@guidepup/guidepup - npm Package Compare versions

Comparing version 0.11.0 to 0.12.0

lib/macOS/VoiceOver/VoiceOver.d.ts

@@ -0,2 +1,6 @@
+import { ClickOptions } from "../../ClickOptions";
+import { CommanderCommands } from "./CommanderCommands";
 import type { CommandOptions } from "../../CommandOptions";
+import { KeyboardCommand } from "../KeyboardCommand";
+import { KeyboardOptions } from "../../KeyboardOptions";
 import { VoiceOverCaption } from "./VoiceOverCaption";
@@ -56,2 +60,123 @@ import { VoiceOverCommander } from "./VoiceOverCommander";
     stop(options?: CommandOptions): Promise<void>;
+    /**
+     * Move the VoiceOver cursor to the previous location.
+     *
+     * Equivalent of executing VO-Left Arrow.
+     *
+     * @param {object} [options] Additional options.
+     */
+    previous(options?: CommandOptions): Promise<void>;
+    /**
+     * Move the VoiceOver cursor to the next location.
+     *
+     * Equivalent of executing VO-Right Arrow.
+     *
+     * @param {object} [options] Additional options.
+     */
+    next(options?: CommandOptions): Promise<void>;
+    /**
+     * Perform the default action for the item in the VoiceOver cursor.
+     *
+     * Equivalent of executing VO-Space bar.
+     *
+     * @param {object} [options] Additional options.
+     */
+    act(options?: CommandOptions): Promise<void>;
+    /**
+     * Interact with the item under the ScreenReader cursor.
+     *
+     * Equivalent of executing VO-Shift-Down Arrow.
+     *
+     * @param {object} [options] Additional options.
+     */
+    interact(options?: CommandOptions): Promise<void>;
+    /**
+     * Stop interacting with the current item.
+     *
+     * Equivalent of executing VO-Shift-Up Arrow.
+     *
+     * @param {object} [options] Additional options.
+     */
+    stopInteracting(options?: CommandOptions): Promise<void>;
+    /**
+     * Press a key on the focused item.
+     *
+     * `key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
+     * value or a single character to generate the text for. A superset of the `key` values can be found
+     * [on the MDN key values page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
+     *
+     * `F1` - `F20`, `Digit0` - `Digit9`, `KeyA` - `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
+     * `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
+     *
+     * Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `Command`.
+     *
+     * Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
+     *
+     * If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective
+     * texts.
+     *
+     * Shortcuts such as `key: "Control+f"` or `key: "Control+Shift+f"` are supported as well. When specified with the
+     * modifier, modifier is pressed and being held while the subsequent key is being pressed.
+     *
+     * ```ts
+     * await keyboard.press("Control+f");
+     * ```
+     *
+     * @param {string} key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
+     * @param {object} [options] Additional options.
+     */
+    press(key: string, options?: KeyboardOptions): Promise<void>;
+    /**
+     * Type text into the focused item.
+     *
+     * To press a special key, like `Control` or `ArrowDown`, use `keyboard.press(key[, options])`.
+     *
+     * ```ts
+     * await keyboard.type("my-username");
+     * await keyboard.press("Enter");
+     * ```
+     *
+     * @param {string} text Text to type into the focused element.
+     * @param {object} [options] Additional options.
+     */
+    type(text: string, options?: KeyboardOptions): Promise<void>;
+    /**
+     * Perform a VoiceOver command.
+     *
+     * @param {any} command VoiceOver keyboard command or commander command to execute.
+     * @param {object} [options] Additional options.
+     */
+    perform(command: KeyboardCommand | CommanderCommands, options?: CommandOptions): Promise<void>;
+    /**
+     * Click the mouse.
+     *
+     * @param {object} [options] Click options.
+     */
+    click(options?: ClickOptions): Promise<void>;
+    /**
+     * Get the last spoken phrase.
+     *
+     * @param {object} [options] Additional options.
+     * @returns {Promise<string>} The last spoken phrase.
+     */
+    lastSpokenPhrase(options?: CommandOptions): Promise<string>;
+    /**
+     * Get the text of the item in the VoiceOver cursor.
+     *
+     * @param {object} [options] Additional options.
+     * @returns {Promise<string>} The item's text.
+     */
+    itemText(options?: CommandOptions): Promise<string>;
+    /**
+     * Get the log of all spoken phrases for this VoiceOver instance.
+     *
+     * @returns {string[]} The spoken phrase log.
+     */
+    spokenPhraseLog(): string[];
+    /**
+     * Get the log of all visited item text for this VoiceOver instance.
+     *
+     * @returns {string[]} The item text log.
+     */
+    itemTextLog(): string[];
 }

lib/macOS/VoiceOver/VoiceOver.js

@@ -15,2 +15,3 @@ "use strict";
 const errors_1 = require("../errors");
+const isKeyboard_1 = require("../../isKeyboard");
 const isMacOS_1 = require("../isMacOS");
