{"id":13650939,"url":"https://github.com/abhinaba-ghosh/axe-playwright","last_synced_at":"2025-05-15T00:14:18.701Z","repository":{"id":37056035,"uuid":"272257323","full_name":"abhinaba-ghosh/axe-playwright","owner":"abhinaba-ghosh","description":":wheelchair:: Custom commands for Playwright to run accessibility (a11y) checks with axe-core","archived":false,"fork":false,"pushed_at":"2025-02-06T17:13:23.000Z","size":906,"stargazers_count":207,"open_issues_count":17,"forks_count":22,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-13T22:39:36.028Z","etag":null,"topics":["a11y","a11y-testing","accesibility","axe","axe-core","playwright"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/axe-playwright","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/abhinaba-ghosh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-14T18:08:42.000Z","updated_at":"2025-04-06T09:55:19.000Z","dependencies_parsed_at":"2025-02-28T18:17:58.393Z","dependency_job_id":null,"html_url":"https://github.com/abhinaba-ghosh/axe-playwright","commit_stats":{"total_commits":122,"total_committers":20,"mean_commits":6.1,"dds":0.5573770491803278,"last_synced_commit":"006c14a8af9d509df53751f335124b9ce75a9ef7"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinaba-ghosh%2Faxe-playwright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinaba-ghosh%2Faxe-playwright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinaba-ghosh%2Faxe-playwright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhinaba-ghosh%2Faxe-playwright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abhinaba-ghosh","download_url":"https://codeload.github.com/abhinaba-ghosh/axe-playwright/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254249206,"owners_count":22039029,"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-testing","accesibility","axe","axe-core","playwright"],"created_at":"2024-08-02T02:00:42.835Z","updated_at":"2025-05-15T00:14:13.667Z","avatar_url":"https://github.com/abhinaba-ghosh.png","language":"TypeScript","funding_links":[],"categories":["Integrations"],"sub_categories":[],"readme":"![logo](./docs/logo.png)\n\n# Axe-Playwright\n\n![Test Status](https://github.com/abhinaba-ghosh/axe-playwright/actions/workflows/tests.yml/badge.svg?branch=master)\n![Build Status](https://github.com/abhinaba-ghosh/axe-playwright/actions/workflows/npm-release.yml/badge.svg?branch=master)\n[![NPM release](https://img.shields.io/npm/v/axe-playwright.svg 'NPM release')](https://www.npmjs.com/package/axe-playwright)\n[![NPM Downloads](https://img.shields.io/npm/dt/axe-playwright.svg?style=flat-square)](https://www.npmjs.com/package/axe-playwright)\n\nAxe-core® is a powerful accessibility testing engine provided by Deque Systems that powers this package. Axe-Playwright provides simple commands to integrate the axe-core® library with your [Playwright](https://www.npmjs.com/package/playwright) tests. This integration functions seamlessly across all Playwright browsers: Chromium, Firefox, and WebKit.\n\nAxe-core® is a trademark of [Deque Systems, Inc.](https://www.deque.com/) in the US and other countries. This project is not formally affiliated with Deque, but we are big fans! Axe-core® is used here with permission.\n\n## Install and configure\n\n### Add as a dev dependency:\n\n```sh\nnpm i -D axe-playwright\n```\n\n### Install peer dependencies:\n\n```sh\nnpm i -D playwright\n```\n\nNOTE: axe-core® is now bundled and doesn't need to be installed separately.\n\n### Add Typings\n\n```json\n//tsconfig.json\n{\n  \"compilerOptions\": {\n    \"types\": [\"axe-playwright\"]\n  }\n}\n```\n\n## Commands\n\n### injectAxe\n\nThis will inject the axe-core® runtime into the page under test. You must run this after a call to page.goto() and before you run the checkA11y command.\n\nYou run this command with `injectAxe()` either in your test, or in a `beforeEach`, as long as the `visit` comes first.\n\n```js\nbeforeAll(async () =\u003e {\n  browser = await chromium.launch()\n  page = await browser.newPage()\n  await page.goto(`http://localhost:3000/login`)\n  await injectAxe(page)\n})\n```\n\n### configureAxe\n\n#### Purpose\n\nTo configure the format of the data used by aXe. This can be used to add new rules, which must be registered with the library to execute.\n\n#### Description\n\nUser specifies the format of the JSON structure passed to the callback of axe.run\n\n[Link - aXe Docs: axe.configure](https://www.deque.com/axe/documentation/api-documentation/#api-name-axeconfigure)\n\n```js\nit('Has no detectable a11y violations on load (custom configuration)', async () =\u003e {\n  // Configure aXe and test the page at initial load\n  await configureAxe(page, {\n    branding: {\n      brand: String,\n      application: String,\n    },\n    reporter: 'option',\n    checks: [Object],\n    rules: [Object],\n    locale: Object,\n  })\n  await checkA11y()\n})\n```\n\n### checkA11y\n\nThis will run axe against the document at the point in which it is called. This means you can call this after interacting with your page and uncover accessibility issues introduced as a result of rendering in response to user actions.\n\n#### Parameters on checkA11y (axe.run)\n\n##### page (mandatory)\n\nThe `page` instance of `playwright`.\n\n##### context (optional)\n\nDefines the scope of the analysis - the part of the DOM that you would like to analyze. This will typically be the document or a specific selector such as class name, ID, selector, etc.\n\n##### axeOptions (optional)\n\nSet of options passed into rules or checks, temporarily modifying them. This contrasts with axe.configure, which is more permanent.\n\nThe keys consist of [those accepted by `axe.run`'s options argument](https://www.deque.com/axe/documentation/api-documentation/#parameters-axerun) as well as custom `includedImpacts`, `detailedReport`, `verbose`, and `detailedReportOptions` keys.\n\nThe `includedImpacts` key is an array of strings that map to `impact` levels in violations. Specifying this array will only include violations where the impact matches one of the included values. Possible impact values are \"minor\", \"moderate\", \"serious\", or \"critical\".\n\nFiltering based on impact in combination with the `skipFailures` argument allows you to introduce `axe-playwright` into tests for a legacy application without failing in CI before you have an opportunity to address accessibility issues. Ideally, you would steadily move towards stricter testing as you address issues.\ne-effects, such as adding custom output to the terminal.\n\n**NOTE:** _This respects the `includedImpacts` filter and will only execute with violations that are included._\n\nThe `detailedReport` key is a boolean whether to print the more detailed report `detailedReportOptions` is an object with the shape\n\n```\n{\n html?: boolean // include the full html for the offending nodes\n}\n```\n\nThe `verbose` key is a boolean to whether to print the message `No accessibility violations detected!` when there aren't accessibility violations present in the test. For the `DefaultTerminalReporter` this is true and for the `v2 Reporter` this is false.\n\n##### skipFailures (optional, defaults to false)\n\nDisables assertions based on violations and only logs violations to the console output. If you set `skipFailures` as `true`, although accessibility check is not passed, your test will not fail. It will simply print the violations in the console, but will not make the test fail.\n\n##### reporter (optional)\n\nA class instance that implements the `Reporter` interface or values `default`, `v2` and `html`. Custom reporter instances can be supplied to override default reporting behaviour dictated by `DefaultTerminalReporter` set by the value `default`. `v2` is the new TerminalReporter inspired by the reports from [jest-axe](https://github.com/nickcolley/jest-axe). `html` reporter will generate external HTML file.\n\nNote! `html` reporter will disable printed to logs violations.\n\n##### options (dedicated for axe-html-reporter)\n\nOptions dedicated for HTML reporter. \n[axe-html-reporter](https://www.npmjs.com/package/axe-html-reporter)\n\n### getAxeResults\n\nThis will run axe against the document at the point in which it is called, then returns the full set of results as reported by `axe.run`.\n\n#### Parameters on getAxeResults\n\n##### page (mandatory)\n\nThe `page` instance of `playwright`.\n\n##### context (optional)\n\nDefines the scope of the analysis - the part of the DOM that you would like to analyze. This will typically be the document or a specific selector such as class name, ID, selector, etc.\n\n##### options (optional)\n\nSet of options passed into rules or checks, temporarily modifying them. This contrasts with axe.configure, which is more permanent.\n\nThe object is of the same type which is [accepted by `axe.run`'s options argument](https://www.deque.com/axe/documentation/api-documentation/#parameters-axerun) and directly forwarded to it.\n\n### getViolations\n\nThis will run axe against the document at the point in which it is called, then return you an array of accessibility violations (i.e. the `violations` array included in the `getAxeResults` result).\n\n#### Parameters on getViolations (axe.run)\n\nIdentical to [parameters of getAxeResults](#parameters-on-getAxeResults).\n\n### reportViolations\n\nReports violations based on the `Reporter` concrete implementation behaviour. \n\n#### Parameters on reportViolations\n\n##### violations (mandatory)\n\nAn array of Axe violations to be printed.\n\n##### reporter (mandatory)\n\nA class instance that implements the `Reporter` interface. Custom reporter instances can be supplied to override default reporting behaviour dictated by `DefaultTerminalReporter`.\n\n### Examples\n\n#### Basic usage\n\n```ts\nimport { chromium, Browser, Page } from 'playwright'\nimport { injectAxe, checkA11y, getViolations, reportViolations } from 'axe-playwright'\n\nlet browser: Browser\nlet page: Page\n\ndescribe('Playwright web page accessibility test', () =\u003e {\n  beforeAll(async () =\u003e {\n    browser = await chromium.launch()\n    page = await browser.newPage()\n    await page.goto(`file://${process.cwd()}/test/site.html`)\n    await injectAxe(page)\n  })\n\n  it('simple accessibility run', async () =\u003e {\n    await checkA11y(page)\n  })\n\n  it('check a11y for the whole page and axe run options', async () =\u003e {\n    await checkA11y(page, null, {\n      axeOptions: {\n        runOnly: {\n          type: 'tag',\n          values: ['wcag2a'],\n        },\n      },\n    })\n  })\n\n  it('check a11y for the specific element', async () =\u003e {\n    await checkA11y(page, 'input[name=\"password\"]', {\n      axeOptions: {\n        runOnly: {\n          type: 'tag',\n          values: ['wcag2a'],\n        },\n      },\n    })\n  })\n\n  it('gets and reports a11y for the specific element', async () =\u003e {\n    const violations = await getViolations(page, 'input[name=\"password\"]', {\n      runOnly: {\n        type: 'tag',\n        values: ['wcag2a'],\n      },\n    })\n\n    reportViolations(violations, new YourAwesomeCsvReporter('accessibility-report.csv'))\n\n    expect(violations.length).toBe(0)\n  })\n\n  afterAll(async () =\u003e {\n    await browser.close()\n  })\n})\n```\n\nThis custom logging behavior results in terminal output like this:\n\n![Custom terminal logging](./docs/terminal_output_example.png)\n\n#### Detailed Report\n\nThe detailed report is disabled by default, but can be enabled by including the `detailedReport` property in the `checkAlly` options.\n\n```ts\nimport { chromium, Browser, Page } from 'playwright'\nimport { injectAxe, checkA11y } from 'axe-playwright'\n\nlet browser: Browser\nlet page: Page\n\ndescribe('Playwright web page accessibility test', () =\u003e {\n  beforeAll(async () =\u003e {\n    browser = await chromium.launch()\n    page = await browser.newPage()\n    await page.goto(`file://${process.cwd()}/test/site.html`)\n    await injectAxe(page)\n  })\n\n  // Prints outs a detailed report per node with an array of numbers of which violations from the summary affect that node\n  it('print out a detailed report on violations', async () =\u003e {\n    await checkA11y(page, null, {\n      detailedReport: true,\n    })\n  })\n\n  // Same as above, but includes the html of the offending node\n  it('print out a detailed report on violations', async () =\u003e {\n    await checkA11y(page, null, {\n      detailedReport: true,\n      detailedReportOptions: { html: true },\n    })\n  })\n\n  afterAll(async () =\u003e {\n    await browser.close()\n  })\n})\n```\n\n![Detailed Report](./docs/detailed-report-example.png)\n\n![Detailed Report with HTML](./docs/detailed-report-html-example.png)\n\n#### HTML Report\n\nThanks to [axe-html-reporter](https://www.npmjs.com/package/axe-html-reporter) you can generate HTML report(s).\nFrom default HTML file(s) will be generated under `/artifacts/accessibilityReport.html`. \nReport's options can customized from `checkAlly` level:\n\n```\nawait checkA11y(\n      page,\n      'form',\n      {\n        axeOptions: {\n          runOnly: {\n            type: 'tag',\n            values: ['wcag2a'],\n          },\n        },\n      },\n      true,\n      'html',\n      {\n        outputDirPath: 'results',\n        outputDir: 'accessibility',\n        reportFileName: 'accessibility-audit.html'\n      }\n    )\n```\n#### JUnit Report\n\n```\nawait checkA11y(\n      page,\n      'form',\n      {\n        axeOptions: {\n          runOnly: {\n            type: 'tag',\n            values: ['wcag2a'],\n          },\n        },\n      },\n      true,\n      'junit',\n     {\n        outputDirPath: 'results',\n        outputDir: 'accessibility',\n        reportFileName: 'accessibility-audit.xml',\n      },\n    )\n```\n## Before you Go\n\nIf it works for you , leave a [Star](https://github.com/abhinaba-ghosh/axe-playwright)! :star:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhinaba-ghosh%2Faxe-playwright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabhinaba-ghosh%2Faxe-playwright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhinaba-ghosh%2Faxe-playwright/lists"}