Skip to main content

ScreenReader

Implements: IScreenReader

A ScreenReader instance can be used to launch and control the default screen reader for the environment: NVDA for Windows, Orca for Linux, and VoiceOver for macOS.

Here's a typical example using a ScreenReader instance:

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

See also:

Contents:

screenReader.name​

Getter for the screen reader name: "NVDA", "Orca", or "VoiceOver".

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

console.log(screenReader.name); // "NVDA", "Orca", or "VoiceOver"

Returns: string

screenReader.version​

Getter for the screen reader version.

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

console.log(screenReader.version);

Returns: string

screenReader.act([options])​

Perform the default action for the item in the screen reader cursor.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.capture(action[, options])​

Capture screen reader 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 screen reader output associated with the action.

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

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

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

  await screenReader.stop();
});

Parameters:

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

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

screenReader.clearItemTextLog()​

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

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // ... perform some commands.

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<void>

screenReader.clearSpokenPhraseLog()​

Clear the log of all spoken phrases for this screen reader instance.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // ... perform some commands.

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<void>

screenReader.click([options])​

Click the mouse.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

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

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.default()​

Detect whether the screen reader is the default screen reader for the current OS.

When using a ScreenReader instance this will always return true.

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

(() => {
  const isDefaultScreenReader = screenReader.default();

  console.log(isDefaultScreenReader); // true
})();

Returns: boolean

screenReader.detect()​

Detect whether the screen reader is supported for the current OS.

When using a ScreenReader instance this will always return true.

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

const isSupportedScreenReader = screenReader.detect();

console.log(isSupportedScreenReader);

Returns: boolean

screenReader.getSetting(key)​

Returns the value of a setting for this screen reader instance.

Parameters:

  • key string The setting name.

Returns: unknown The setting value.

screenReader.getSettings()​

Returns all the current settings for this screen reader instance.

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

screenReader.interact([options])​

Interact with the item under the screen reader cursor.

VoiceOver and Orca require an additional command to interact with the item in the screen reader cursor. NVDA does not require this command.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Interact with the item. This is a no-op on NVDA.
  await screenReader.interact();

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.itemText()​

Get the text of the item in the screen reader cursor.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

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

  // Stop the screen reader.
  await screenReader.stop();
})();

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

screenReader.itemTextLog()​

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

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

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

  // Stop the screen reader.
  await screenReader.stop();
})();

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

screenReader.lastSpokenPhrase()​

Get the last spoken phrase.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<string> The last spoken phrase.

screenReader.navigateNextUntil(matcher[, options])​

Move the screen reader cursor to the next location until its spoken phrase matches the provided matcher.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next item containing the exact spoken phrase.
  await screenReader.navigateNextUntil(/Submit/);

  // Stop the screen reader.
  await screenReader.stop();
})();

The matcher can be an exact matching string, a regular expression, or a function that returns whether the spoken phrase matches. The command throws if no match is found within maxNavigationAttempts (default is 10). If the last spoken phrase is already a match then no navigation occurs.

Parameters:

screenReader.navigateNextHeadingUntil(matcher[, options])​

Move the screen reader cursor to the next heading until its spoken phrase matches the provided matcher.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next heading with a matching spoken phrase.
  await screenReader.navigateNextHeadingUntil(/Account/);

  // Stop the screen reader.
  await screenReader.stop();
})();

The matcher can be an exact matching string, a regular expression, or a function that returns whether the spoken phrase matches. The command throws if no match is found within maxNavigationAttempts (default is 10). If the last spoken phrase is already a match then no navigation occurs.

Parameters:

Returns: Promise<void>

screenReader.navigateNextLandmarkUntil(matcher[, options])​

Move the screen reader cursor to the next landmark until its spoken phrase matches the provided matcher.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next landmark with a matching spoken phrase.
  await screenReader.navigateNextLandmarkUntil(/Main/);

  // Stop the screen reader.
  await screenReader.stop();
})();

The matcher can be an exact matching string, a regular expression, or a function that returns whether the spoken phrase matches. The command throws if no match is found within maxNavigationAttempts (default is 10). If the last spoken phrase is already a match then no navigation occurs.

Parameters:

Returns: Promise<void>

Move the screen reader cursor to the next link until its spoken phrase matches the provided matcher.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next link with a matching spoken phrase.
  await screenReader.navigateNextLinkUntil(/Home/);

  // Stop the screen reader.
  await screenReader.stop();
})();

The matcher can be an exact matching string, a regular expression, or a function that returns whether the spoken phrase matches. The command throws if no match is found within maxNavigationAttempts (default is 10). If the last spoken phrase is already a match then no navigation occurs.

Parameters:

Returns: Promise<void>

screenReader.navigatePreviousUntil(matcher[, options])​

