{"id":13651022,"url":"https://github.com/guidepup/guidepup-playwright","last_synced_at":"2025-04-04T19:13:05.932Z","repository":{"id":43814503,"uuid":"445871193","full_name":"guidepup/guidepup-playwright","owner":"guidepup","description":"Screen reader driver for Playwright tests.","archived":false,"fork":false,"pushed_at":"2024-11-30T12:17:25.000Z","size":274,"stargazers_count":66,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T18:17:31.446Z","etag":null,"topics":["a11y","a11y-api","a11y-automation","a11y-testing","accessibility","accessibility-automation","accessibility-testing","nvda","playwright","playwright-a11y","screen-reader","screen-reader-api","voiceover"],"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":"2022-01-08T16:31:11.000Z","updated_at":"2025-03-27T08:58:13.000Z","dependencies_parsed_at":"2023-12-10T02:23:40.712Z","dependency_job_id":"1838c39e-7df6-48f4-9f58-e6a67ca2fb9f","html_url":"https://github.com/guidepup/guidepup-playwright","commit_stats":{"total_commits":40,"total_committers":3,"mean_commits":"13.333333333333334","dds":"0.22499999999999998","last_synced_commit":"841cfda6c0f9c4250949ec9d3885363fc65c940c"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidepup%2Fguidepup-playwright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidepup%2Fguidepup-playwright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidepup%2Fguidepup-playwright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guidepup%2Fguidepup-playwright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guidepup","download_url":"https://codeload.github.com/guidepup/guidepup-playwright/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234923,"owners_count":20905854,"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","nvda","playwright","playwright-a11y","screen-reader","screen-reader-api","voiceover"],"created_at":"2024-08-02T02:00:43.964Z","updated_at":"2025-04-04T19:13:05.915Z","avatar_url":"https://github.com/guidepup.png","language":"TypeScript","readme":"# Guidepup Playwright\n\n\u003ca href=\"https://www.npmjs.com/package/@guidepup/playwright\"\u003e\u003cimg alt=\"@guidepup/playwright available on NPM\" src=\"https://img.shields.io/npm/v/@guidepup/playwright\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/guidepup/guidepup-playwright/actions/workflows/test.yml\"\u003e\u003cimg alt=\"@guidepup/playwright test workflows\" src=\"https://github.com/guidepup/guidepup-playwright/workflows/Test/badge.svg\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/guidepup/guidepup-playwright/blob/main/LICENSE\"\u003e\u003cimg alt=\"@guidepup/playwright uses the MIT license\" src=\"https://img.shields.io/github/license/guidepup/guidepup-playwright\" /\u003e\u003c/a\u003e\n\n## [Documentation](https://guidepup.dev) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)\n\n[![MacOS Monetary Support](https://img.shields.io/badge/macos-Monetary-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-monterey/id1576738294)\n[![MacOS Ventura Support](https://img.shields.io/badge/macos-Ventura-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-ventura/id1638787999)\n[![MacOS Sonoma Support](https://img.shields.io/badge/macos-Somona-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-sonoma/id6450717509)\n[![Windows 10 Support](https://img.shields.io/badge/windows-10-blue.svg?logo=windows10)](https://www.microsoft.com/en-gb/software-download/windows10ISO)\n[![Windows Server 2019 Support](https://img.shields.io/badge/windows_server-2019-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2019)\n[![Windows Server 2022 Support](https://img.shields.io/badge/windows_server-2022-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2022)\n\nThis package provides [Guidepup](https://github.com/guidepup/guidepup) integration with [Playwright](https://playwright.dev/) for writing screen reader tests that automate \u003ca href=\"https://www.guidepup.dev/docs/api/class-voiceover\"\u003e\u003cb\u003eVoiceOver on MacOS\u003c/b\u003e\u003c/a\u003e and \u003ca href=\"https://www.guidepup.dev/docs/api/class-nvda\"\u003e\u003cb\u003eNVDA on Windows\u003c/b\u003e\u003c/a\u003e.\n\n## Capabilities\n\n- **Full Control** - If a screen reader has a keyboard command, then Guidepup supports it.\n- **Mirrors Real User Experience** - Assert on what users really do and hear when using screen readers.\n\n## Getting Started\n\nSet up your environment for screen reader automation with [`@guidepup/setup`](https://github.com/guidepup/setup):\n\n```sh\nnpx @guidepup/setup\n```\n\nIf you are using GitHub Actions, check out the dedicated [`guidepup/setup-action`](https://github.com/marketplace/actions/guidepup-setup):\n\n```yaml\n- name: Setup Environment\n  uses: guidepup/setup-action\n```\n\nInstall `@guidepup/playwright` to your project:\n\n```sh\nnpm install --save-dev @guidepup/playwright @guidepup/guidepup @playwright/test\n```\n\nNote: you require `@guidepup/guidepup` and `@playwright/test` as they are peer dependencies to this project.\n\nAnd get cracking with your first screen reader tests in Playwright!\n\n## Examples\n\nHead over to the [Guidepup Website](https://www.guidepup.dev/) for guides, real world examples, environment setup, and complete API documentation with examples.\n\nYou can also check out these [awesome examples](https://github.com/guidepup/guidepup/tree/main/examples) to learn how you could use Guidepup with Playwright in your projects.\n\nAlternatively check out [this project](https://github.com/guidepup/aria-at-tests) which runs several thousand tests to assert screen reader compatibility against [W3C ARIA-AT](https://github.com/w3c/aria-at) test suite.\n\n### Playwright Config\n\nIn your `playwright.config.ts` add the following for the best results with Guidepup for Screen Reader automation:\n\n```ts\nimport { devices, PlaywrightTestConfig } from \"@playwright/test\";\nimport { screenReaderConfig } from \"@guidepup/playwright\";\n\nconst config: PlaywrightTestConfig = {\n  ...screenReaderConfig,\n\n  // ... your custom config\n};\n\nexport default config;\n```\n\nCheck out the configuration this adds [in the `config.ts` file](./src/config.ts).\n\n### Web Content Navigation\n\nIn addition to the Guidepup APIs the `voiceOver` and `nvda` instances provided by the Guidepup Playwright setup have an additional utility method `.navigateToWebContent()`.\n\nThis method will navigate the screen reader to the first element of the document body in the browser.\n\nUse this method after you navigate to a page and have made any necessary checks that the page has loaded as expected. For example, this is how you might use the method with NVDA:\n\n```ts\n// Navigate to the desired page\nawait page.goto(\"https://github.com/guidepup/guidepup\", {\n  waitUntil: \"load\",\n});\n\n// Wait for page to be ready\nawait page.locator('header[role=\"banner\"]').waitFor();\n\n// Navigate to the web content\nawait nvda.navigateToWebContent();\n\n// ... some commands\n```\n\n**Note:** This command clears all logs meaning `.spokenPhraseLog()` and `.itemTextLog()` are emptied. If logs from prior to the command are required, first store the logs in a variable for later use:\n\n```ts\n// ... some commands\n\n// Store spoken phrases\nconst spokenPhrases = await nvda.spokenPhraseLog();\n\n// Navigate to the web content\nawait nvda.navigateToWebContent();\n\n// ... some commands\n\n// Collect all spoken phrases\nconst allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];\n\n// ... do something with spoken phrases\n```\n\n### Providing Screen Reader Start Options\n\nThe options provided to `nvda.start([options])` or `voiceOver.start([options])` can be configured using `test.use(config)` as follows:\n\n```ts\n// VoiceOver Example\nimport { voiceOverTest as test } from \"@guidepup/playwright\";\n\ntest.use({ voiceOverStartOptions: { capture: \"initial\" } });\n```\n\n```ts\n// NVDA Example\nimport { nvdaTest as test } from \"@guidepup/playwright\";\n\ntest.use({ nvdaStartOptions: { capture: \"initial\" } });\n```\n\n### VoiceOver Example\n\n`playwright.config.ts`:\n\n```ts\nimport { devices, PlaywrightTestConfig } from \"@playwright/test\";\nimport { screenReaderConfig } from \"@guidepup/playwright\";\n\nconst config: PlaywrightTestConfig = {\n  ...screenReaderConfig,\n  reportSlowTests: null,\n  timeout: 5 * 60 * 1000,\n  retries: 2,\n  projects: [\n    {\n      name: \"webkit\",\n      use: { ...devices[\"Desktop Safari\"], headless: false },\n    },\n  ],\n};\n\nexport default config;\n```\n\n`voiceOver.spec.ts`:\n\n```ts\nimport { voiceOverTest as test } from \"@guidepup/playwright\";\nimport { expect } from \"@playwright/test\";\n\ntest.describe(\"Playwright VoiceOver\", () =\u003e {\n  test(\"I can navigate the Guidepup Github page with VoiceOver\", async ({\n    page,\n    voiceOver,\n  }) =\u003e {\n    // Navigate to Guidepup GitHub page\n    await page.goto(\"https://github.com/guidepup/guidepup\", {\n      waitUntil: \"load\",\n    });\n\n    // Wait for page to be ready\n    const header = page.locator('header[role=\"banner\"]');\n    await header.waitFor();\n\n    // Interact with the page\n    await voiceOver.navigateToWebContent();\n\n    // Move across the page menu to the Guidepup heading using VoiceOver\n    while ((await voiceOver.itemText()) !== \"Guidepup heading level 1\") {\n      await voiceOver.perform(voiceOver.keyboardCommands.findNextHeading);\n    }\n\n    // Assert that the spoken phrases are as expected\n    expect(JSON.stringify(await voiceOver.spokenPhraseLog())).toMatchSnapshot();\n  });\n});\n```\n\n### NVDA Example\n\n`playwright.config.ts`:\n\n```ts\nimport { devices, PlaywrightTestConfig } from \"@playwright/test\";\nimport { screenReaderConfig } from \"@guidepup/playwright\";\n\nconst config: PlaywrightTestConfig = {\n  ...screenReaderConfig,\n  reportSlowTests: null,\n  timeout: 5 * 60 * 1000,\n  retries: 2,\n  projects: [\n    {\n      name: \"firefox\",\n      use: { ...devices[\"Desktop Firefox\"], headless: false },\n    },\n  ],\n};\n\nexport default config;\n```\n\n`nvda.spec.ts`:\n\n```ts\nimport { nvdaTest as test } from \"@guidepup/playwright\";\nimport { expect } from \"@playwright/test\";\n\ntest.describe(\"Playwright NVDA\", () =\u003e {\n  test(\"I can navigate the Guidepup Github page with NVDA\", async ({\n    page,\n    nvda,\n  }) =\u003e {\n    // Navigate to Guidepup GitHub page\n    await page.goto(\"https://github.com/guidepup/guidepup\", {\n      waitUntil: \"load\",\n    });\n\n    // Wait for page to be ready and setup\n    const header = page.locator('header[role=\"banner\"]');\n    await header.waitFor();\n\n    // Interact with the page\n    await nvda.navigateToWebContent();\n\n    // Move across the page menu to the Guidepup heading using NVDA\n    while (\n      !(await nvda.lastSpokenPhrase()).includes(\"Guidepup, heading, level 1\")\n    ) {\n      await nvda.perform(nvda.keyboardCommands.moveToNextHeading);\n    }\n\n    // Assert that the spoken phrases are as expected\n    expect(JSON.stringify(await nvda.spokenPhraseLog())).toMatchSnapshot();\n  });\n});\n```\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/virtual-screen-reader`](https://github.com/guidepup/virtual-screen-reader/) - Reliable unit testing for your screen reader a11y workflows.\n- [`@guidepup/jest`](https://github.com/guidepup/jest/) - Jest matchers for reliable unit testing of your screen reader a11y workflows.\n\n## Resources\n\n- [Documentation](https://www.guidepup.dev/docs/example)\n- [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)\n- [Contributing](.github/CONTRIBUTING.md)\n- [Changelog](https://github.com/guidepup/guidepup-playwright/releases)\n- [MIT License](https://github.com/guidepup/guidepup-playwright/blob/main/LICENSE)\n","funding_links":["https://github.com/sponsors/cmorten"],"categories":["Integrations"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguidepup%2Fguidepup-playwright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguidepup%2Fguidepup-playwright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguidepup%2Fguidepup-playwright/lists"}