NVDA

A NVDA instance can be used to launch and control NVDA on Windows.

Here's a typical example using a NVDA instance:

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Contents:

nvda.keyboardCommands

Getter for all NVDA keyboard commands.

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Returns: NVDAKeyCodeCommands

nvda.name

Getter for the screen reader name "NVDA".

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

console.log(nvda.name); // "NVDA"

Returns: string

nvda.version

Getter for the screen reader version.

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

console.log(nvda.version);

Returns: string

nvda.act([options])

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

Equivalent of executing Enter.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.capture(action[, options])

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

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

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

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

  await nvda.stop();
});

Parameters:

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

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

nvda.clearItemTextLog()

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

For NVDA this is the same as clearSpokenPhraseLog.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // ... perform some commands.

  // Clear the spoken phrase log.
  await nvda.clearItemTextLog();

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.clearSpokenPhraseLog()

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // ... perform some commands.

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

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.click([options])

Click the mouse.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options ClickOptions Click options.

Returns: Promise<void>

nvda.default()

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

true for Windows
false for macOS
false for Linux

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

const isNVDADefaultScreenReader = nvda.default();

console.log(isNVDADefaultScreenReader);

Returns: boolean

nvda.detect()

Detect whether NVDA is supported on the current machine. NVDA must be installed for this check to return true.

true for Windows when NVDA is installed
false for macOS
false for Linux

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

const isNVDASupportedScreenReader = nvda.detect();

console.log(isNVDASupportedScreenReader);

Returns: boolean

nvda.getSetting(key)

Returns the value of a setting for this NVDA instance.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // Log the value for the 'virtualBuffers.autoSayAllOnPageLoad' setting.
  console.log(nvda.getSetting("virtualBuffers.autoSayAllOnPageLoad"));

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

key string The setting name.

Returns: unknown The setting value.

nvda.getSettings()

Returns all the current settings for this NVDA instance.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

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

nvda.interact()

No-op to provide same API across screen readers.

NVDA does not require users to perform an additional command to interact with the item in the NVDA cursor.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Interact with the item - does nothing on NVDA.
  await nvda.interact();

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.itemText()

Get the text of the item in the NVDA cursor.

For NVDA this is the same as lastSpokenPhrase.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

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

nvda.itemTextLog()

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

For NVDA this is the same as spokenPhraseLog.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

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

nvda.lastSpokenPhrase()

Get the last spoken phrase.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<string> The last spoken phrase.

nvda.navigateNextUntil(matcher[, options])

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.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:

matcher SpokenPhraseMatcher Matcher to navigate until reached.
Optional: options NavigateOptions Additional options.

nvda.navigateNextHeadingUntil(matcher[, options])

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

matcher SpokenPhraseMatcher Matcher to navigate until reached.
Optional: options NavigateOptions Additional options.

Returns: Promise<void>

nvda.navigateNextLandmarkUntil(matcher[, options])

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

matcher SpokenPhraseMatcher Matcher to navigate until reached.
Optional: options NavigateOptions Additional options.

Returns: Promise<void>

nvda.navigateNextLinkUntil(matcher[, options])

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

matcher SpokenPhraseMatcher Matcher to navigate until reached.
Optional: options NavigateOptions Additional options.

Returns: Promise<void>

nvda.navigatePreviousUntil(matcher[, options])

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

matcher SpokenPhraseMatcher Matcher to navigate until reached.
Optional: options NavigateOptions Additional options.

nvda.navigatePreviousHeadingUntil(matcher[, options])

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

matcher SpokenPhraseMatcher Matcher to navigate until reached.
Optional: options NavigateOptions Additional options.

Returns: Promise<void>

nvda.navigatePreviousLandmarkUntil(matcher[, options])

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

matcher SpokenPhraseMatcher Matcher to navigate until reached.
Optional: options NavigateOptions Additional options.

Returns: Promise<void>

nvda.navigatePreviousLinkUntil(matcher[, options])

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

matcher SpokenPhraseMatcher Matcher to navigate until reached.
Optional: options NavigateOptions Additional options.

Returns: Promise<void>

nvda.next([options])

Move the NVDA cursor to the next location.

Equivalent of executing Down Arrow.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.nextHeading([options])

Move the NVDA cursor to the next heading.

Equivalent of executing H.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.nextLandmark([options])

Move the NVDA cursor to the next landmark.

Equivalent of executing D.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.nextLink([options])

Move the NVDA cursor to the next link.

Equivalent of executing K.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.perform(command[, options])

Perform a NVDA command.

The command can be a WindowsKeyCodeCommand or WindowsKeystrokeCommand.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Keyboard commands available on the NVDA instance.
  await nvda.perform(nvda.keyboardCommands.performDefaultActionForItem);

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

