{"id":13398056,"url":"https://github.com/pa11y/pa11y","last_synced_at":"2025-05-13T16:08:38.508Z","repository":{"id":7264157,"uuid":"8576730","full_name":"pa11y/pa11y","owner":"pa11y","description":"Pa11y is your automated accessibility testing pal","archived":false,"fork":false,"pushed_at":"2024-10-04T14:00:44.000Z","size":2475,"stargazers_count":4128,"open_issues_count":57,"forks_count":263,"subscribers_count":218,"default_branch":"main","last_synced_at":"2025-03-09T13:02:25.676Z","etag":null,"topics":["a11y","accessibility","accessibility-testing","automated-testing","axe","html-codesniffer","javascript","pa11y","testing"],"latest_commit_sha":null,"homepage":"https://pa11y.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pa11y.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2013-03-05T09:51:11.000Z","updated_at":"2025-03-09T10:43:11.000Z","dependencies_parsed_at":"2023-02-18T20:40:19.760Z","dependency_job_id":"7daac86a-4d9d-4c4f-ac21-b76fe36d9368","html_url":"https://github.com/pa11y/pa11y","commit_stats":{"total_commits":527,"total_committers":66,"mean_commits":7.984848484848484,"dds":0.7893738140417457,"last_synced_commit":"242b650a8d96ca700beaf547614e1d50146f33d9"},"previous_names":[],"tags_count":114,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pa11y%2Fpa11y","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pa11y%2Fpa11y/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pa11y%2Fpa11y/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pa11y%2Fpa11y/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pa11y","download_url":"https://codeload.github.com/pa11y/pa11y/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250513576,"owners_count":21443201,"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","accessibility","accessibility-testing","automated-testing","axe","html-codesniffer","javascript","pa11y","testing"],"created_at":"2024-07-30T18:02:04.323Z","updated_at":"2025-04-23T20:47:09.496Z","avatar_url":"https://github.com/pa11y.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Practices","AI for Accessibility Testing","\u003ca id=\"1d9dec1320a5d774dc8e0e7604edfcd3\"\u003e\u003c/a\u003e工具-新添加的","Links","More Topics"],"sub_categories":["Development and Staging","\u003ca id=\"8f1b9c5c2737493524809684b934d49a\"\u003e\u003c/a\u003e文章\u0026\u0026视频","Tests","Accessibility"],"readme":"# Pa11y\n\nPa11y is your automated accessibility testing pal. It runs accessibility tests on your pages via the command line or Node.js, so you can automate your testing process.\n\n[![NPM version][shield-npm]][info-npm]\n[![Node.js version support][shield-node]][info-node]\n[![Build status][shield-build]][info-build]\n[![LGPL-3.0-only licensed][shield-license]][info-license]\n\nOn the command line:\n\n```sh\npa11y https://example.com\n```\n\nIn JavaScript:\n\n```js\nconst pa11y = require('pa11y');\n\npa11y('https://example.com').then((results) =\u003e {\n    // Use the results\n});\n```\n\n## Requirements\n\nPa11y 8 requires [Node.js][node] 18 or 20. An older version of Node.js can be used with [Pa11y 6 or below](#support-and-migration).\n\n### Linux and macOS\n\nTo install [Node.js][node] you can use [nvm][nvm]. For example, to install with `nvm` with [Homebrew][brew], and then install the latest version of Node:\n\n```sh\nbrew install nvm\nnvm install node\nnvm install-latest-npm\n```\n\nAlternatively, download a pre-built package from the [Node.js][node] website for your operating system.\n\n### Windows\n\nOn Windows 10, download a pre-built package from the [Node.js][node] website. Pa11y will be usable via the bundled Node.js application as well as the Windows command prompt.\n\n## Command-line interface\n\nInstall Pa11y globally with [npm][npm]:\n\n```sh\nnpm install -g pa11y\n```\n\n```console\n$ pa11y --help\n\nUsage: pa11y [options] \u003curl\u003e\n\n  Options:\n\n    -V, --version                  output the version number\n    -n, --environment              output details about the environment Pa11y will run in\n    -s, --standard \u003cname\u003e          the accessibility standard to use: WCAG2A, WCAG2AA (default), WCAG2AAA – only used by htmlcs runner\n    -r, --reporter \u003creporter\u003e      the reporter to use: cli (default), csv, json\n    -e, --runner \u003crunner\u003e          the test runners to use: htmlcs (default), axe\n    -l, --level \u003clevel\u003e            the level of issue to fail on (exit with code 2): error, warning, notice\n    -T, --threshold \u003cnumber\u003e       permit this number of errors, warnings, or notices, otherwise fail with exit code 2\n    -i, --ignore \u003cignore\u003e          types and codes of issues to ignore, a repeatable value or separated by semi-colons\n    --include-notices              Include notices in the report\n    --include-warnings             Include warnings in the report\n    -R, --root-element \u003cselector\u003e  a CSS selector used to limit which part of a page is tested\n    -E, --hide-elements \u003chide\u003e     a CSS selector to hide elements from testing, selectors can be comma separated\n    -c, --config \u003cpath\u003e            a JSON or JavaScript config file\n    -t, --timeout \u003cms\u003e             the timeout in milliseconds\n    -w, --wait \u003cms\u003e                the time to wait before running tests in milliseconds\n    -d, --debug                    output debug messages\n    -S, --screen-capture \u003cpath\u003e    a path to save a screen capture of the page to\n    -A, --add-rule \u003crule\u003e          WCAG 2.1 rules to include, a repeatable value or separated by semi-colons – only used by htmlcs runner\n    -h, --help                     output usage information\n```\n\n### Testing with `pa11y`\n\nFind accessibility issues at a URL:\n\n```sh\npa11y https://example.com\n```\n\nThe default [test runner](#runners) is [HTML_CodeSniffer][htmlcs], but [axe] is also supported. To use `axe`:\n\n```sh\npa11y https://example.com --runner axe\n```\n\nUse both axe and HTML_CodeSniffer in the same run:\n\n```sh\npa11y https://example.com --runner axe --runner htmlcs\n```\n\nGenerate results in CSV format, and output to a file, `report.csv`:\n\n```sh\npa11y https://example.com \u003e report.csv --reporter csv \n```\n\nFind accessibility issues in a local HTML file (absolute paths only, not relative):\n\n```sh\npa11y ./path/to/your/file.html\n```\n\n### Exit codes\n\nThe command-line tool uses the following exit codes:\n\n- `0`: Pa11y ran successfully, and there are no errors\n- `1`: Pa11y failed run due to a technical fault\n- `2`: Pa11y ran successfully but there are errors in the page\n\nBy default, only accessibility issues with a type of `error` will exit with a code of `2`. This is configurable with the `--level` flag which can be set to one of the following:\n\n- `error`: exit with a code of `2` on errors only, exit with a code of `0` on warnings and notices\n- `warning`: exit with a code of `2` on errors and warnings, exit with a code of `0` on notices\n- `notice`: exit with a code of `2` on errors, warnings, and notices\n- `none`: always exit with a code of `0`\n\n### Command-line configuration\n\nThe command-line tool can be configured with a JSON file as well as arguments. By default it will look for a `pa11y.json` file in the current directory, but you can change this with the `--config` flag:\n\n```sh\npa11y https://example.com --config ./path/to/config.json \n```\n\nIf any configuration is set both in a configuration file and also as a command-line option, the value set in the latter will take priority.\n\nFor more information on configuring Pa11y, see the [configuration documentation](#configuration).\n\n### Ignoring\n\nThe ignore flag can be used in several different ways. Separated by semi-colons:\n\n```sh\npa11y https://example.com --ignore \"issue-code-1;issue-code-2\" \n```\n\nor by using the flag multiple times:\n\n```sh\npa11y https://example.com --ignore issue-code-1 --ignore issue-code-2 \n```\n\nPa11y can also ignore notices, warnings, and errors up to a threshold number. This might be useful if you're using CI and don't want to break your build. The following example will return exit code 0 on a page with 9 errors, and return exit code 2 on a page with 10 or more errors.\n\n```sh\npa11y https://example.com --threshold 10 \n```\n\n### Reporters\n\nThe command-line tool can provide test results in a few different ways using the `--reporter` flag. The built-in reporters are:\n\n- `cli`: output test results in a human-readable format\n- `csv`: output test results as comma-separated values\n- `html`: output test results as an HTML page\n- `json`: output test results as a JSON array\n- `tsv`: output test results as tab-separated values\n\nYou can also write and publish your own reporters. Pa11y looks for reporters in your `node_modules` folder (with a naming pattern), and the current working directory. The first reporter found will be loaded. So with this command:\n\n```sh\npa11y https://example.com --reporter rainbows \n```\n\nThe following locations will be checked:\n\n```sh\n\u003ccwd\u003e/node_modules/pa11y-reporter-rainbows\n\u003ccwd\u003e/rainbows\n```\n\nA Pa11y reporter _must_ export a string property named `supports`. This is a [semver range] which indicates which versions of Pa11y the reporter supports:\n\n```js\nexports.supports = '^8.0.0';\n```\n\nA reporter should export the following methods, each returning one string. If your reporter needs to perform asynchronous operations, then it may return a promise which resolves to a string:\n\n```js\nbegin(); // Called when pa11y starts\nerror(message); // Called when a technical error is reported\ndebug(message); // Called when a debug message is reported\ninfo(message); // Called when an information message is reported\nresults(results); // Called with a test run's results\n```\n\n## JavaScript interface\n\nAdd Pa11y to your project with [npm][npm], most commonly as a development dependency:\n\n```sh\nnpm install pa11y --save-dev\n```\n\nRequire Pa11y:\n\n```js\nconst pa11y = require('pa11y');\n```\n\nRun Pa11y against a URL, the `pa11y` function returns a [Promise]:\n\n```js\npa11y(url).then((results) =\u003e {\n    // Use the results\n});\n```\n\nPa11y can also be run with [options](#configuration):\n\n```js\nconst options = { /* ... */ };\npa11y(url, options)).then((results) =\u003e {\n    // Use the results\n});\n```\n\nPa11y resolves with a `results` object, containing details about the page, and an array of accessibility issues found by the test runner:\n\n```js\n{\n    pageUrl: 'The tested URL',\n    documentTitle: 'Title of the page under test',\n    issues: [\n        {\n            code: 'WCAG2AA.Principle1.Guideline1_1.1_1_1.H30.2',\n            context: '\u003ca href=\"https://example.com/\"\u003e\u003cimg src=\"example.jpg\" alt=\"\"/\u003e\u003c/a\u003e',\n            message: 'Img element is the only content of the link, but is missing alt text. The alt text should describe the purpose of the link.',\n            selector: 'html \u003e body \u003e p:nth-child(1) \u003e a',\n            type: 'error',\n            typeCode: 1\n        }\n    ]\n}\n```\n\n### Transforming the results\n\nIf you wish to transform these results with a command-line reporter, `require` it into your code. The `csv`, `tsv`, `html`, `json`, and `markdown` reporters each expose a method `process`:\n\n```js\n// Assuming you've already run tests, and the results\n// are available in a `results` variable:\nconst htmlReporter = require('pa11y/lib/reporters/html');\nconst html = await htmlReporter.results(results);\n```\n\n### `async`/`await`\n\nPa11y uses promises, so you can use `async` functions and the `await` keyword:\n\n```js\nasync function runPa11y() {\n    try {\n        const results = await pa11y(url);\n        // Use the results\n    }\n    catch (error) {\n        // Handle error\n    }\n}\n\nrunPa11y();\n```\n\n### Callback interface\n\nFor those who prefer callbacks to promises:\n\n```js\npa11y(url, (error, results) =\u003e {\n    // Use results, handle error\n});\n```\n\n### Validating actions\n\nPa11y's `isValidAction` function can be used to validate an [action](#actions) string ahead of its use:\n\n```js\npa11y.isValidAction('click element #submit');  // true\npa11y.isValidAction('open the pod bay doors'); // false\n```\n\n## Configuration\n\nPa11y has lots of options you can use to change the way Headless Chrome runs, or the way your page is loaded. Options can be set either as a parameter on the `pa11y` function or in a [JSON configuration file](#command-line-configuration). Some are also available directly as [command-line options](#command-line-interface).\n\nBelow is a reference of all the options that are available:\n\n### `actions` (array)\n\nActions to be run before Pa11y tests the page. There are quite a few different actions available in Pa11y, the [Actions documentation](#actions) outlines each of them.\n\n```js\npa11y(url, {\n    actions: [\n        'set field #username to exampleUser',\n        'set field #password to password1234',\n        'click element #submit',\n        'wait for path to be /myaccount'\n    ]\n});\n```\n\nDefaults to an empty array.\n\n### `browser` (Browser) and `page` (Page)\n\nA [Puppeteer Browser instance][puppeteer-browser] which will be used in the test run. Optionally you may also supply a [Puppeteer Page instance][puppeteer-page], but this cannot be used between test runs as event listeners would be bound multiple times.\n\nIf either of these options are provided then there are several things you need to consider:\n\n  1. Pa11y's `chromeLaunchConfig` option will be ignored, you'll need to pass this configuration in when you create your Browser instance\n  2. Pa11y will not automatically close the Browser when the tests have finished running, you will need to do this yourself if you need the Node.js process to exit\n  3. It's important that you use a version of Puppeteer that meets the range specified in Pa11y's `package.json`\n  4. You _cannot_ reuse page instances between multiple test runs, doing so will result in an error. The page option allows you to do things like take screen-shots on a Pa11y failure or execute your own JavaScript before Pa11y\n\n**Note:** This is an advanced option. If you're using this, please mention in any issues you open on Pa11y and double-check that the Puppeteer version you're using matches Pa11y's.\n\n```js\nconst browser = await puppeteer.launch({\n    ignoreHTTPSErrors: true\n});\n\npa11y(url, {\n    browser: browser\n});\n\nbrowser.close();\n```\n\nA more complete example can be found in the [puppeteer examples](#puppeteer-example).\n\nDefaults to `null`.\n\n### `chromeLaunchConfig` (object)\n\nLaunch options for the Headless Chrome instance. [See the Puppeteer documentation for more information][puppeteer-launch].\n\n```js\npa11y(url, {\n    chromeLaunchConfig: {\n        executablePath: '/path/to/Chrome',\n        ignoreHTTPSErrors: false\n    }\n});\n```\n\nDefaults to:\n\n```js\n{\n    ignoreHTTPSErrors: true\n}\n```\n\n### `headers` (object)\n\nA key-value map of request headers to send when testing a web page.\n\n```js\npa11y(url, {\n    headers: {\n        Cookie: 'foo=bar'\n    }\n});\n```\n\nDefaults to an empty object.\n\n### `hideElements` (string)\n\nA CSS selector to hide elements from testing, selectors can be comma separated. Elements matching this selector will be hidden from testing by styling them with `visibility: hidden`.\n\n```js\npa11y(url, {\n    hideElements: '.advert, #modal, div[aria-role=presentation]'\n});\n```\n\n### `ignore` (array)\n\nAn array of result codes and types that you'd like to ignore. You can find the codes for each rule in the console output and the types are `error`, `warning`, and `notice`. Note: `warning` and `notice` messages are ignored by default.\n\n```js\npa11y(url, {\n    ignore: [\n        'WCAG2AA.Principle3.Guideline3_1.3_1_1.H57.2'\n    ]\n});\n```\n\nDefaults to an empty array.\n\n### `ignoreUrl` (boolean)\n\nWhether to use the provided [Puppeteer Page instance][puppeteer-page] as is or use the provided url. Both the [Puppeteer Page instance][puppeteer-page] and the [Puppeteer Browser instance][puppeteer-browser] are required alongside `ignoreUrl`.\n\n```js\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\n\npa11y(url, {\n    ignoreUrl: true,\n    page: page,\n    browser: browser\n});\n```\n\nDefaults to `false`.\n\n### `includeNotices` (boolean)\n\nWhether to include results with a type of `notice` in the Pa11y report. Issues with a type of `notice` are not directly actionable and so they are excluded by default. You can include them by using this option:\n\n```js\npa11y(url, {\n    includeNotices: true\n});\n```\n\nDefaults to `false`.\n\n### `includeWarnings` (boolean)\n\nWhether to include results with a type of `warning` in the Pa11y report. Issues with a type of `warning` are not directly actionable and so they are excluded by default. You can include them by using this option:\n\n```js\npa11y(url, {\n    includeWarnings: true\n});\n```\n\nDefaults to `false`.\n\n### `level` (string)\n\nThe level of issue which can fail the test (and cause it to exit with code 2) when running via the CLI. This should be one of `error` (the default), `warning`, or `notice`.\n\n```json\n{\n    \"level\": \"warning\"\n}\n```\n\nDefaults to `error`. Note this configuration is only available when using Pa11y on the command line, not via the JavaScript Interface.\n\n### `log` (object)\n\nAn object which implements the methods `debug`, `error`, and `info` which will be used to report errors and test information.\n\n```js\npa11y(url, {\n    log: {\n        debug: console.log,\n        error: console.error,\n        info: console.info\n    }\n});\n```\n\nEach of these defaults to an empty function.\n\n### `method` (string)\n\nThe HTTP method to use when running Pa11y.\n\n```js\npa11y(url, {\n    method: 'POST'\n});\n```\n\nDefaults to `GET`.\n\n### `postData` (string)\n\nThe HTTP POST data to send when running Pa11y. This should be combined with a `Content-Type` header. E.g to send form data:\n\n```js\npa11y(url, {\n    headers: {\n        'Content-Type': 'application/x-www-form-urlencoded'\n    },\n    method: 'POST',\n    postData: 'foo=bar\u0026bar=baz'\n});\n```\n\nOr to send JSON data:\n\n```js\npa11y(url, {\n    headers: {\n        'Content-Type': 'application/json'\n    },\n    method: 'POST',\n    postData: '{\"foo\": \"bar\", \"bar\": \"baz\"}'\n});\n```\n\nDefaults to `null`.\n\n### `reporter` (string)\n\nThe reporter to use while running the test via the CLI. [More about reporters](#reporters).\n\n```json\n{\n    \"reporter\": \"json\"\n}\n```\n\nDefaults to `cli`. Note this configuration is only available when using Pa11y on the command line, not via the JavaScript Interface.\n\n### `rootElement` (element)\n\nThe root element for testing a subset of the page opposed to the full document.\n\n```js\npa11y(url, {\n    rootElement: '#main'\n});\n```\n\nDefaults to `null`, meaning the full document will be tested. If the specified root element isn't found, the full document will be tested.\n\n### `runners` (array)\n\nAn array of runner names which correspond to existing and installed [Pa11y runners](#runners). If a runner is not found then Pa11y will error.\n\n```js\npa11y(url, {\n    runners: [\n        'axe',\n        'htmlcs'\n    ]\n});\n```\n\nDefaults to:\n\n```js\n[\n    'htmlcs'\n]\n```\n\n### `rules` (array)\n\nAn array of WCAG 2.1 guidelines that you'd like to include to the current standard. You can find the codes for each guideline in the [HTML Code Sniffer WCAG2AAA ruleset][htmlcs-wcag2aaa-ruleset]. **Note:** only used by htmlcs runner.\n\n```js\npa11y(url, {\n    rules: [\n        'Principle1.Guideline1_3.1_3_1_AAA'\n    ]\n});\n```\n\n### `screenCapture` (string)\n\nA file path to save a screen capture of the tested page to. The screen will be captured immediately after the Pa11y tests have run so that you can verify that the expected page was tested.\n\n```js\npa11y(url, {\n    screenCapture: `${__dirname}/my-screen-capture.png`\n});\n```\n\nDefaults to `null`, meaning the screen will not be captured. Note the directory part of this path must be an existing directory in the file system – Pa11y will not create this for you.\n\n### `standard` (string)\n\nThe accessibility standard to use when testing pages. This should be one of `WCAG2A`, `WCAG2AA`, or `WCAG2AAA`. **Note:** only used by htmlcs runner.\n\n```js\npa11y(url, {\n    standard: 'WCAG2A'\n});\n```\n\nDefaults to `WCAG2AA`.\n\n### `threshold` (number)\n\nThe number of errors, warnings, or notices to permit before the test is considered to have failed (with exit code 2) when running via the CLI.\n\n```json\n{\n    \"threshold\": 9\n}\n```\n\nDefaults to `0`. Note this configuration is only available when using Pa11y on the command line, not via the JavaScript Interface.\n\n### `timeout` (number)\n\nThe time in milliseconds that a test should be allowed to run before calling back with a timeout error.\n\nPlease note that this is the timeout for the _entire_ test run (including time to initialise Chrome, load the page, and run the tests).\n\n```js\npa11y(url, {\n    timeout: 500\n});\n```\n\nDefaults to `30000`.\n\n### `userAgent` (string)\n\nThe `User-Agent` header to send with Pa11y requests. This is helpful to identify Pa11y in your logs.\n\n```js\npa11y(url, {\n    userAgent: 'A11Y TESTS'\n});\n```\n\nDefaults to `pa11y/\u003cversion\u003e`.\n\n### `viewport` (object)\n\nThe viewport configuration. This can have any of the properties supported by the [puppeteer `setViewport` method][puppeteer-viewport].\n\n```js\npa11y(url, {\n    viewport: {\n        width: 320,\n        height: 480,\n        deviceScaleFactor: 2,\n        isMobile: true\n    }\n});\n```\n\nDefaults to:\n\n```js\n{\n    width: 1280,\n    height: 1024\n}\n```\n\n### `wait` (number)\n\nThe time in milliseconds to wait before running HTML_CodeSniffer on the page.\n\n```js\npa11y(url, {\n    wait: 500\n});\n```\n\nDefaults to `0`.\n\n## Actions\n\nActions are additional interactions that you can make Pa11y perform before the tests are run. They allow you to do things like click on a button, enter a value in a form, wait for a redirect, or wait for the URL fragment to change:\n\n```js\npa11y(url, {\n    actions: [\n        'click element #tab-1',\n        'wait for element #tab-1-content to be visible',\n        'set field #fullname to John Doe',\n        'clear field #middlename',\n        'check field #terms-and-conditions',\n        'uncheck field #subscribe-to-marketing',\n        'screen capture example.png',\n        'wait for fragment to be #page-2',\n        'wait for path to not be /login',\n        'wait for url to be https://example.com/',\n        'wait for #my-image to emit load',\n        'navigate to https://another-example.com/'\n    ]\n});\n```\n\nBelow is a reference of all the available actions and what they do on the page. Some of these take time to complete so you may need to increase the `timeout` option if you have a large set of actions.\n\n### `click element \u003cselector\u003e`\n\nClicks an element:\n\n```js\npa11y(url, {\n    actions: [\n        'click element #tab-1'\n    ]\n});\n```\n\nYou can use any valid [query selector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector), including classes and types.\n\n### `set field \u003cselector\u003e to \u003cvalue\u003e`\n\nSets the value of a text-based `input` or `select`:\n\n```js\npa11y(url, {\n    actions: [\n        'set field #fullname to John Doe'\n    ]\n});\n```\n\n### `clear field \u003cselector\u003e`\n\nClears the value of a text-based `input` or `select`:\n\n```js\npa11y(url, {\n    actions: [\n        'clear field #middlename'\n    ]\n});\n```\n\n### `check field \u003cselector\u003e`, `uncheck field \u003cselector\u003e`\n\nChecks/unchecks an `input` of type `radio` or `checkbox`:\n\n```js\npa11y(url, {\n    actions: [\n        'check field #terms-and-conditions',\n        'uncheck field #subscribe-to-marketing'\n    ]\n});\n```\n\n### `screen capture \u003cto-file-path.png\u003e`\n\nCaptures the screen, saving the image to a file, which can be useful between actions for debugging, or just for visual reassurance:\n\n```js\npa11y(url, {\n    actions: [\n        'screen capture example.png'\n    ]\n});\n```\n\n### `wait for`\n\n#### `wait for \u003cfragment|path|url\u003e`\n\nThis allows you to pause the test until a condition is met, and the page has either a given fragment, path, or URL. This will wait until Pa11y times out so it should be used after another action that would trigger the change in state. You can also wait until the page does **not** have a given fragment, path, or URL using the `to not be` syntax. This action takes one of the forms:\n\n- `wait for fragment to be \u003cfragment\u003e` (including the preceding `#`)\n- `wait for fragment to not be \u003cfragment\u003e` (including the preceding `#`)\n- `wait for path to be \u003cpath\u003e` (including the preceding `/`)\n- `wait for path to not be \u003cpath\u003e` (including the preceding `/`)\n- `wait for url to be \u003curl\u003e`\n- `wait for url to not be \u003curl\u003e`\n\nE.g.\n\n```js\npa11y(url, {\n    actions: [\n        'click element #login-link',\n        'wait for path to be /login'\n    ]\n});\n```\n\n#### `wait for element`'s state\n\nThis allows you to pause the test until an element on the page (matching a CSS selector) is either added, removed, visible, or hidden. This will wait until Pa11y times out so it should be used after another action that would trigger the change in state. This action takes one of the forms:\n\n- `wait for element \u003cselector\u003e to be added`\n- `wait for element \u003cselector\u003e to be removed`\n- `wait for element \u003cselector\u003e to be visible`\n- `wait for element \u003cselector\u003e to be hidden`\n\nE.g.\n\n```js\npa11y(url, {\n    actions: [\n        'click element #tab-2',\n        'wait for element #tab-1 to be hidden'\n    ]\n});\n```\n\n#### `wait for element`'s event\n\nThis allows you to pause the test until an element on the page (matching a CSS selector) emits an event. This will wait until Pa11y times out so it should be used after another action that would trigger the event. This action takes the form `wait for element \u003cselector\u003e to emit \u003cevent-type\u003e`. E.g.\n\n```js\npa11y(url, {\n    actions: [\n        'click element #tab-2',\n        'wait for element #tab-panel-to to emit content-loaded'\n    ]\n});\n```\n\n### `navigate to \u003curl\u003e`\n\nThis action allows you to navigate to a new URL if, for example, the URL is inaccessible using other methods. This action takes the form `navigate to \u003curl\u003e`. E.g.\n\n```js\npa11y(url, {\n    actions: [\n        'navigate to https://another-example.com'\n    ]\n});\n```\n\n## Runners\n\nPa11y supports multiple test runners which return different results. The built-in options are:\n\n- `axe`: run tests using [axe-core][axe].\n- `htmlcs` (default): run tests using [HTML_CodeSniffer][htmlcs]\n\nYou can also write and publish your own runners. Pa11y looks for runners in your `node_modules` folder (with a naming pattern), and the current working directory. The first runner found will be loaded. So with this command:\n\n```sh\npa11y https://example.com --runner custom-tool\n```\n\nThe following locations will be checked:\n\n```sh\n\u003ccwd\u003e/node_modules/pa11y-runner-custom-tool\n\u003ccwd\u003e/node_modules/custom-tool\n\u003ccwd\u003e/custom-tool\n```\n\nA Pa11y runner _must_ export a string property named `supports`. This is a [semver range] which indicates which versions of Pa11y the runner supports:\n\n```js\nexports.supports = '^8.0.0';\n```\n\nA Pa11y runner _must_ export a property named `scripts`. This is an array of strings which are paths to scripts which need to load before the tests can be run. This may be empty:\n\n```js\nexports.scripts = [\n    `${__dirname}/vendor/example.js`\n];\n```\n\nA runner _must_ export a `run` method, which returns a promise that resolves with test results (it's advisable to use an `async` function). The `run` method is evaluated in a browser context and so has access to a global `window` object.\n\nThe `run` method _must not_ use anything that's been imported using `require`, as it's run in a browser context. Doing so will error.\n\nThe `run` method is called with two arguments:\n\n- `options`: Options specified in the test runner\n- `pa11y`: The Pa11y test runner, which includes some helper methods:\n  - `pa11y.getElementContext(element)`: Get a short HTML context snippet for an element\n  - `pa11y.getElementSelector(element)`: Get a unique selector with which you can select this element in a page\n\nThe `run` method _must_ resolve with an array of Pa11y issues. These follow the format:\n\n```js\n{\n    code: '123', // An identifier for this error\n    element: {}, // The HTML element this issue relates to; `null` if no element is involved\n    message: 'example', // A description of the issue\n    type: 'error', // 'error', 'warning', or 'notice'\n    runnerExtras: {} // Additional data a runner is free to provide; unused by Pa11y itself\n}\n```\n\n## Examples\n\n### Basic example\n\nRun Pa11y on a URL and output the results. [See the example](example/basic/index.js).\n\n### Multiple URLs example\n\nRun Pa11y on multiple URLs at once and output the results. [See the example](example/multiple/index.js).\n\n### Actions example\n\nStep through some actions before Pa11y runs. This example logs into a fictional site then waits until the account page has loaded before running Pa11y. [See the example](example/actions/index.js).\n\n### Puppeteer example\n\nPass in pre-created Puppeteer browser and page instances so that you can reuse them between tests. [See the example](example/puppeteer/index.js).\n\n## Common questions and troubleshooting\n\nSee our [Troubleshooting guide](TROUBLESHOOTING.md) to get the answers to common questions about Pa11y, along with some ideas to help you troubleshoot any problems.\n\n## Tutorials and articles\n\nYou can find some useful tutorials and articles in the [Tutorials section](https://pa11y.org/tutorials/) of [pa11y.org](https://pa11y.org/).\n\n## Contributing\n\nThere are many ways to contribute to Pa11y, some of which we describe in the [contributing guide](CONTRIBUTING.md) for this repo.\n\nIf you're ready to contribute some code, clone this repo, commit your code to a new branch, then create a pull request to bring your changes into `main`. If you're an external contributor, [fork this repo][fork-pa11y] first, then follow the same process.\n\nPlease write unit tests for your code, and check that everything works by running the following before opening a pull request:\n\n```sh\nnpm run lint                # Lint the code\nnpm test                    # Run every test, reporting coverage\n```\n\nYou can also run test suites individually:\n\n```sh\nnpm run test-unit           # Run the unit tests alone\nnpm run test-integration    # Run the integration tests alone\nnpm run test-coverage       # Run the unit tests alone, reporting coverage\n```\n\n## Support and migration\n\n\u003e [!TIP]\n\u003e We maintain a [migration guide](MIGRATION.md) to help you migrate between major versions.\n\nWhen we release a new major version we will continue to support the previous major version for 6 months. This support will be limited to fixes for critical bugs and security issues. If you're opening an issue related to this project, please mention the specific version that the issue affects.\n\nThe following table lists the major versions available and, for each previous major version, its end-of-support date, and its final minor version released.\n\n| Major version | Final minor version | Node.js support  | Puppeteer version | Support end date         |\n| :------------ | :------------------ | :--------------- | :---------------- | :----------------------- |\n| `8`           |                     | `18`, `20`       | `^22`             | ✅ Current major version |\n| `7`           | `7.0`               | `18`, `20`       | `^20`             | October 2024             |\n| `6`           | `6.2`               | `12`, `14`, `16` | `~9.1`            | July 2024                |\n| `5`           | `5.3`               | `8`, `10`, `12`  | `^1`              | 2021-11-25               |\n| `4`           | `4.13`              | `4`, `6`, `8`    |                   | 2018-08-15               |\n| `3`           | `3.8`               | `0.12`, `4`      |                   | 2016-12-05               |\n| `2`           | `2.4`               | `0.10`, `0.12`   |                   | 2016-10-16               |\n| `1`           | `1.7`               | `0.10`           |                   | 2016-06-08               |\n\n## License\n\nPa11y is licensed under the [Lesser General Public License (LGPL-3.0-only)][info-license].  \nCopyright \u0026copy; 2013-2024, Team Pa11y and contributors\n\n[axe]: https://www.deque.com/axe/\n[brew]: https://mxcl.github.com/homebrew/\n[fork-pa11y]: (https://github.com/pa11y/pa11y/fork)\n[htmlcs-wcag2aaa-ruleset]: https://squizlabs.github.io/HTML_CodeSniffer/Standards/WCAG2/\n[htmlcs]: https://squizlabs.github.io/HTML_CodeSniffer/\n[info-build]: https://github.com/pa11y/pa11y/actions/workflows/tests.yml\n[info-license]: LICENSE\n[info-node]: package.json\n[info-npm]: https://www.npmjs.com/package/pa11y\n[node]: https://nodejs.org/\n[npm]: https://www.npmjs.com/\n[nvm]: https://github.com/nvm-sh/nvm\n[promise]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise\n[puppeteer-browser]: https://pptr.dev/next/api/puppeteer.browser\n[puppeteer-launch]: https://pptr.dev/next/api/puppeteer.puppeteerlaunchoptions\n[puppeteer-page]: https://pptr.dev/api/puppeteer.page\n[puppeteer-viewport]: https://pptr.dev/api/puppeteer.page.setviewport\n[semver range]: https://github.com/npm/node-semver#ranges\n[shield-build]: https://github.com/pa11y/pa11y/actions/workflows/tests.yml/badge.svg\n[shield-license]: https://img.shields.io/badge/license-LGPL%203.0-blue.svg\n[shield-node]: https://img.shields.io/node/v/pa11y.svg\n[shield-npm]: https://img.shields.io/npm/v/pa11y.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpa11y%2Fpa11y","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpa11y%2Fpa11y","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpa11y%2Fpa11y/lists"}