{"id":19787185,"url":"https://github.com/guidepup/virtual-screen-reader","last_synced_at":"2025-04-06T10:12:32.162Z","repository":{"id":168197244,"uuid":"643857179","full_name":"guidepup/virtual-screen-reader","owner":"guidepup","description":"Virtual Screen Reader is a screen reader simulator for unit tests.","archived":false,"fork":false,"pushed_at":"2024-09-24T06:02:43.000Z","size":9783,"stargazers_count":99,"open_issues_count":6,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-15T06:31:26.693Z","etag":null,"topics":["a11y","a11y-api","a11y-automation","a11y-testing","accessibility","accessibility-automation","accessibility-testing","screen-reader","screen-reader-api"],"latest_commit_sha":null,"homepage":"https://guidepup.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guidepup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS.md","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["cmorten"]}},"created_at":"2023-05-22T09:52:26.000Z","updated_at":"2024-10-04T13:12:01.000Z","dependencies_parsed_at":"2023-12-01T08:29:49.982Z","dependency_job_id":"908263c9-21a4-467b-b5d3-09233a18ec50","html_url":"https://github.com/guidepup/virtual-screen-reader","commit_stats":{"total_commits":175,"total_committers":7,"mean_commits":25.0,"dds":"0.44571428571428573","last_synced_commit":"19eb568be30264c180265615179d0146eded0895"},"previous_names":["guidepup/virtual-screen-reader"],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidepup%2Fvirtual-screen-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidepup%2Fvirtual-screen-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidepup%2Fvirtual-screen-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidepup%2Fvirtual-screen-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guidepup","download_url":"https://codeload.github.com/guidepup/virtual-screen-reader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247246017,"owners_count":20907723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a11y","a11y-api","a11y-automation","a11y-testing","accessibility","accessibility-automation","accessibility-testing","screen-reader","screen-reader-api"],"created_at":"2024-11-12T06:21:32.593Z","updated_at":"2025-04-06T10:12:32.143Z","avatar_url":"https://github.com/guidepup.png","language":"TypeScript","readme":"# Virtual Screen Reader\n\n\u003ca href=\"https://www.npmjs.com/package/@guidepup/virtual-screen-reader\"\u003e\u003cimg alt=\"Virtual Screen Reader available on NPM\" src=\"https://img.shields.io/npm/v/@guidepup/virtual-screen-reader\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/guidepup/virtual-screen-reader/actions/workflows/test.yml\"\u003e\u003cimg alt=\"Virtual Screen Reader test workflows\" src=\"https://github.com/guidepup/virtual-screen-reader/workflows/Test/badge.svg\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/guidepup/virtual-screen-reader/blob/main/LICENSE\"\u003e\u003cimg alt=\"Virtual Screen Reader uses the MIT license\" src=\"https://img.shields.io/github/license/guidepup/virtual-screen-reader\" /\u003e\u003c/a\u003e\n\n## [Documentation](https://www.guidepup.dev/docs/virtual) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup-virtual-screen-reader)\n\nVirtual Screen Reader is a screen reader simulator for unit tests.\n\nThis package aims to supplement your testing by enabling you to automate a Virtual Screen Reader for unit test workflows the same as you would for mouse or keyboard based scenarios.\n\n\u003e [!IMPORTANT]\n\u003e This package should not replace but augment your screen reader testing, there is no substitute for testing with real screen readers and with real users.\n\nIf you are looking to automate real screen readers, check out the [`@guidepup/guidepup`](https://github.com/guidepup/guidepup) package.\n\nIf you are looking to for quick and easy Jest snapshot testing, check out the [`@guidepup/jest`](https://github.com/guidepup/jest) package.\n\n## Capabilities\n\n- **Mirrors Screen Reader Functionality** - simulate and assert on what users can do when using screen readers.\n- **Test Framework Agnostic** - run with Jest, Vitest, Web Test Runner, in Storybook, as an independent script, no vendor lock-in.\n- **UI Framework Agnostic** - want to use React, Vue, Solid, Svelte, etc.? All good here! Works with any UI framework, and plays nicely with the [Testing Library](https://testing-library.com/) suite.\n- **Fast Feedback** - avoid the cumbersome overhead of running an e2e test with a real screen reader by running virtually over the provided DOM.\n\n## Principles\n\nThere is currently no explicit specification for screen readers to adhere to, but there are a number of requirements laid out by specifications to inform screen reader expectations. This library aims to meet these requirements so that it can be as \"spec compliant\" as possible.\n\nCurrent W3C specifications used:\n\n- [Accessible Name and Description Computation (ACCNAME) 1.2](https://www.w3.org/TR/accname-1.2/)\n- [Core Accessibility API Mappings (CORE-AAM) 1.2](https://www.w3.org/TR/core-aam-1.2/)\n- [Digital Publishing Accessibility API Mappings](https://www.w3.org/TR/dpub-aam-1.0/)\n- [Digital Publishing WAI-ARIA Module 1.1](https://www.w3.org/TR/dpub-aria-1.1/)\n- [Graphics Accessibility API Mappings](https://www.w3.org/TR/graphics-aam-1.0/)\n- [WAI-ARIA Graphics Module](https://www.w3.org/TR/graphics-aria-1.0/)\n- [HTML Accessibility API Mappings (HTML-AAM) 1.0](https://www.w3.org/TR/html-aam-1.0/)\n- [ARIA in HTML (HTML-ARIA)](https://www.w3.org/TR/html-aria/)\n- [SVG Accessibility API Mappings](https://www.w3.org/TR/svg-aam-1.0/)\n- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/)\n\nExtracted requirements from these specifications can be found in [docs/requirements.md](docs/requirements.md). If a requirement is not met, [please raise an issue](https://github.com/guidepup/virtual-screen-reader/issues).\n\nInternal modules responsible for constructing the Virtual Screen Reader accessibility tree are being tested against [Web Platform Tests](https://github.com/web-platform-tests/wpt) for the following specs:\n\n- [accname](https://github.com/web-platform-tests/wpt/tree/master/accname)\n- [core-aam](https://github.com/web-platform-tests/wpt/tree/master/core-aam)\n- [dpub-aam](https://github.com/web-platform-tests/wpt/tree/master/dpub-aam)\n- [graphics-aria](https://github.com/web-platform-tests/wpt/tree/master/graphics-aria)\n- [html-aam](https://github.com/web-platform-tests/wpt/tree/master/html-aam)\n- [svg-aam](https://github.com/web-platform-tests/wpt/tree/master/svg-aam)\n- [wai-aria](https://github.com/web-platform-tests/wpt/tree/master/wai-aria)\n\nThe current status of the WPT coverage is:\n\n| Passing | Failing | Skipped |\n| :-----: | :-----: | :-----: |\n|   411   |   128   |   338   |\n\nThe included tests, skipped tests, and expected failures can be found in the [WPT configuration file](./test/wpt-jsdom/to-run.yaml) with reasons as to skips and expected failures.\n\nIn addition to the W3C specifications [a11ysupport.io](https://a11ysupport.io/) has been used as a guide for test cases in the absence of anything formal for screen reader output. In future we hope to adopt test cases laid out by the [ARIA and Assistive Technologies (ARIA-AT) community group](https://github.com/w3c/aria-at).\n\n\u003e [!NOTE]\n\u003e This library should not used as a substitute for testing with real screen readers and with real screen reader users, but a means to gain quick coverage and confidence by automating away common scenarios the same as any other unit test.\n\n## Getting Started\n\nInstall Virtual Screen Reader to your projects:\n\n```bash\nnpm install --save-dev @guidepup/virtual-screen-reader\n```\n\n```bash\nyarn add -D @guidepup/virtual-screen-reader\n```\n\nAnd get cracking with your first screen reader unit test automation code!\n\n## Examples\n\nHead over to the [Guidepup Website](https://www.guidepup.dev/) for guides, real world examples, and complete API documentation with examples.\n\nSome examples can also be found in the [examples section](./examples).\n\nYou can also check out this project's own [integration tests](https://github.com/guidepup/virtual-screen-reader/tree/main/src/test) to learn how you could use the Virtual Screen Reader in your projects.\n\n### Basic Navigation\n\nHere is a basic example for navigating through HTML in a Jest test in a Node setup:\n\n```ts\nimport { virtual } from \"@guidepup/virtual-screen-reader\";\n\nfunction setupBasicPage() {\n  document.body.innerHTML = `\n  \u003cnav\u003eNav Text\u003c/nav\u003e\n  \u003csection\u003e\n    \u003ch1\u003eSection Heading\u003c/h1\u003e\n    \u003cp\u003eSection Text\u003c/p\u003e\n    \u003carticle\u003e\n      \u003cheader\u003e\n        \u003ch1\u003eArticle Header Heading\u003c/h1\u003e\n        \u003cp\u003eArticle Header Text\u003c/p\u003e\n      \u003c/header\u003e\n      \u003cp\u003eArticle Text\u003c/p\u003e\n    \u003c/article\u003e \n  \u003c/section\u003e\n  \u003cfooter\u003eFooter\u003c/footer\u003e\n  `;\n}\n\ndescribe(\"Screen Reader Tests\", () =\u003e {\n  test(\"should traverse the page announcing the expected roles and content\", async () =\u003e {\n    // Setup a page using a framework and testing library of your choice\n    setupBasicPage();\n\n    // Start your Virtual Screen Reader instance\n    await virtual.start({ container: document.body });\n\n    // Navigate your environment with the Virtual Screen Reader similar to how your users would\n    while ((await virtual.lastSpokenPhrase()) !== \"end of document\") {\n      await virtual.next();\n    }\n\n    // Assert on the kind of things your users would see and hear when using screen readers\n    expect(await virtual.spokenPhraseLog()).toEqual([\n      \"document\",\n      \"navigation\",\n      \"Nav Text\",\n      \"end of navigation\",\n      \"heading, Section Heading, level 1\",\n      \"paragraph\",\n      \"Section Text\",\n      \"end of paragraph\",\n      \"article\",\n      \"heading, Article Header Heading, level 1\",\n      \"paragraph\",\n      \"Article Header Text\",\n      \"end of paragraph\",\n      \"paragraph\",\n      \"Article Text\",\n      \"end of paragraph\",\n      \"end of article\",\n      \"contentinfo\",\n      \"Footer\",\n      \"end of contentinfo\",\n      \"end of document\",\n    ]);\n\n    // Stop your Virtual Screen Reader instance\n    await virtual.stop();\n  });\n});\n```\n\n### Browser\n\nVirtual Screen Reader also supports ESM environments such as browsers.\n\nTry it out on any website in a browser of your choice by executing the following snippet in DevTools:\n\n```ts\nconst { virtual } = await import(\n  \"https://unpkg.com/@guidepup/virtual-screen-reader/lib/esm/index.browser.js\"\n);\n\nawait virtual.start({ container: document.body, displayCursor: true });\n\nawait virtual.next();\n\nconsole.log(await virtual.spokenPhraseLog());\n\nawait virtual.stop();\n```\n\n### AOM Support\n\nVirtual Screen Reader will feature detect [Accessibility Object Model (AOM)](https://github.com/WICG/aom) support and adopt the browser's computed accessible names and roles when available.\n\nSee the [Storybook example](./examples/storybook/) to learn how to opt into this behaviour.\n\n## Powerful Tooling\n\nCheck out some of the other Guidepup modules:\n\n- [`@guidepup/guidepup`](https://github.com/guidepup/guidepup) - Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver and NVDA.\n- [`@guidepup/setup`](https://github.com/guidepup/setup) - Set up your local or CI environment for screen reader test automation.\n- [`@guidepup/playwright`](https://github.com/guidepup/guidepup-playwright) - Seamless integration of Guidepup with Playwright.\n- [`@guidepup/jest`](https://github.com/guidepup/jest) - Jest matchers for reliable unit testing of your screen reader a11y workflows.\n\n## Similar\n\nHere are some similar unaffiliated projects:\n\n- [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library/)\n- [`html-aria`](https://github.com/drwpow/html-aria)\n- [`aria-query`](https://github.com/A11yance/aria-query)\n- [`dom-accessibility-api`](https://github.com/eps1lon/dom-accessibility-api)\n- [`aria-at`](https://github.com/w3c/aria-at)\n\n## Resources\n\n- [Documentation](https://www.guidepup.dev/docs/virtual)\n- [API Reference](https://www.guidepup.dev/docs/api/class-guidepup-virtual-screen-reader)\n- [Contributing](.github/CONTRIBUTING.md)\n- [Changelog](https://github.com/guidepup/virtual-screen-reader/releases)\n- [MIT License](https://github.com/guidepup/virtual-screen-reader/blob/main/LICENSE)\n","funding_links":["https://github.com/sponsors/cmorten"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguidepup%2Fvirtual-screen-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguidepup%2Fvirtual-screen-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguidepup%2Fvirtual-screen-reader/lists"}