Move the screen reader cursor to the previous location until its spoken phrase matches the provided matcher.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the previous item containing the exact spoken phrase.
  await screenReader.navigatePreviousUntil(/Submit/);

  // Stop the screen reader.
  await screenReader.stop();
})();

The matcher can be an exact matching string, a regular expression, or a function that returns whether the spoken phrase matches. The command throws if no match is found within maxNavigationAttempts (default is 10). If the last spoken phrase is already a match then no navigation occurs.

Parameters:

screenReader.navigatePreviousHeadingUntil(matcher[, options])​

Move the screen reader cursor to the previous heading until its spoken phrase matches the provided matcher.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the previous heading with a matching spoken phrase.
  await screenReader.navigatePreviousHeadingUntil(/Account/);

  // Stop the screen reader.
  await screenReader.stop();
})();

The matcher can be an exact matching string, a regular expression, or a function that returns whether the spoken phrase matches. The command throws if no match is found within maxNavigationAttempts (default is 10). If the last spoken phrase is already a match then no navigation occurs.

Parameters:

Returns: Promise<void>

screenReader.navigatePreviousLandmarkUntil(matcher[, options])​

Move the screen reader cursor to the previous landmark until its spoken phrase matches the provided matcher.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the previous landmark with a matching spoken phrase.
  await screenReader.navigatePreviousLandmarkUntil(/Main/);

  // Stop the screen reader.
  await screenReader.stop();
})();

The matcher can be an exact matching string, a regular expression, or a function that returns whether the spoken phrase matches. The command throws if no match is found within maxNavigationAttempts (default is 10). If the last spoken phrase is already a match then no navigation occurs.

Parameters:

Returns: Promise<void>

Move the screen reader cursor to the previous link until its spoken phrase matches the provided matcher.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the previous link with a matching spoken phrase.
  await screenReader.navigatePreviousLinkUntil(/Home/);

  // Stop the screen reader.
  await screenReader.stop();
})();

The matcher can be an exact matching string, a regular expression, or a function that returns whether the spoken phrase matches. The command throws if no match is found within maxNavigationAttempts (default is 10). If the last spoken phrase is already a match then no navigation occurs.

Parameters:

Returns: Promise<void>

screenReader.next([options])​

Move the screen reader cursor to the next location.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.nextHeading([options])​

Move the screen reader cursor to the next heading.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.nextLandmark([options])​

Move the screen reader cursor to the next landmark.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

Move the screen reader cursor to the next link.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.perform(command[, options])​

Perform a screen reader command.

import {
  NVDAKeyCodeCommands,
  orcaKeyCodeCommands,
  voiceOverKeyCodeCommands,
} from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  if (screenReader.name === "NVDA") {
    await screenReader.perform(NVDAKeyCodeCommands.performDefaultActionForItem);
  } else if (screenReader.name === "Orca") {
    await screenReader.perform(orcaKeyCodeCommands.PerformAction);
  } else if (screenReader.name === "VoiceOver") {
    await screenReader.perform(
      voiceOverKeyCodeCommands.performDefaultActionForItem,
    );
  }

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.press(key[, options])​

Press a key on the focused item.

Orca does not currently implement this method; calling it while Orca is active throws an error.

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.

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.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Open a find text modal.
  await screenReader.press("Control+f");

  // Stop the screen reader.
  await screenReader.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>

screenReader.previous([options])​

Move the screen reader cursor to the previous location.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.previousHeading([options])​

Move the screen reader cursor to the previous heading.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the previous heading.
  await screenReader.nextHeading();

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.previousLandmark([options])​

Move the screen reader cursor to the previous landmark.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

Move the screen reader cursor to the previous link.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.spokenPhraseLog()​

Get the log of all spoken phrases for this screen reader instance.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

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

  // Stop the screen reader.
  await screenReader.stop();
})();

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

screenReader.start([options])​

Turn the screen reader on.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // ... perform some commands.

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.stop([options])​

Turn the screen reader off.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // ... perform some commands.

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.stopInteracting([options])​

Stop interacting with the current item.

VoiceOver and Orca require an additional command to stop interacting with the item in the screen reader cursor. NVDA does not require this command.

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Interact with the item. This is a no-op on NVDA.
  await screenReader.interact();

  // ... perform some commands.

  // Stop interacting with the item. This is a no-op on NVDA.
  await screenReader.stopInteracting();

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

Returns: Promise<void>

screenReader.type(text[, options])​

Type text into the focused item.

Orca does not currently implement this method; calling it while Orca is active throws an error.

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

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

(async () => {
  // Start the screen reader.
  await screenReader.start();

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

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

  • text string Text to type into the focused item.
  • Optional: options CommandOptions Additional options.

Returns: Promise<void>