Virtual

Implements: ScreenReader

A Virtual Screen Reader instance can be used to launch and control a headless JavaScript screen reader which is compatible with any specification compliant DOM implementation, e.g. jsdom, Jest, or any modern browser.

Here's a typical example using a Virtual instance:

import { virtual } from "@guidepup/virtual-screen-reader";

function setupBasicPage() {
  document.body.innerHTML = `
  <nav>Nav Text</nav>
  <section>
    <h1>Section Heading</h1>
    <p>Section Text</p>
    <article>
      <header>
        <h1>Article Header Heading</h1>
        <p>Article Header Text</p>
      </header>
      <p>Article Text</p>
    </article> 
  </section>
  <footer>Footer</footer>
  `;
}

describe("Screen Reader Tests", () => {
  test("should traverse the page announcing the expected roles and content", async () => {
    // Setup a page using a framework and testing library of your choice
    setupBasicPage();

    // Start your Virtual Screen Reader instance
    await virtual.start({ container: document.body });

    // Navigate your environment with the Virtual Screen Reader just as your users would
    while ((await virtual.lastSpokenPhrase()) !== "end of document") {
      await virtual.next();
    }

    // Assert on what your users would really see and hear when using screen readers
    expect(await virtual.spokenPhraseLog()).toEqual([
      "document",
      "navigation",
      "Nav Text",
      "end of navigation",
      "region",
      "heading, Section Heading, level 1",
      "Section Text",
      "article",
      "banner",
      "heading, Article Header Heading, level 1",
      "Article Header Text",
      "end of banner",
      "Article Text",
      "end of article",
      "end of region",
      "contentinfo",
      "Footer",
      "end of contentinfo",
      "end of document",
    ]);

    // Stop your Virtual Screen Reader instance
    await virtual.stop();
  });
});

Contents:

• virtual.activeNode
• virtual.commands
• virtual.act()
• virtual.clearItemTextLog()
• virtual.clearSpokenPhraseLog()
• virtual.click()
• virtual.default()
• virtual.detect()
• virtual.interact()
• virtual.itemText()
• virtual.itemTextLog()
• virtual.lastSpokenPhrase()
• virtual.next()
• virtual.perform(command[, options])
• virtual.press(key)
• virtual.previous()
• virtual.spokenPhraseLog()
• virtual.start([options])
• virtual.stop()
• virtual.stopInteracting()
• virtual.type(text)

virtual.activeNode

Getter for the active node under the Virtual Screen Reader cursor.

Note that this is not always the same as the currently focused node.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

  // Move to the next element.
  await virtual.next();

  // Log the currently focused node.
  console.log(virtual.activeNode);

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Node | null

virtual.commands

Getter for all Virtual Screen Reader commands.

Use with the perform command to invoke an action:

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

  // Perform action to move to the next landmark.
  await virtual.perform(virtual.commands.moveToNextLandmark);

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

See also:

• virtual.perform(command[, options])

Returns: VirtualCommands

virtual.act()

Perform the default action for the item in the Virtual Screen Reader cursor.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Promise<void>

virtual.clearItemTextLog()

Clear the log of all visited item text for this Virtual Screen Reader instance.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

  // ... perform some commands.

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Promise<void>

virtual.clearSpokenPhraseLog()

Clear the log of all spoken phrases for this Virtual Screen Reader instance.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

  // ... perform some commands.

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Promise<void>

virtual.click([options])

Click the mouse.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

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

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Parameters:

• Optional: options ClickOptions Click options.

Returns: Promise<void>

virtual.default()

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

• false for all OS

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  const isVirtualDefaultScreenReader = await virtual.default();

  console.log(isVirtualDefaultScreenReader);
});

Returns: Promise<boolean>

virtual.detect()

Detect whether Virtual is supported for the current OS:

• true for all OS

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  const isVirtualSupportedScreenReader = await virtual.detect();

  console.log(isVirtualSupportedScreenReader);
});

Returns: Promise<boolean>

virtual.interact()

No-op to provide same API across screen readers.

The Virtual Screen Reader does not require users to perform an additional command to interact with the item in the Virtual Screen Reader cursor.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

  // Interact with the item - does nothing with the Virtual Screen Reader.
  await virtual.interact();

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Promise<void>

virtual.itemText()

Get the text of the item in the Virtual Screen Reader cursor.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

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

virtual.itemTextLog()

Get the log of all visited item text for this Virtual Screen Reader instance.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

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

virtual.lastSpokenPhrase()

Get the last spoken phrase.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

  // Get the phrase spoken by Virtual Screen Reader from moving to the next item above.
  const lastSpokenPhrase = await virtual.lastSpokenPhrase();
  console.log(lastSpokenPhrase);

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Promise<string> The last spoken phrase.

virtual.next()

Move the Virtual cursor to the next location.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Parameters:

• Optional: options CommandOptions Additional options.

Returns: Promise<void>

virtual.perform(command[, options])

Perform a Virtual Screen Reader command.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

  // Perform action to move to the next landmark.
  await virtual.perform(virtual.commands.moveToNextLandmark);

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

See also:

• virtual.commands
• VirtualCommands

Parameters:

• command string Virtual Screen Reader command to execute. See VirtualCommands for valid commands.
• Optional: options object Additional options.

Returns: Promise<void>

virtual.press(key)

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.

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: "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 { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Parameters:

• key string Name of the key to press or a character to generate, such as ArrowLeft or a.

Returns: Promise<void>

virtual.previous()

Move the Virtual cursor to the previous location.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Promise<void>

virtual.spokenPhraseLog()

Get the log of all spoken phrases for this Virtual Screen Reader instance.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

  // Get the phrase spoken by the Virtual Screen Reader from moving through the
  // items above.
  const spokenPhraseLog = await virtual.spokenPhraseLog();
  console.log(spokenPhraseLog);

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

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

virtual.start([options])

Turn the Virtual Screen Reader on.

This must be called before any other Virtual Screen Reader command can be issued.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader on the entire page.
  await virtual.start({ container: document.body });

  // ... perform some commands.

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Parameters:

• Optional: options StartOptions Start options.

Returns: Promise<void>

virtual.stop()

Turn the Virtual Screen Reader off.

Calling this method will clear any item text or spoken phrases collected by the Virtual Screen Reader.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

  // ... perform some commands.

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Promise<void>

virtual.stopInteracting()

No-op to provide same API across screen readers.

The Virtual Screen Reader does not require users to perform an additional command to interact with the item in the Virtual Screen Reader cursor.

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

  // Interact with the item - does nothing with the Virtual Screen Reader.
  await virtual.interact();

  // ... perform some commands.

  // Stop interacting with the item - does nothing with Virtual.
  await virtual.stopInteracting();

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Returns: Promise<void>

virtual.type(text)

Type text into the focused item.

To press a special key, like Control or ArrowDown, use virtual.press(key).

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start the Virtual Screen Reader.
  await virtual.start({ container: document.body });

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

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Parameters:

• text string Text to type into the focused item.

Returns: Promise<void>