{"_id":"@-ralph/cypress-axe","name":"@-ralph/cypress-axe","dist-tags":{"latest":"1.0.0-rc"},"versions":{"1.0.0-rc":{"name":"@-ralph/cypress-axe","version":"1.0.0-rc","license":"MIT","description":"Test accessibility with axe-core in Cypress","homepage":"https://github.com/component-driven/cypress-axe","repository":{"type":"git","url":"git+https://github.com/component-driven/cypress-axe.git"},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","lint":"eslint . --cache --fix","pretest":"npm run lint","test":"npm run test:e2e:ci","posttest":"npm run format","format":"prettier --loglevel warn --write \"**/*.{js,md}\"","prepublishOnly":"npm run build","start":"http-server test","cypress":"cypress open","cypress:headless":"cypress run --browser chrome --headless","test:e2e":"start-server-and-test start 8080 cypress","test:e2e:ci":"start-server-and-test start 8080 cypress:headless"},"engines":{"node":">=10"},"dependencies":{},"peerDependencies":{"axe-core":"^3 || ^4","cypress":"^10"},"devDependencies":{"@types/node":"^14.14.8","@typescript-eslint/eslint-plugin":"^4.8.1","@typescript-eslint/parser":"^4.8.1","axe-core":"^4.0.2","cypress":"^10.1.0","eslint":"^7.12.0","eslint-config-tamia":"^7.2.6","http-server":"^0.12.3","husky":"^4.3.0","lint-staged":"^10.5.0","prettier":"^2.1.2","start-server-and-test":"^1.11.5","typescript":"^4.0.5"},"authors":[{"name":"Andy Van Slaars","url":"https://vanslaars.io"},{"name":"Artem Sapegin","url":"https://sapegin.me"}],"keywords":["a11y","accessibility","axe","axe-core","cypress"],"husky":{"hooks":{"pre-commit":"lint-staged"}},"lint-staged":{"*.js":"eslint --cache --fix","*.{js,md}":"prettier --write"},"gitHead":"1672a81160e6fff5f56a013ef2ff1cfd5390ec0c","bugs":{"url":"https://github.com/component-driven/cypress-axe/issues"},"_id":"@-ralph/cypress-axe@1.0.0-rc","_nodeVersion":"16.13.0","_npmVersion":"8.1.0","dist":{"integrity":"sha512-EtqXszt0EOiFlMQcwrQTmq26Td5B1OHSY8lxRdcuz5vNBmS7YucyPqjU31AgNTGcj8RDljsJYoj3gC8ZrFQ3GA==","shasum":"a634f7c0be9c5d753514d9cd25dcb462c03edc4d","tarball":"https://registry.npmjs.org/@-ralph/cypress-axe/-/cypress-axe-1.0.0-rc.tgz","fileCount":5,"unpackedSize":19720,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFamvlCtqcmviD3P/3j7vgSvcUUaCOLXpZguC+QZ+Im5AiApMVq+/FXr5aHtjUmH5eqgvlAqJE/0GJyzdiprxEkU4g=="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJi46zKACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmqKYRAAoTVNleroty8K2W5gntpwO5cOMfuARajAuVPr/tuWRE+ghZar\r\nkOJN7rub/OWxGaD0ra/AN/u6hEYFzLyquv311fPh3h92c+9mV0ceNA6gZcL8\r\nPkJhxriXeJvgFnRKad4jNvKCyXnEJKL0KdcWPuAoCCZ7wxUQeveuijPuaVp1\r\nrxrzihjfF5T0C+bJwN0ZT/nyFJRFdQ2tNbFmftsbYCjdA84k3PJ55fkPuldN\r\nnyJVjO/idhGHb+deIazVl3EPN9y4ZNtqb3DW2P9ujgcz2SY2EEGQ1iyCybuR\r\nZVUPw4z4gwwq26efFNhCKCsZqegY4seID4bgG6lMdz1uDE1Ahk/2QiuBLuJ+\r\n1Pt2WkSbgWcA2gOtOSIKG8SxradeobeXiaVSXEZLKyYh9kcuHKO9KzO7HXMa\r\n2ZWp04WLNVYzxuV2ahiufHu0dQA6IS0r+3TKOyL9DdemHGBLNphZLxogqynS\r\nG+CFxVHTt/uuzkPJCxjcDx6eTyhoWVN+JqqerFEBndMdZmuMOSt25H2P79DH\r\n5mtTS8heWDrODVF9fEWx1GVSH01B8g5lcFDoIGdoU8u8yEmE5cb0YI0p5Nhn\r\n5Gp9TBZnc6/U6l+Os6kqTsNOsS6pDSAiRSIFukd1QamDCBjKzXDJYz1ujKhr\r\n4aWx7ZhWzbArrWIfVeryTNUf8jqG5zCqJrk=\r\n=Tscv\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"-ralph","email":"acastofthousands@gmail.com"},"directories":{},"maintainers":[{"name":"-ralph","email":"acastofthousands@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/cypress-axe_1.0.0-rc_1659088073953_0.3790836783232925"},"_hasShrinkwrap":false}},"time":{"created":"2022-07-29T09:47:53.901Z","1.0.0-rc":"2022-07-29T09:47:54.140Z","modified":"2022-07-29T09:47:54.274Z"},"maintainers":[{"name":"-ralph","email":"acastofthousands@gmail.com"}],"description":"Test accessibility with axe-core in Cypress","homepage":"https://github.com/component-driven/cypress-axe","keywords":["a11y","accessibility","axe","axe-core","cypress"],"repository":{"type":"git","url":"git+https://github.com/component-driven/cypress-axe.git"},"bugs":{"url":"https://github.com/component-driven/cypress-axe/issues"},"license":"MIT","readme":"# cypress-axe\n\n[![npm](https://img.shields.io/npm/v/cypress-axe.svg)](https://www.npmjs.com/package/cypress-axe) [![Node.js CI status](https://github.com/component-driven/cypress-axe/workflows/Node.js%20CI/badge.svg)](https://github.com/component-driven/cypress-axe/actions)\n\nTest accessibility with [axe-core](https://github.com/dequelabs/axe-core) in [Cypress](https://cypress.io).\n\n## Installation\n\n1. **Install `cypress-axe` from npm:**\n\n- For Cypress v10 install latest cypress-axe\n\n```sh\nnpm install --save-dev cypress-axe\n```\n\n- For Cypress v9 install 0.x.x\n\n```sh\nnpm install --save-dev cypress-axe@0.14.0\n```\n\n1. **Install peer dependencies:**\n\n- For Cypress v10 and above\n\n```sh\nnpm install --save-dev cypress axe-core\n```\n\n- For Cypress v9 and below install the specific cypress version you are using For example if you are using cypress v9.6.0\n\n```sh\nnpm install --save-dev cypress@9.6.0 axe-core\n```\n\n1. **Include the commands.**\n\n- For Cypress v10 and above update `cypress/support/e2e.js` file to include the cypress-axe commands by adding:\n- For Cypress v9 and below update `cypress/support/index.js` file to include the cypress-axe commands by adding:\n\n```js\nimport 'cypress-axe'\n```\n\n4. **Add a task to log the messages to the terminal** when Cypress executes the spec files. [Example - configuring log task](https://docs.cypress.io/api/commands/task.html#Usage).\n\n### TypeScript\n\nIf you’re using TypeScript, add cypress-axe types to your Cypress’ `tsconfig.json` file:\n\n```json\n{\n  \"compilerOptions\": {\n    \"baseUrl\": \"./\",\n    \"target\": \"es5\",\n    \"lib\": [\"esnext\", \"dom\"],\n    \"types\": [\"cypress\", \"cypress-axe\"]\n  },\n  \"include\": [\".\"]\n}\n```\n\n## Commands\n\n### cy.injectAxe\n\nThis will inject the `axe-core` runtime into the page under test. You must run this **after** a call to `cy.visit()` and before you run the `checkA11y` command.\n\nYou run this command with `cy.injectAxe()` either in your test, or in a `beforeEach`, as long as the `visit` comes first.\n\n```js\nbeforeEach(() => {\n  cy.visit('http://localhost:9000')\n  cy.injectAxe()\n})\n```\n\n### cy.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)', () => {\n  // Configure aXe and test the page at initial load\n  cy.configureAxe({\n    branding: {\n      brand: String,\n      application: String\n    },\n    reporter: 'option',\n    checks: [Object],\n    rules: [Object],\n    locale: Object\n  })\n  cy.checkA11y()\n})\n```\n\n### cy.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 cy.checkA11y (axe.run)\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 keys consist of [those accepted by `axe.run`'s options argument](https://www.deque.com/axe/documentation/api-documentation/#parameters-axerun) as well as a custom `includedImpacts` key.\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 `cypress-axe` 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.\n\n##### violationCallback (optional)\n\nAllows you to define a callback that receives the violations for custom side-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\n##### failOn (optional, defaults to 'any')\n\nSet a level to fail on. Options are 'any', 'none' or an array of levels ['minor', 'moderate', 'serious', 'critical'];\n\nAllows you to set the level of severity to fail on. If set to 'any', any level of violation will fail, whilst 'none' will allow all violations to pass. You can fine tune this with a severity array, e.g. `['serious', 'critical']` will only fail on errors at the serious or critical level. This allows you to log all violations using e.g. `cy.checkA11y(null, null, terminalLog)` whilst only failing for a particular severity level.\n\n### Examples\n\n#### Basic usage\n\n```js\n// Basic usage\nit('Has no detectable a11y violations on load', () => {\n  // Test the page at initial load\n  cy.checkA11y()\n})\n\n// Applying a context and run parameters\nit('Has no detectable a11y violations on load (with custom parameters)', () => {\n  // Test the page at initial load (with context and options)\n  cy.checkA11y('.example-class', {\n    runOnly: {\n      type: 'tag',\n      values: ['wcag2a']\n    }\n  })\n})\n\nit('Has no detectable a11y violations on load (filtering to only include critical impact violations)', () => {\n  // Test on initial load, only report and assert for critical impact items\n  cy.checkA11y(null, {\n    includedImpacts: ['critical']\n  })\n})\n\n// Basic usage after interacting with the page\nit('Has no a11y violations after button click', () => {\n  // Interact with the page, then check for a11y issues\n  cy.get('button').click()\n  cy.checkA11y()\n})\n\nit('Only logs a11y violations while allowing the test to pass', () => {\n  // Do not fail the test when there are accessibility failures\n  cy.checkA11y(null, null, null, 'none')\n})\n\nit('Only logs a11y violations of level \"critical\"', () => {\n  // Do not fail the test when there are accessibility failures below the 'critical' level\n  cy.checkA11y(null, null, ['critical'])\n})\n```\n\n#### Using the violationCallback argument\n\nThe violation callback parameter accepts a function and allows you to add custom behavior when violations are found.\n\nThis example adds custom logging to the terminal running Cypress, using `cy.task` and the `violationCallback` argument for `cy.checkA11y`\n\n##### In Cypress plugins file\n\nThis registers a `log` task as seen in the [Cypress docs for cy.task](https://docs.cypress.io/api/commands/task.html#Usage) as well as a `table` task for sending tabular data to the terminal.\n\n```js\nmodule.exports = (on, config) => {\n  on('task', {\n    log(message) {\n      console.log(message)\n\n      return null\n    },\n    table(message) {\n      console.table(message)\n\n      return null\n    }\n  })\n}\n```\n\n#### In your spec file\n\nThen we create a function that uses our tasks and pass it as the `validationCallback` argument to `cy.checkA11y`\n\n```js\n// Define at the top of the spec file or just import it\nfunction terminalLog(violations) {\n  cy.task(\n    'log',\n    `${violations.length} accessibility violation${\n      violations.length === 1 ? '' : 's'\n    } ${violations.length === 1 ? 'was' : 'were'} detected`\n  )\n  // pluck specific keys to keep the table readable\n  const violationData = violations.map(\n    ({ id, impact, description, nodes }) => ({\n      id,\n      impact,\n      description,\n      nodes: nodes.length\n    })\n  )\n\n  cy.task('table', violationData)\n}\n\n// Then in your test...\nit('Logs violations to the terminal', () => {\n  cy.checkA11y(null, null, terminalLog)\n})\n```\n\nThis custom logging behavior results in terminal output like this:\n\n![Custom terminal logging with cy.task and validationCallback](terminal_output_example.png)\n\n## Standard Output\n\nWhen accessibility violations are detected, your test will fail and an entry titled \"A11Y ERROR!\" will be added to the command log for each type of violation found (they will be above the failed assertion). Clicking on those will reveal more specifics about the error in the DevTools console.\n\n![Cypress and DevTools output for passing and failing axe-core audits](cmd_log.png)\n\n## Authors\n\nThe project was created by [Andy Van Slaars](https://vanslaars.io/), and maintained by [Artem Sapegin](https://sapegin.me).\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#emoji-key)):\n\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<table>\n  <tr>\n    <td align=\"center\"><a href=\"https://samcus.co\"><img src=\"https://avatars2.githubusercontent.com/u/14907938?v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>Samuel Custer</b></sub></a><br /><a href=\"https://github.com/component-driven/cypress-axe/commits?author=samcus\" title=\"Code\">💻</a> <a href=\"https://github.com/component-driven/cypress-axe/commits?author=samcus\" title=\"Documentation\">📖</a></td>\n    <td align=\"center\"><a href=\"https://github.com/miketoth\"><img src=\"https://avatars2.githubusercontent.com/u/2512676?v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>Michael Toth</b></sub></a><br /><a href=\"https://github.com/component-driven/cypress-axe/commits?author=miketoth\" title=\"Code\">💻</a></td>\n    <td align=\"center\"><a href=\"https://github.com/NicholasBoll\"><img src=\"https://avatars2.githubusercontent.com/u/338257?v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>Nicholas Boll</b></sub></a><br /><a href=\"https://github.com/component-driven/cypress-axe/commits?author=NicholasBoll\" title=\"Code\">💻</a></td>\n    <td align=\"center\"><a href=\"https://github.com/michaeljacobdavis\"><img src=\"https://avatars2.githubusercontent.com/u/916905?v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>Mike Davis</b></sub></a><br /><a href=\"https://github.com/component-driven/cypress-axe/commits?author=michaeljacobdavis\" title=\"Code\">💻</a></td>\n    <td align=\"center\"><a href=\"https://github.com/chit786\"><img src=\"https://avatars2.githubusercontent.com/u/18376182?v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>chit786</b></sub></a><br /><a href=\"https://github.com/component-driven/cypress-axe/commits?author=chit786\" title=\"Code\">💻</a> <a href=\"https://github.com/component-driven/cypress-axe/commits?author=chit786\" title=\"Documentation\">📖</a></td>\n    <td align=\"center\"><a href=\"https://github.com/acourdavault\"><img src=\"https://avatars0.githubusercontent.com/u/27222128?v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>Adrien courdavault</b></sub></a><br /><a href=\"https://github.com/component-driven/cypress-axe/commits?author=acourdavault\" title=\"Code\">💻</a></td>\n    <td align=\"center\"><a href=\"http://brett-zamir.me\"><img src=\"https://avatars3.githubusercontent.com/u/20234?v=4\" width=\"100px;\" alt=\"\"/><br /><sub><b>Brett Zamir</b></sub></a><br /><a href=\"https://github.com/component-driven/cypress-axe/commits?author=brettz9\" title=\"Code\">💻</a></td>\n  </tr>\n</table>\n\n<!-- markdownlint-enable -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n## License\n\nMIT License, see the included [License.md](License.md) file.\n","readmeFilename":"README.md"}