@guidepup/virtual-screen-reader
Version:
Virtual Screen Reader driver for unit test automation.
1,428 lines (1,418 loc) • 59 kB
text/typescript
type AccessibleAttributeToLabelMap = Record<string, {
label: string;
value: string;
}>;
interface AccessibilityNode {
accessibleAttributeLabels: string[];
accessibleAttributeToLabelMap: AccessibleAttributeToLabelMap;
accessibleDescription: string;
accessibleName: string;
accessibleValue: string;
allowedAccessibilityChildRoles: string[];
alternateReadingOrderParents: Node[];
childrenPresentational: boolean;
isInert: boolean;
node: Node;
parentAccessibilityNodeTree: AccessibilityNodeTree | null;
parent: Node | null;
parentDialog: HTMLElement | null;
role: string;
spokenRole: string;
}
interface AccessibilityNodeTree extends Omit<AccessibilityNode, "accessibleAttributeLabels" | "accessibleAttributeToLabelMap"> {
children: AccessibilityNodeTree[];
}
interface VirtualCommandArgs {
currentIndex: number;
container: Node;
tree: AccessibilityNode[];
}
type GetNextIndexArgs = Omit<VirtualCommandArgs, "container">;
interface JumpToControlledElementCommandArgs extends VirtualCommandArgs {
index?: number;
}
/**
* aria-controls:
*
* Identifies the element (or elements) whose contents or presence
* are controlled by the current element. See related aria-owns.
*
* REF: https://www.w3.org/TR/wai-aria-1.2/#aria-controls
*
* MUST requirement:
*
* The controlled element might not be close to the element with
* aria-controls and the user might find it convenient to jump directly to
* the controlled element.
*
* REF: https://a11ysupport.io/tech/aria/aria-controls_attribute
*/
declare function jumpToControlledElement({ index, container, currentIndex, tree, }: JumpToControlledElementCommandArgs): number | undefined;
/**
* aria-details:
*
* REF: https://www.w3.org/TR/wai-aria-1.2/#aria-details
*
* SHOULD requirement:
*
* If the details are not adjacent to the element with aria-details, it might
* be helpful to jump directly to the reference or have it conveyed.
*
* REF: https://a11ysupport.io/tech/aria/aria-details_attribute
*/
declare function jumpToDetailsElement({ container, currentIndex, tree, }: VirtualCommandArgs): number | undefined;
interface JumpToErrorMessageElementCommandArgs extends VirtualCommandArgs {
index?: number;
}
/**
* aria-errormessage:
*
* REFs:
* - https://www.w3.org/TR/wai-aria-1.2/#aria-errormessage
* - https://a11ysupport.io/tech/aria/aria-errormessage_attribute
*/
declare function jumpToErrorMessageElement({ index, container, currentIndex, tree, }: JumpToErrorMessageElementCommandArgs): number | undefined;
interface MoveToNextAlternateReadingOrderElement$1 extends VirtualCommandArgs {
index?: number;
}
/**
* aria-flowto:
*
* However, when aria-flowto is provided with multiple ID
* references, assistive technologies SHOULD present the referenced
* elements as path choices.
*
* In the case of one or more ID references, user agents or assistive
* technologies SHOULD give the user the option of navigating to any of the
* targeted elements. The name of the path can be determined by the name of
* the target element of the aria-flowto attribute. Accessibility APIs can
* provide named path relationships.
*
* REF: https://www.w3.org/TR/wai-aria-1.2/#aria-flowto
*
* MUST requirements:
*
* A user needs to understand that the current element flows to another element
* so that they can invoke the functionality.
*
* A user needs to be able to follow the alternate reading order.
*
* REF: https://a11ysupport.io/tech/aria/aria-flowto_attribute
*/
declare function moveToNextAlternateReadingOrderElement({ index, container, currentIndex, tree, }: MoveToNextAlternateReadingOrderElement$1): number | undefined;
interface MoveToNextAlternateReadingOrderElement extends VirtualCommandArgs {
index?: number;
}
/**
* aria-flowto:
*
* However, when aria-flowto is provided with multiple ID
* references, assistive technologies SHOULD present the referenced
* elements as path choices.
*
* In the case of one or more ID references, user agents or assistive
* technologies SHOULD give the user the option of navigating to any of the
* targeted elements. The name of the path can be determined by the name of
* the target element of the aria-flowto attribute. Accessibility APIs can
* provide named path relationships.
*
* REF: https://www.w3.org/TR/wai-aria-1.2/#aria-flowto
*
* MUST requirements:
*
* The reading order goes both directions, and a user needs to be aware of the
* alternate reading order so that they can invoke the functionality.
*
* The reading order goes both directions, and a user needs to be able to
* travel backwards through their chosen reading order.
*
* REF: https://a11ysupport.io/tech/aria/aria-flowto_attribute
*/
declare function moveToPreviousAlternateReadingOrderElement({ index, container, currentIndex, tree, }: MoveToNextAlternateReadingOrderElement): number | undefined;
declare const commands: {
/**
* Move to the next element with a level 1 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 level 1 heading element.
* await virtual.perform(virtual.commands.moveToNextHeadingLevel1);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextHeadingLevel1: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a level 1 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 previous level 1 heading element.
* await virtual.perform(virtual.commands.moveToPreviousHeadingLevel1);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousHeadingLevel1: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a level 2 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 level 2 heading element.
* await virtual.perform(virtual.commands.moveToNextHeadingLevel2);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextHeadingLevel2: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a level 2 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 previous level 2 heading element.
* await virtual.perform(virtual.commands.moveToPreviousHeadingLevel2);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousHeadingLevel2: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a level 3 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 level 3 heading element.
* await virtual.perform(virtual.commands.moveToNextHeadingLevel3);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextHeadingLevel3: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a level 3 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 previous level 3 heading element.
* await virtual.perform(virtual.commands.moveToPreviousHeadingLevel3);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousHeadingLevel3: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a level 4 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 level 4 heading element.
* await virtual.perform(virtual.commands.moveToNextHeadingLevel4);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextHeadingLevel4: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a level 4 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 previous level 4 heading element.
* await virtual.perform(virtual.commands.moveToPreviousHeadingLevel4);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousHeadingLevel4: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a level 5 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 level 5 heading element.
* await virtual.perform(virtual.commands.moveToNextHeadingLevel5);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextHeadingLevel5: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a level 5 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 previous level 5 heading element.
* await virtual.perform(virtual.commands.moveToPreviousHeadingLevel5);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousHeadingLevel5: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a level 6 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 level 6 heading element.
* await virtual.perform(virtual.commands.moveToNextHeadingLevel6);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextHeadingLevel6: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a level 6 [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role:
*
* ```ts
* 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 previous level 6 heading element.
* await virtual.perform(virtual.commands.moveToPreviousHeadingLevel6);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousHeadingLevel6: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with any [`landmark`](https://www.w3.org/TR/wai-aria-1.2/#landmark)
* role:
*
* - [`banner`](https://www.w3.org/TR/wai-aria-1.2/#banner)
* - [`complementary`](https://www.w3.org/TR/wai-aria-1.2/#complementary)
* - [`contentinfo`](https://www.w3.org/TR/wai-aria-1.2/#contentinfo)
* - [`figure`](https://www.w3.org/TR/wai-aria-1.2/#figure)
* - [`form`](https://www.w3.org/TR/wai-aria-1.2/#form)
* - [`landmark`](https://www.w3.org/TR/wai-aria-1.2/#landmark)
* - [`main`](https://www.w3.org/TR/wai-aria-1.2/#main)
* - [`navigation`](https://www.w3.org/TR/wai-aria-1.2/#navigation)
* - [`region`](https://www.w3.org/TR/wai-aria-1.2/#region)
* - [`search`](https://www.w3.org/TR/wai-aria-1.2/#search)
*
* ```ts
* 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 element.
* await virtual.perform(virtual.commands.moveToNextLandmark);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextLandmark: ({ currentIndex, tree, }: GetNextIndexArgs) => number | null;
/**
* Move to the previous element with any [`landmark`](https://www.w3.org/TR/wai-aria-1.2/#landmark)
* role:
*
* - [`banner`](https://www.w3.org/TR/wai-aria-1.2/#banner)
* - [`complementary`](https://www.w3.org/TR/wai-aria-1.2/#complementary)
* - [`contentinfo`](https://www.w3.org/TR/wai-aria-1.2/#contentinfo)
* - [`figure`](https://www.w3.org/TR/wai-aria-1.2/#figure)
* - [`form`](https://www.w3.org/TR/wai-aria-1.2/#form)
* - [`landmark`](https://www.w3.org/TR/wai-aria-1.2/#landmark)
* - [`main`](https://www.w3.org/TR/wai-aria-1.2/#main)
* - [`navigation`](https://www.w3.org/TR/wai-aria-1.2/#navigation)
* - [`region`](https://www.w3.org/TR/wai-aria-1.2/#region)
* - [`search`](https://www.w3.org/TR/wai-aria-1.2/#search)
*
* ```ts
* 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 previous landmark element.
* await virtual.perform(virtual.commands.moveToPreviousLandmark);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousLandmark: ({ currentIndex, tree, }: GetNextIndexArgs) => number | null;
/**
* Move to the next element with a [`banner`](https://www.w3.org/TR/wai-aria-1.2/#banner)
* role.
*
* ```ts
* 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 banner element.
* await virtual.perform(virtual.commands.moveToNextBanner);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextBanner: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`banner`](https://www.w3.org/TR/wai-aria-1.2/#banner)
* role.
*
* ```ts
* 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 previous banner element.
* await virtual.perform(virtual.commands.moveToPreviousBanner);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousBanner: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`complementary`](https://www.w3.org/TR/wai-aria-1.2/#complementary)
* role.
*
* ```ts
* 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 complementary element.
* await virtual.perform(virtual.commands.moveToNextComplementary);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextComplementary: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`complementary`](https://www.w3.org/TR/wai-aria-1.2/#complementary)
* role.
*
* ```ts
* 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 previous complementary element.
* await virtual.perform(virtual.commands.moveToPreviousComplementary);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousComplementary: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`contentinfo`](https://www.w3.org/TR/wai-aria-1.2/#contentinfo)
* role.
*
* ```ts
* 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 contentinfo element.
* await virtual.perform(virtual.commands.moveToNextContentInfo);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextContentinfo: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`contentinfo`](https://www.w3.org/TR/wai-aria-1.2/#contentinfo)
* role.
*
* ```ts
* 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 previous contentinfo element.
* await virtual.perform(virtual.commands.moveToPreviousContentinfo);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousContentinfo: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`figure`](https://www.w3.org/TR/wai-aria-1.2/#figure)
* role.
*
* ```ts
* 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 figure element.
* await virtual.perform(virtual.commands.moveToNextFigure);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextFigure: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`figure`](https://www.w3.org/TR/wai-aria-1.2/#figure)
* role.
*
* ```ts
* 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 previous figure element.
* await virtual.perform(virtual.commands.moveToPreviousFigure);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousFigure: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`form`](https://www.w3.org/TR/wai-aria-1.2/#form)
* role.
*
* ```ts
* 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 form element.
* await virtual.perform(virtual.commands.moveToNextForm);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextForm: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`form`](https://www.w3.org/TR/wai-aria-1.2/#form)
* role.
*
* ```ts
* 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 previous form element.
* await virtual.perform(virtual.commands.moveToPreviousForm);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousForm: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`main`](https://www.w3.org/TR/wai-aria-1.2/#main)
* role.
*
* ```ts
* 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 main element.
* await virtual.perform(virtual.commands.moveToNextMain);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextMain: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`main`](https://www.w3.org/TR/wai-aria-1.2/#main)
* role.
*
* ```ts
* 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 previous main element.
* await virtual.perform(virtual.commands.moveToPreviousMain);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousMain: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`navigation`](https://www.w3.org/TR/wai-aria-1.2/#navigation)
* role.
*
* ```ts
* 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 navigation element.
* await virtual.perform(virtual.commands.moveToNextNavigation);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextNavigation: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`navigation`](https://www.w3.org/TR/wai-aria-1.2/#navigation)
* role.
*
* ```ts
* 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 previous navigation element.
* await virtual.perform(virtual.commands.moveToPreviousNavigation);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousNavigation: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`region`](https://www.w3.org/TR/wai-aria-1.2/#region)
* role.
*
* ```ts
* 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 region element.
* await virtual.perform(virtual.commands.moveToNextRegion);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextRegion: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`region`](https://www.w3.org/TR/wai-aria-1.2/#region)
* role.
*
* ```ts
* 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 previous region element.
* await virtual.perform(virtual.commands.moveToPreviousRegion);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousRegion: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`search`](https://www.w3.org/TR/wai-aria-1.2/#search)
* role.
*
* ```ts
* 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 search element.
* await virtual.perform(virtual.commands.moveToNextSearch);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextSearch: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`search`](https://www.w3.org/TR/wai-aria-1.2/#search)
* role.
*
* ```ts
* 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 previous search element.
* await virtual.perform(virtual.commands.moveToPreviousSearch);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousSearch: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role.
*
* ```ts
* 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 heading element.
* await virtual.perform(virtual.commands.moveToNextHeading);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextHeading: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`heading`](https://www.w3.org/TR/wai-aria-1.2/#heading)
* role.
*
* ```ts
* 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 previous heading element.
* await virtual.perform(virtual.commands.moveToPreviousHeading);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousHeading: (args: VirtualCommandArgs) => number | null;
/**
* Move to the next element with a [`link`](https://www.w3.org/TR/wai-aria-1.2/#link)
* role.
*
* ```ts
* 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 link element.
* await virtual.perform(virtual.commands.moveToNextLink);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextLink: (args: VirtualCommandArgs) => number | null;
/**
* Move to the previous element with a [`link`](https://www.w3.org/TR/wai-aria-1.2/#link)
* role.
*
* ```ts
* 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 previous link element.
* await virtual.perform(virtual.commands.moveToPreviousLink);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousLink: (args: VirtualCommandArgs) => number | null;
/**
* Jump to an element controlled by the current element in the Virtual Screen
* Reader focus. See [aria-controls](https://www.w3.org/TR/wai-aria-1.2/#aria-controls).
*
* When using with `virtual.perform()`, pass an index option to select which
* controlled element is jumped to when there are more than one:
*
* ```ts
* 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 jump to the second controlled element.
* await virtual.perform(virtual.commands.jumpToControlledElement, { index: 1 });
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
jumpToControlledElement: typeof jumpToControlledElement;
/**
* Jump to an element that describes the current element in the Virtual
* Screen Reader focus. See [aria-details](https://www.w3.org/TR/wai-aria-1.2/#aria-details).
*
* ```ts
* 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 jump to the details element.
* await virtual.perform(virtual.commands.jumpToDetailsElement);
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
jumpToDetailsElement: typeof jumpToDetailsElement;
/**
* Jump to an element that provides an error message for the current element
* in the Virtual Screen Reader focus. See [aria-errormessage](https://www.w3.org/TR/wai-aria-1.2/#aria-errormessage).
*
* When using with `virtual.perform()`, pass an `index` option to select
* which error message element is jumped to when there are more than one:
*
* ```ts
* 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 jump to the second error message element.
* await virtual.perform(virtual.commands.jumpToErrorMessageElement, {
* index: 1,
* });
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
jumpToErrorMessageElement: typeof jumpToErrorMessageElement;
/**
* Move to the next element in an alternate reading order. See
* [aria-flowto](https://www.w3.org/TR/wai-aria-1.2/#aria-flowto).
*
* When using with `virtual.perform()`, pass an `index` option to select
* which alternate reading order element is jumped to when there are more
* than one:
*
* ```ts
* 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 second choice element of next alternate reading order.
* await virtual.perform(
* virtual.commands.moveToNextAlternateReadingOrderElement,
* { index: 1 }
* );
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToNextAlternateReadingOrderElement: typeof moveToNextAlternateReadingOrderElement;
/**
* Move to the previous element in an alternate reading order. See
* [aria-flowto](https://www.w3.org/TR/wai-aria-1.2/#aria-flowto).
*
* When using with `virtual.perform()`, pass an `index` option to select
* which alternate reading order element is jumped to when there are more than
* one:
*
* ```ts
* 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 second choice element of previous alternate reading order.
* await virtual.perform(
* virtual.commands.moveToPreviousAlternateReadingOrderElement,
* { index: 1 }
* );
*
* // Stop the Virtual Screen Reader.
* await virtual.stop();
* });
* ```
*/
moveToPreviousAlternateReadingOrderElement: typeof moveToPreviousAlternateReadingOrderElement;
};
type VirtualCommands = {
[K in keyof typeof commands]: (typeof commands)[K];
};
interface Root {
document?: Document;
MutationObserver?: typeof MutationObserver;
}
interface StartOptions {
/**
* The bounding HTML element to use the Virtual Screen Reader in.
*
* To use the entire page pass `document.body`.
*/
container: Node;
/**
* The window instance.
*
* Only required if the `window` instance is not already globally available.
* For example, when you are in a Node environment and using a custom DOM
* implementation that is not attached to the global scope.
*
* Defaults to using the global `window` instance.
*/
window?: Root;
/**
* Display the Virtual Screen Reader cursor visually on the target element.
*
* Note: There is a performance overhead to visually rendering the cursor.
*
* Defaults to `false`.
*/
displayCursor?: boolean;
}
/**
* TODO: When a modal element is displayed, assistive technologies SHOULD
* navigate to the element unless focus has explicitly been set elsewhere.
*
* REF: https://www.w3.org/TR/wai-aria-1.2/#aria-modal
*/
/**
* TODO: When an assistive technology reading cursor moves from one article to
* another, assistive technologies SHOULD set user agent focus on the article
* that contains the reading cursor. If the reading cursor lands on a focusable
* element inside the article, the assistive technology MAY set focus on that
* element in lieu of setting focus on the containing article.
*
* REF: https://www.w3.org/TR/wai-aria-1.2/#feed
*/
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual)
*
* A Virtual Screen Reader class that 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:
*
* ```ts
* 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();
*
* // Create a new Virtual Screen Reader instance
* const virtual = new Virtual();
*
* // 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",
* "heading, Article Header Heading, level 1",
* "Article Header Text",
* "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();
* });
* });
* ```
*/
declare class Virtual {
#private;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-active-node)
*
* Getter for the active node under the Virtual Screen Reader cursor.
*
* Note that this is not always the same as the currently focused node.
*
* ```ts
* 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}
*/
get activeNode(): Node | null;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-commands)
*
* Getter for all Virtual Screen Reader commands.
*
* Use with the `await virtual.perform(command)` command to invoke an action:
*
* ```ts
* 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();
* });
* ```
*/
get commands(): { [K in keyof VirtualCommands]: K; };
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-detect)
*
* Detect whether the screen reader is supported for the current OS:
*
* - `true` for all OS
*
* ```ts
* import { virtual } from "@guidepup/virtual-screen-reader";
*
* test("example test", async () => {
* const isVirtualSupportedScreenReader = await virtual.detect();
*
* console.log(isVirtualSupportedScreenReader);
* });
* ```
*
* @returns {Promise<boolean>}
*/
detect(): Promise<boolean>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-default)
*
* Detect whether the screen reader is the default screen reader for the current OS.
*
* - `false` for all OS
*
* ```ts
* import { virtual } from "@guidepup/virtual-screen-reader";
*
* test("example test", async () => {
* const isVirtualDefaultScreenReader = await virtual.default();
*
* console.log(isVirtualDefaultScreenReader);
* });
* ```
*
* @returns {Promise<boolean>}
*/
default(): Promise<boolean>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-start)
*
* Turn the Virtual Screen Reader on.
*
* This must be called before any other Virtual command can be issued.
*
* ```ts
* 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();
* });
* ```
*
* @param {object} [options] Additional options.
*/
start({ container, displayCursor, window: root }?: StartOptions): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-stop)
*
* Turn the Virtual Screen Reader off.
*
* Calling this method will clear any item text or spoken phrases collected by Virtual.
*
* ```ts
* 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();
* });
* ```
*/
stop(): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-previous)
*
* Move the screen reader cursor to the previous location.
*
* ```ts
* 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();
* });
* ```
*/
previous(): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-next)
*
* Move the screen reader cursor to the next location.
*
* ```ts
* 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();
* });
* ```
*/
next(): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-act)
*
* Perform the default action for the item in the Virtual Screen Reader cursor.
*
* ```ts
* 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();
* });
* ```
*/
act(): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#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.
*/
interact(): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-stop-interacting)
*
* 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.
*/
stopInteracting(): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-press)
*
* Press a key on the active item.
*
* `key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/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](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). 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` (OS permitting).
*
* 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.
*
* ```ts
* 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();
* });
* ```
*
* @param {string} key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
*/
press(key: string): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-type)
*
* Type text into the active item.
*
* To press a special key, like `Control` or `ArrowDown`, use `virtual.press(key)`.
*
* ```ts
* 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();
* });
* ```
*
* @param {string} text Text to type into the active item.
*/
type(text: string): Promise<void>;
/**
* [API Reference](https://www.guidepup.dev/docs/api/class-virtual#virtual-perform)
*
* Perform a Virtual Screen Reader command.
*
* ```ts
* import { virtual } from "@guidepup/virtual-screen-reader";
*
* test("example test", async () => {
* // Start the Virtual Screen Reader.
* await virtual.start({ container: doc