VoiceOver

A VoiceOver instance can be used to launch and control VoiceOver on macOS.

Here's a typical example using a VoiceOver instance:

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Contents:

voiceOver.commanderCommands

Getter for all VoiceOver commander commands.

Use with the VoiceOver perform command to invoke a Commander action:

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move down.
  await voiceOver.perform(voiceOver.commanderCommands.MOVE_DOWN);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: VoiceOverCommanderCommands

voiceOver.keyboardCommands

Getter for all VoiceOver keyboard commands.

Use with the VoiceOver perform command to invoke a keyboard action:

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.perform(voiceOver.keyboardCommands.moveToNext);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: voiceOverKeyCodeCommands

voiceOver.name

Getter for the screen reader name "VoiceOver".

import { voiceOver } from "@guidepup/guidepup";

console.log(voiceOver.name); // "VoiceOver"

Returns: string

voiceOver.version

Getter for the screen reader version.

import { voiceOver } from "@guidepup/guidepup";

console.log(voiceOver.version);

Returns: string

voiceOver.act([options])

Perform the default action for the item in the VoiceOver cursor.

Equivalent of executing VO-Space bar.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Perform the default action for the item.
  await voiceOver.act();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.capture(action[, options])

Capture VoiceOver output produced while an action runs. The action can be performed using an external automation tool such as Playwright. The returned capture contains the action's result and the VoiceOver output associated with the action.

import { test } from "@playwright/test";
import { voiceOver } from "@guidepup/guidepup";

test("capture VoiceOver output while clicking a button", async ({ page }) => {
  await voiceOver.start();

  const capture = await voiceOver.capture(() =>
    page
      .getByRole("button", {
        name: "Submit",
      })
      .click(),
  );
  console.log(capture);

  await voiceOver.stop();
});

Parameters:

action () => Promise<T> | T The action to perform while capturing VoiceOver output.
Optional: options CommandOptions Capture options.

Returns: Promise<Capture<T>> The action's result and captured VoiceOver output.

voiceOver.clearItemTextLog()

Clear the log of all visited item text for this VoiceOver instance.

For VoiceOver this is distinct from spokenPhraseLog.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // ... perform some commands.

  // Clear the item text log.
  await voiceOver.clearItemTextLog();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: Promise<void>

voiceOver.clearSpokenPhraseLog()

Clear the log of all spoken phrases for this VoiceOver instance.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // ... perform some commands.

  // Clear the spoken phrase log.
  await voiceOver.clearSpokenPhraseLog();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: Promise<void>

voiceOver.click([options])

Click the mouse.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Left-click the mouse.
  await voiceOver.click();

  // Left-click the mouse using specific options.
  await voiceOver.click({ button: "left", clickCount: 1 });

  // Double-right-click the mouse.
  await voiceOver.click({ button: "right", clickCount: 2 });

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options ClickOptions Click options.

Returns: Promise<void>

voiceOver.copyLastSpokenPhrase([options])

Copy the last spoken phrase to the Clipboard (also called the "Pasteboard").

This command is specific to the VoiceOver screen reader.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Copy the phrase spoken by VoiceOver from moving to the next item above to
  // the Clipboard.
  await voiceOver.copyLastSpokenPhrase();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.default()

Detect whether VoiceOver is the default screen reader for the current OS:

false for Windows
true for macOS
false for Linux

import { voiceOver } from "@guidepup/guidepup";

const isVoiceOverDefaultScreenReader = voiceOver.default();

console.log(isVoiceOverDefaultScreenReader);

Returns: boolean

voiceOver.detect()

Detect whether VoiceOver is supported for the current OS:

false for Windows
true for macOS
false for Linux

import { voiceOver } from "@guidepup/guidepup";

const isVoiceOverSupportedScreenReader = voiceOver.detect();

console.log(isVoiceOverSupportedScreenReader);

Returns: boolean

voiceover.getSetting(key)

Returns the value of a setting for this VoiceOver instance.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Log the value for the 'SCRCUserDefaultsCursorTrackingEnabled' setting.
  console.log(voiceOver.getSetting("SCRCUserDefaultsCursorTrackingEnabled"));

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

key string The setting name.

Returns: [unknown] The setting value.

voiceover.getSettings()

Returns all the current settings for this VoiceOver instance.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Log current settings.
  console.log(voiceOver.getSettings());

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: [Record]<string, [unknown]> Current settings values.