@@ -96,2 +97,152 @@ const LogStore_1 = require("../../LogStore");
     }
+    /**
+     * Move the VoiceOver cursor to the previous location.
+     *
+     * Equivalent of executing VO-Left Arrow.
+     *
+     * @param {object} [options] Additional options.
+     */
+    async previous(options) {
+        return await this.cursor.previous(options);
+    }
+    /**
+     * Move the VoiceOver cursor to the next location.
+     *
+     * Equivalent of executing VO-Right Arrow.
+     *
+     * @param {object} [options] Additional options.
+     */
+    async next(options) {
+        return await this.cursor.next(options);
+    }
+    /**
+     * Perform the default action for the item in the VoiceOver cursor.
+     *
+     * Equivalent of executing VO-Space bar.
+     *
+     * @param {object} [options] Additional options.
+     */
+    async act(options) {
+        return await this.cursor.act(options);
+    }
+    /**
+     * Interact with the item under the ScreenReader cursor.
+     *
+     * Equivalent of executing VO-Shift-Down Arrow.
+     *
+     * @param {object} [options] Additional options.
+     */
+    async interact(options) {
+        return await this.cursor.interact(options);
+    }
+    /**
+     * Stop interacting with the current item.
+     *
+     * Equivalent of executing VO-Shift-Up Arrow.
+     *
+     * @param {object} [options] Additional options.
+     */
+    async stopInteracting(options) {
+        return await this.cursor.stopInteracting(options);
+    }
+    /**
+     * Press a key on the focused item.
+     *
+     * `key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
+     * value or a single character to generate the text for. A superset of the `key` values can be found
+     * [on the MDN key values page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
+     *
+     * `F1` - `F20`, `Digit0` - `Digit9`, `KeyA` - `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
+     * `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
+     *
+     * Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `Command`.
+     *
+     * Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
+     *
+     * If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective
+     * texts.
+     *
+     * Shortcuts such as `key: "Control+f"` or `key: "Control+Shift+f"` are supported as well. When specified with the
+     * modifier, modifier is pressed and being held while the subsequent key is being pressed.
+     *
+     * ```ts
+     * await keyboard.press("Control+f");
+     * ```
+     *
+     * @param {string} key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
+     * @param {object} [options] Additional options.
+     */
+    async press(key, options) {
+        return await this.keyboard.press(key, options);
+    }
+    /**
+     * Type text into the focused item.
+     *
+     * To press a special key, like `Control` or `ArrowDown`, use `keyboard.press(key[, options])`.
+     *
+     * ```ts
+     * await keyboard.type("my-username");
+     * await keyboard.press("Enter");
+     * ```
+     *
+     * @param {string} text Text to type into the focused element.
+     * @param {object} [options] Additional options.
+     */
+    async type(text, options) {
+        return await this.keyboard.type(text, options);
+    }
+    /**
+     * Perform a VoiceOver command.
+     *
+     * @param {any} command VoiceOver keyboard command or commander command to execute.
+     * @param {object} [options] Additional options.
+     */
+    async perform(command, options) {
+        if ((0, isKeyboard_1.isKeyboard)(command)) {
+            return await this.keyboard.perform(command, options);
+        }
+        return this.commander.perform(command, options);
+    }
+    /**
+     * Click the mouse.
+     *
+     * @param {object} [options] Click options.
+     */
+    async click(options) {
+        return await this.mouse.click(options);
+    }
+    /**
+     * Get the last spoken phrase.
+     *
+     * @param {object} [options] Additional options.
+     * @returns {Promise<string>} The last spoken phrase.
+     */
+    async lastSpokenPhrase(options) {
+        return await this.caption.lastSpokenPhrase(options);
+    }
+    /**
+     * Get the text of the item in the VoiceOver cursor.
+     *
+     * @param {object} [options] Additional options.
+     * @returns {Promise<string>} The item's text.
+     */
+    async itemText(options) {
+        return await this.caption.itemText(options);
+    }
+    /**
+     * Get the log of all spoken phrases for this VoiceOver instance.
+     *
+     * @returns {string[]} The spoken phrase log.
+     */
+    spokenPhraseLog() {
+        return this.caption.spokenPhraseLog();
+    }
+    /**
+     * Get the log of all visited item text for this VoiceOver instance.
+     *
+     * @returns {string[]} The item text log.
+     */
+    itemTextLog() {
+        return this.caption.itemTextLog();
+    }
 };
