Skip to main content

Testing Orca

Guidepup provides support for Orca, the open-source screen reader for Linux.

You can use Guidepup to start and stop Orca, navigate web content, interact with controls, and capture what Orca communicates to the user.

Requirements​

Orca automation requires:

  • Linux with a supported kernel version
  • Orca
  • A supported browser, such as Firefox
  • Node.js
  • @guidepup/guidepup

For the current supported versions and configurations, see the support matrix.

To use a preconfigured Linux container for Orca testing, see the Orca Docker guide.

Machine setup​

Configure your Linux machine for Orca automation:

npx @guidepup/setup setup

Install the Orca assets required by your installed version of Guidepup:

npx @guidepup/setup install

See the machine setup guide for more information about the configuration performed by @guidepup/setup.

Starting Orca​

The orca instance provides direct control over Orca:

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

await orca.start();

try {
  // Orca automation.
} finally {
  await orca.stop();
}

Always stop Orca when the test completes, including when the test fails.

When combining Orca with Playwright, start and stop orca directly in your test.

Navigating web content​

Orca navigation is usually expressed through its keyboardCommands collection and the perform() API:

await orca.perform(orca.keyboardCommands.MoveToNextSibling);

expect(await orca.lastSpokenPhrase()).toContain("Products");

Guidepup also provides common navigation methods, including navigating by:

  • Headings
  • Links
  • Landmarks
  • Form controls
  • Tables
  • Other web content

The example above follows the same basic pattern described in testing navigation: move to content with a screen reader command, then confirm what Orca reported.

See the Orca key code command reference for the available commands and keyboard representations.

When using @guidepup/playwright an additional command for navigating to the web content from the desktop is provided:

await orca.navigateToWebContent();

Interacting with controls​

Orca can be used to interact with controls during a workflow:

await orca.nextLink();

expect(await orca.lastSpokenPhrase()).toContain("View all");

await orca.act();

You can combine these commands with Playwright's browser APIs to create end-to-end tests.

See testing interactions for examples covering forms, links, and other interactive content.

Testing spoken output​

Guidepup can capture what Orca speaks during a test:

await orca.act();

expect(await orca.lastSpokenPhrase()).toContain("Added to basket");

You can also inspect the spoken phrase history when you need to verify a sequence of announcements.

The lastSpokenPhrase() API and the spokenPhraseLog() API are the main observation points for test assertions. See testing announcements for more examples.

Orca specific behaviour​

Guidepup exposes a common screen reader API where possible, while also providing access to Orca-specific commands and settings.

This means tests can share the same general structure across Orca, VoiceOver, and NVDA without hiding the differences between screen readers.

Orca supports interact() and stopInteracting() for entering and leaving an item's interaction mode. The perform() API provides access to Orca-specific commands:

await orca.perform(orca.keyboardCommands.MoveToNextSibling);

Orca does not currently implement press() or type(). Use Playwright's browser APIs for keyboard input or text entry.

See testing NVDA and testing VoiceOver for the equivalent workflows.