{"id":19462807,"url":"https://github.com/widen/expect-axe-playwright","last_synced_at":"2025-04-25T08:31:40.015Z","repository":{"id":42567994,"uuid":"384233510","full_name":"Widen/expect-axe-playwright","owner":"Widen","description":"Expect matchers to perform Axe accessibility tests in your Playwright tests.","archived":false,"fork":false,"pushed_at":"2023-02-01T02:15:37.000Z","size":2749,"stargazers_count":19,"open_issues_count":0,"forks_count":5,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-03-26T01:04:24.014Z","etag":null,"topics":["axe","axe-core","playwright","playwright-test","testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Widen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-07-08T19:52:35.000Z","updated_at":"2024-02-07T10:10:55.000Z","dependencies_parsed_at":"2023-02-16T15:15:53.072Z","dependency_job_id":null,"html_url":"https://github.com/Widen/expect-axe-playwright","commit_stats":{"total_commits":46,"total_committers":7,"mean_commits":6.571428571428571,"dds":0.4782608695652174,"last_synced_commit":"4c2be94f5c86aa88ef7c9a0bf700b3c13631257b"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Widen%2Fexpect-axe-playwright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Widen%2Fexpect-axe-playwright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Widen%2Fexpect-axe-playwright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Widen%2Fexpect-axe-playwright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Widen","download_url":"https://codeload.github.com/Widen/expect-axe-playwright/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223992708,"owners_count":17237501,"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":["axe","axe-core","playwright","playwright-test","testing"],"created_at":"2024-11-10T18:05:49.691Z","updated_at":"2024-11-10T18:05:50.567Z","avatar_url":"https://github.com/Widen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# expect-axe-playwright\n\n[![Build](https://github.com/Widen/expect-axe-playwright/actions/workflows/build.yml/badge.svg)](https://github.com/Widen/expect-axe-playwright/actions/workflows/build.yml)\n[![npm version](https://img.shields.io/npm/v/expect-axe-playwright)](https://www.npmjs.com/package/expect-axe-playwright)\n[![changesets](https://img.shields.io/badge/maintained%20with-changesets-blue)](https://github.com/atlassian/changesets)\n\nExpect matchers to perform Axe accessibility tests in your Playwright tests.\n\n## Installation\n\n### npm\n\n```sh\nnpm install expect-axe-playwright\n```\n\n### Yarn\n\n```\nyarn add expect-axe-playwright\n```\n\n## Usage\n\n```ts\n// playwright.config.ts\nimport { expect } from '@playwright/test'\nimport matchers from 'expect-axe-playwright'\n\nexpect.extend(matchers)\n```\n\n## Why do I need it?\n\nThis project was inspired by\n[axe-playwright](https://github.com/abhinaba-ghosh/axe-playwright) which did a\ngreat job of integrating the [axe-core](https://github.com/dequelabs/axe-core)\nlibrary with some simple wrapper functions. However, the API is not as elegant\nfor testing as would be preferred. That's where `expect-axe-playwright` comes to\nthe rescue with the following features.\n\n- Direct integration with the `expect` API for simplicity and better error\n  messaging.\n- Automatic Axe script injection.\n- Auto-retry until timeout.\n- Works with [pages], [frames], and [locators].\n- HTML report with full violation details.\n- Project-level option configuration.\n\nHere are a few examples:\n\n```js\nawait expect(page).toPassAxe() // Page\nawait expect(page.locator('#foo')).toPassAxe() // Locator\nawait expect(page.frameLocator('iframe')).toPassAxe() // Frame locator\n```\n\n## API Documentation\n\n### `toPassAxe`\n\nThis function checks if a given page, frame, or element handle passes a set of accessibility checks.\n\nYou can test the entire page:\n\n```js\nawait expect(page).toPassAxe()\n```\n\nOr pass a locator to test part of the page:\n\n```js\nawait expect(page.locator('#my-element')).toPassAxe()\n```\n\nYou can also pass an [Axe results\nobject](https://www.deque.com/axe/core-documentation/api-documentation/#results-object)\nto the matcher:\n\n```js\nimport { waitForAxeResults } from 'expect-axe-playwright'\n\ntest('should pass common accessibility checks', async ({ page }) =\u003e {\n  const { results } = await waitForAxeResults(page)\n  await expect(results).toPassAxe()\n})\n```\n\n#### Word of Caution: Limitations to Accessibility Tests\n\n```js\ntoPassAxe() !== toBeAccessible()\n```\n\nIt's important to keep in mind that if your page passes the set of accessibility\nchecks that you've configured for Axe, that does not mean that your page is free\nof all accessibility barriers.\n\nIn fact, automated testing can only catch a fraction of the most common kinds of\naccessibility errors.\n\nAccessibility is analogous in ways to security. Imagine the following code:\n\n```js\nexpect(myApp).toBeSecure()\n```\n\nIt's very hard to say that anything is secure because you never know when\nsomeone is going to uncover a security vulnerability in your code. Similarly,\nit's very hard to say that anything you've built is totally accessible because\nyou never know when somebody will uncover a barrier you didn't know was there.\n\nFurthermore, of the commonly known accessibility barriers, only some can be\nfound through automated testing, which is then further subject to the\neffectiveness of the checker being used. A 2017 study on the [effectiveness of\nautomated accessibility testing\ntools](https://accessibility.blog.gov.uk/2017/02/24/what-we-found-when-we-tested-tools-on-the-worlds-least-accessible-webpage/)\nby the UK's Government Digital Service confirms this.\n\nTo echo [jest-axe](https://github.com/NickColley/jest-axe), tools like Axe are\nsimilar to code linters and spell checkers: they can find common issues but\ncannot guarantee that what you build works for users.\n\nYou'll also need to:\n\n- test your interface with the [assistive technologies that real users\n  use](https://www.gov.uk/service-manual/technology/testing-with-assistive-technologies#when-to-test)\n  (see also [WebAIM's survey\n  results](https://webaim.org/projects/screenreadersurvey8/#primary)).\n- include disabled people in user research.\n\n#### Axe run options\n\nYou can configure options that should be passed to aXe at the project or\nassertion level.\n\nTo configure a single assertion to use a different set of options, pass an\nobject with the desired arguments to the matcher.\n\n```js\nawait expect(page).toPassAxe({\n  rules: {\n    'color-contrast': { enabled: false },\n  },\n})\n```\n\nTo configure the entire project to use a different set of options, specify\noptions in `use.axeOptions` in your Playwright config file.\n\n```ts\n// playwright.config.ts\nimport { PlaywrightTestConfig } from '@playwright/test'\n\nconst config: PlaywrightTestConfig = {\n  use: {\n    axeOptions: {\n      rules: {\n        'color-contrast': { enabled: false },\n      },\n    },\n  },\n}\n\nexport default config\n```\n\n#### Report options\n\nYou can configure options that should be passed to the aXe HTML reporter at\nthe assertion level.\n\n```js\nawait expect(page.locator('#my-element')).toPassAxe({\n  filename: 'my-report.html',\n})\n```\n\nThis is particularly useful if you need to produce multiple aXe reports within\nthe same test as it would otherwise keep replacing the same report every time\nyou run the assertion.\n\n## Thanks\n\n- [axe-playwright](https://github.com/abhinaba-ghosh/axe-playwright) for the\n  inspiration and groundwork laid for using Axe with Playwright.\n\n[pages]: https://playwright.dev/docs/api/class-page\n[frames]: https://playwright.dev/docs/api/class-frame\n[locators]: https://playwright.dev/docs/api/class-locator\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiden%2Fexpect-axe-playwright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiden%2Fexpect-axe-playwright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiden%2Fexpect-axe-playwright/lists"}