@@ -98,0 +249,0 @@ VoiceOver = VoiceOver_1 = __decorate([

lib/ScreenReader.d.ts

@@ -0,2 +1,4 @@
+import type { ClickOptions } from "./ClickOptions";
 import type { CommandOptions } from "./CommandOptions";
+import type { KeyboardOptions } from "./KeyboardOptions";
 import type { ScreenReaderCaption } from "./ScreenReaderCaption";
@@ -35,2 +37,113 @@ import type { ScreenReaderCursor } from "./ScreenReaderCursor";
     stop(options?: CommandOptions): Promise<void>;
+    /**
+     * Move the ScreenReader cursor to the previous location.
+     *
+     * @param {object} [options] Additional options.
+     */
+    previous(options?: CommandOptions): Promise<void>;
+    /**
+     * Move the ScreenReader cursor to the next location.
+     *
+     * @param {object} [options] Additional options.
+     */
+    next(options?: CommandOptions): Promise<void>;
+    /**
+     * Perform the default action for the item in the ScreenReader cursor.
+     *
+     * @param {object} [options] Additional options.
+     */
+    act(options?: CommandOptions): Promise<void>;
+    /**
+     * Interact with the item under the ScreenReader cursor.
+     *
+     * @param {object} [options] Additional options.
+     */
+    interact(options?: CommandOptions): Promise<void>;
+    /**
+     * Stop interacting with the current item.
+     *
+     * @param {object} [options] Additional options.
+     */
+    stopInteracting(options?: CommandOptions): Promise<void>;
+    /**
+     * Press a key on the focused item.
+     *
+     * `key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
+     * value or a single character to generate the text for. A superset of the `key` values can be found
+     * [on the MDN key values page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
+     *
+     * `F1` - `F20`, `Digit0` - `Digit9`, `KeyA` - `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
+     * `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
+     *
+     * Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`.
+     *
+     * Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
+     *
+     * If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective
+     * texts.
+     *
+     * Shortcuts such as `key: "Control+f"` or `key: "Control+Shift+f"` are supported as well. When specified with the
+     * modifier, modifier is pressed and being held while the subsequent key is being pressed.
+     *
+     * ```ts
+     * await keyboard.press("Control+f");
+     * ```
+     *
+     * @param {string} key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
+     * @param {object} [options] Additional options.
+     */
+    press(key: string, options?: KeyboardOptions): Promise<void>;
+    /**
+     * Type text into the focused item.
+     *
+     * To press a special key, like `Control` or `ArrowDown`, use `keyboard.press(key[, options])`.
+     *
+     * ```ts
+     * await keyboard.type("my-username");
+     * await keyboard.press("Enter");
+     * ```
+     *
+     * @param {string} text Text to type into the focused element.
+     * @param {object} [options] Additional options.
+     */
+    type(text: string, options?: KeyboardOptions): Promise<void>;
+    /**
+     * Perform a ScreenReader command.
+     *
+     * @param {any} command ScreenReader keyboard command or commander command to execute.
+     * @param {object} [options] Additional options.
+     */
+    perform(command: unknown, options?: CommandOptions): Promise<void>;
+    /**
+     * Click the mouse.
+     *
+     * @param {object} [options] Click options.
+     */
+    click(options?: ClickOptions): Promise<void>;
+    /**
+     * Get the last spoken phrase.
+     *
+     * @param {object} [options] Additional options.
+     * @returns {Promise<string>} The last spoken phrase.
+     */
+    lastSpokenPhrase(options?: CommandOptions): Promise<string>;
+    /**
+     * Get the text of the item in the ScreenReader cursor.
+     *
+     * @param {object} [options] Additional options.
+     * @returns {Promise<string>} The item's text.
+     */
+    itemText(options?: CommandOptions): Promise<string>;
+    /**
+     * Get the log of all spoken phrases for this ScreenReader instance.
+     *
+     * @returns {string[]} The spoken phrase log.
+     */
+    spokenPhraseLog(): string[];
+    /**
+     * Get the log of all visited item text for this ScreenReader instance.
+     *
+     * @returns {string[]} The item text log.
+     */
+    itemTextLog(): string[];
 }
@@ -37,0 +150,0 @@ export interface ScreenReader {

package.json

 {
   "name": "@guidepup/guidepup",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Screen-reader driver for automation.",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

README.md

@@ -39,6 +39,6 @@ <h1 align="center">Guidepup</h1>
   // Navigate your environment with screen-readers just as your users do 🏎
-  await vo.cursor.next();
+  await vo.next();
 
   // Assert on what your users really see and hear when using screen-readers 👂
-  console.log(await vo.caption.lastSpokenPhrase());
+  console.log(await vo.lastSpokenPhrase());
 
@@ -70,2 +70,9 @@ await vo.stop();
 
+If you are using GitHub Actions, check out the dedicated [`guidepup/setup-action`](https://github.com/marketplace/actions/guidepup-setup) to setup your CI ready for screen-reader automation.
+
+```yaml
+- name: Setup Environment
+  uses: guidepup/setup-action@0.1.3
+```
+
 ## Roadmap 🐾
@@ -72,0 +79,0 @@

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

391133

increased by4.09%

Number of package files

180

increased by2.27%

Lines of code

7365

increased by5.85%

Number of lines in readme file

109

increased by6.86%

Number of medium supply chain risk alerts

9

decreased by-10%

No dependency changes