voiceOver.interact([options])

Interact with the item under the VoiceOver cursor.

Equivalent of executing VO-Shift-Down Arrow.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Interact with the item.
  await voiceOver.interact();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.itemText()

Get the text of the item in the VoiceOver cursor.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Get the text (if any) for the item currently in focus by the VoiceOver
  // cursor.
  const itemText = await voiceOver.itemText();
  console.log(itemText);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: Promise<string> The item's text.

voiceOver.itemTextLog()

Get the log of all visited item text for this VoiceOver instance.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move through several items.
  for (let i = 0; i < 10; i++) {
    await voiceOver.next();
  }

  // Get the text (if any) for all the items visited by the VoiceOver cursor.
  const itemTextLog = await voiceOver.itemTextLog();
  console.log(itemTextLog);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: Promise<Array<string>> The item text log.

voiceOver.lastSpokenPhrase()

Get the last spoken phrase.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Get the phrase spoken by VoiceOver from moving to the next item above.
  const lastSpokenPhrase = await voiceOver.lastSpokenPhrase();
  console.log(lastSpokenPhrase);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: Promise<string> The last spoken phrase.

voiceOver.next([options])

Move the VoiceOver cursor to the next location.

Equivalent of executing VO-Right Arrow.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.nextHeading([options])

Move the VoiceOver cursor to the next heading.

Equivalent of executing VO-Command-H.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next heading.
  await voiceOver.nextHeading();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.nextLandmark([options])

Move the VoiceOver cursor to the next landmark.

Equivalent of executing VO-Command-N.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next landmark.
  await voiceOver.nextLandmark();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.nextLink([options])

Move the VoiceOver cursor to the next link.

Equivalent of executing VO-Command-L.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next link.
  await voiceOver.nextLink();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.perform(command[, options])

Perform a VoiceOver command.

The command can be a MacOSKeyCodeCommand, MacOSKeystrokeCommand, or VoiceOverCommanderCommands.

import { voiceOver, VoiceOverCommanderCommands } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Type using a custom keystroke command.
  await voiceOver.perform({ characters: "my-username" });

  // Keyboard commands available on the VoiceOver instance.
  await voiceOver.perform(
    voiceOver.keyboardCommands.performDefaultActionForItem,
  );

  // Commander commands available on the VoiceOver instance.
  await voiceOver.perform(voiceOver.commanderCommands.MOVE_DOWN);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

command MacOSKeyboardCommand | VoiceOverCommanderCommands VoiceOver keyboard command or commander command to execute.
Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.press(key[, options])

Press a key on the focused item.

key can specify the intended 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. 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.

See MacOSKeyCodes for the full range of available keys.

Following modification shortcuts are also supported: Shift, Control, Alt, Meta, Command.

See MacOSModifiers for the full range of available modifiers.

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: "Command+f" or key: "Command+Shift+f" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Open a find text modal.
  await voiceOver.press("Command+f");

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

key string Name of the key to press or a character to generate, such as ArrowLeft or a.
Optional: options KeyboardOptions Additional options.

Returns: Promise<void>

voiceOver.previous([options])

Move the VoiceOver cursor to the previous location.

Equivalent of executing VO-Left Arrow.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the previous item.
  await voiceOver.previous();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.previousHeading([options])

Move the VoiceOver cursor to the previous heading.

Equivalent of executing VO-Command-Shift-H.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the previous heading.
  await voiceOver.previousHeading();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.previousLandmark([options])

Move the VoiceOver cursor to the previous landmark.

Equivalent of executing VO-Command-Shift-N.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the previous landmark.
  await voiceOver.previousLandmark();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.previousLink([options])

Move the VoiceOver cursor to the previous link.

Equivalent of executing VO-Command-Shift-L.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the previous link.
  await voiceOver.previousLink();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.saveLastSpokenPhrase([options])

Save the last spoken phrase and the crash log to a file on the desktop for troubleshooting.

This command is specific to the VoiceOver screen reader.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Save the phrase spoken by VoiceOver from moving to the next item above to
  // a file on the desktop.
  await voiceOver.saveLastSpokenPhrase();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.spokenPhraseLog()

Get the log of all spoken phrases for this VoiceOver instance.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move through several items.
  for (let i = 0; i < 10; i++) {
    await voiceOver.next();
  }

  // Get the phrase spoken by VoiceOver from moving through the items above.
  const spokenPhraseLog = await voiceOver.spokenPhraseLog();
  console.log(spokenPhraseLog);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: Promise<Array<string>> The spoken phrase log.