command WindowsKeyCodeCommand | WindowsKeystrokeCommand NVDA keyboard command.
Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.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 WindowsKeyCodes for the full range of available keys.

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

See WindowsModifiers 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: "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 { nvda } from "@guidepup/guidepup";

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

key string Name of the key to press or a character to generate, such as ArrowLeft or a.
Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.previous([options])

Move the NVDA cursor to the previous location.

Equivalent of executing Up Arrow.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.previousHeading([options])

Move the NVDA cursor to the previous heading.

Equivalent of executing Shift-H.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.previousLandmark([options])

Move the NVDA cursor to the previous landmark.

Equivalent of executing Shift-D.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.previousLink([options])

Move the NVDA cursor to the previous link.

Equivalent of executing Shift-K.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.spokenPhraseLog()

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

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

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

nvda.start([options])

Turn NVDA 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 { nvda } from "@guidepup/guidepup";

(async () => {
  // Start NVDA.
  await nvda.start();

  // ... perform some commands.

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

Optional: options Pick<StartOptions, "capture" | "settings"> Capture options.

Returns: Promise<void>

nvda.stop()

Turn NVDA off.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // ... perform some commands.

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.stopInteracting()

No-op to provide same API across screen readers.

NVDA does not require users to perform an additional command to interact with the item in the NVDA cursor.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // Interact with the item - does nothing on NVDA.
  await nvda.interact();

  // ... perform some commands.

  // Stop interacting with the item - does nothing on NVDA.
  await nvda.stopInteracting();

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.type(text[, options])

Type text into the focused item.

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

Each character is typed separately. As a result, lastSpokenPhrase() returns the phrase for the final character; use spokenPhraseLog() to access output for the complete string.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

text string Text to type into the focused item.
Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.keyboardCommands​

nvda.name​

nvda.version​

nvda.act([options])​

nvda.capture(action[, options])​

nvda.clearItemTextLog()​

nvda.clearSpokenPhraseLog()​

nvda.click([options])​

nvda.default()​

nvda.detect()​

nvda.getSetting(key)​

nvda.getSettings()​

nvda.interact()​

nvda.itemText()​

nvda.itemTextLog()​

nvda.lastSpokenPhrase()​

nvda.navigateNextUntil(matcher[, options])​

nvda.navigateNextHeadingUntil(matcher[, options])​

nvda.navigateNextLandmarkUntil(matcher[, options])​

nvda.navigateNextLinkUntil(matcher[, options])​

nvda.navigatePreviousUntil(matcher[, options])​

nvda.navigatePreviousHeadingUntil(matcher[, options])​

nvda.navigatePreviousLandmarkUntil(matcher[, options])​

nvda.navigatePreviousLinkUntil(matcher[, options])​

nvda.next([options])​

nvda.nextHeading([options])​

nvda.nextLandmark([options])​

nvda.nextLink([options])​

nvda.perform(command[, options])​

nvda.press(key[, options])​

nvda.previous([options])​

nvda.previousHeading([options])​

nvda.previousLandmark([options])​

nvda.previousLink([options])​

nvda.spokenPhraseLog()​

nvda.start([options])​

nvda.stop()​

nvda.stopInteracting()​

nvda.type(text[, options])​

nvda.keyboardCommands

nvda.name

nvda.version

nvda.act([options])

nvda.capture(action[, options])

nvda.clearItemTextLog()

nvda.clearSpokenPhraseLog()

nvda.click([options])

nvda.default()

nvda.detect()

nvda.getSetting(key)

nvda.getSettings()

nvda.interact()

nvda.itemText()

nvda.itemTextLog()

nvda.lastSpokenPhrase()

nvda.navigateNextUntil(matcher[, options])

nvda.navigateNextHeadingUntil(matcher[, options])

nvda.navigateNextLandmarkUntil(matcher[, options])

nvda.navigateNextLinkUntil(matcher[, options])

nvda.navigatePreviousUntil(matcher[, options])

nvda.navigatePreviousHeadingUntil(matcher[, options])

nvda.navigatePreviousLandmarkUntil(matcher[, options])

nvda.navigatePreviousLinkUntil(matcher[, options])

nvda.next([options])

nvda.nextHeading([options])

nvda.nextLandmark([options])

nvda.nextLink([options])

nvda.perform(command[, options])

nvda.press(key[, options])

nvda.previous([options])

nvda.previousHeading([options])

nvda.previousLandmark([options])

nvda.previousLink([options])

nvda.spokenPhraseLog()

nvda.start([options])

nvda.stop()

nvda.stopInteracting()

nvda.type(text[, options])