voiceOver.start([options])

Turn VoiceOver on.

By default, capture is set to "initial": it captures the first page of output, but not subsequent content. Set capture to true for full capture or false to disable capture.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // ... perform some commands.

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options StartOptions Additional options.

Returns: Promise<void>

voiceOver.stop([options])

Turn VoiceOver off.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // ... perform some commands.

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options Omit<CommandOptions, "capture"> Additional options. capture is not supported when stopping VoiceOver.

Returns: Promise<void>

voiceOver.stopInteracting([options])

Stop interacting with the current item.

Equivalent of executing VO-Shift-Up Arrow.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Interact with the item.
  await voiceOver.interact();

  // ... perform some commands.

  // Stop interacting with the item.
  await voiceOver.stopInteracting();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<void>

voiceOver.takeCursorScreenshot([options])

Takes a screenshot of the item focussed in the VoiceOver cursor and returns the path to screenshot file.

This command is specific to the VoiceOver screen reader.

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.next();

  // Take a screenshot of the item focussed in the VoiceOver cursor.
  const screenshotFile = await voiceOver.takeCursorScreenshot();
  console.log(screenshotFile);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Optional: options CommandOptions Additional options.

Returns: Promise<string> The path to the screenshot file.

voiceOver.type(text[, options])

Type text into the focused item.

To press a special key, like Control or ArrowDown, use voiceOver.press(key[, options]).

import { voiceOver } from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Type a username and key Enter.
  await voiceOver.type("my-username");
  await voiceOver.press("Enter");

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

text string Text to type into the focused item.
Optional: options KeyboardOptions Additional options, including an application to target.

Returns: Promise<void>

voiceOver.commanderCommands​

voiceOver.keyboardCommands​

voiceOver.name​

voiceOver.version​

voiceOver.act([options])​

voiceOver.capture(action[, options])​

voiceOver.clearItemTextLog()​

voiceOver.clearSpokenPhraseLog()​

voiceOver.click([options])​

voiceOver.copyLastSpokenPhrase([options])​

voiceOver.default()​

voiceOver.detect()​

voiceover.getSetting(key)​

voiceover.getSettings()​

voiceOver.interact([options])​

voiceOver.itemText()​

voiceOver.itemTextLog()​

voiceOver.lastSpokenPhrase()​

voiceOver.next([options])​

voiceOver.nextHeading([options])​

voiceOver.nextLandmark([options])​

voiceOver.nextLink([options])​

voiceOver.perform(command[, options])​

voiceOver.press(key[, options])​

voiceOver.previous([options])​

voiceOver.previousHeading([options])​

voiceOver.previousLandmark([options])​

voiceOver.previousLink([options])​

voiceOver.saveLastSpokenPhrase([options])​

voiceOver.spokenPhraseLog()​

voiceOver.start([options])​

voiceOver.stop([options])​

voiceOver.stopInteracting([options])​

voiceOver.takeCursorScreenshot([options])​

voiceOver.type(text[, options])​

voiceOver.commanderCommands

voiceOver.keyboardCommands

voiceOver.name

voiceOver.version

voiceOver.act([options])

voiceOver.capture(action[, options])

voiceOver.clearItemTextLog()

voiceOver.clearSpokenPhraseLog()

voiceOver.click([options])

voiceOver.copyLastSpokenPhrase([options])

voiceOver.default()

voiceOver.detect()

voiceover.getSetting(key)

voiceover.getSettings()

voiceOver.interact([options])

voiceOver.itemText()

voiceOver.itemTextLog()

voiceOver.lastSpokenPhrase()

voiceOver.next([options])

voiceOver.nextHeading([options])

voiceOver.nextLandmark([options])

voiceOver.nextLink([options])

voiceOver.perform(command[, options])

voiceOver.press(key[, options])

voiceOver.previous([options])

voiceOver.previousHeading([options])

voiceOver.previousLandmark([options])

voiceOver.previousLink([options])

voiceOver.saveLastSpokenPhrase([options])

voiceOver.spokenPhraseLog()

voiceOver.start([options])

voiceOver.stop([options])

voiceOver.stopInteracting([options])

voiceOver.takeCursorScreenshot([options])

voiceOver.type(text[, options])