{"id":20253490,"url":"https://github.com/chanzuckerberg/axe-storybook-testing","last_synced_at":"2025-04-04T10:02:29.987Z","repository":{"id":37446130,"uuid":"289571057","full_name":"chanzuckerberg/axe-storybook-testing","owner":"chanzuckerberg","description":"Command line interface for testing Storybook stories for accessibility.","archived":false,"fork":false,"pushed_at":"2025-01-28T20:50:18.000Z","size":12913,"stargazers_count":55,"open_issues_count":1,"forks_count":7,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-28T09:01:42.189Z","etag":null,"topics":["accessibility","axe","testing"],"latest_commit_sha":null,"homepage":"","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/chanzuckerberg.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-22T21:38:00.000Z","updated_at":"2025-03-10T16:36:50.000Z","dependencies_parsed_at":"2024-05-13T14:40:18.328Z","dependency_job_id":"ca9acbf4-bfdf-45f1-9304-a8aff2b6f7e3","html_url":"https://github.com/chanzuckerberg/axe-storybook-testing","commit_stats":{"total_commits":859,"total_committers":26,"mean_commits":33.03846153846154,"dds":"0.41792782305005816","last_synced_commit":"2e5b26824a11e5817eee3873ff9d5dad169dcbed"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Faxe-storybook-testing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Faxe-storybook-testing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Faxe-storybook-testing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Faxe-storybook-testing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chanzuckerberg","download_url":"https://codeload.github.com/chanzuckerberg/axe-storybook-testing/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149505,"owners_count":20891954,"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":["accessibility","axe","testing"],"created_at":"2024-11-14T10:24:43.902Z","updated_at":"2025-04-04T10:02:29.949Z","avatar_url":"https://github.com/chanzuckerberg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @chanzuckerberg/axe-storybook-testing\n\n[![Package Status](https://img.shields.io/npm/v/@chanzuckerberg/axe-storybook-testing.svg)](https://www.npmjs.com/package/@chanzuckerberg/axe-storybook-testing) ![Tests](https://github.com/chanzuckerberg/axe-storybook-testing/workflows/Tests/badge.svg) [![Release](https://github.com/chanzuckerberg/axe-storybook-testing/actions/workflows/release.yml/badge.svg)](https://github.com/chanzuckerberg/axe-storybook-testing/actions/workflows/release.yml)\n\nCommand line interface for running [axe-core](https://github.com/dequelabs/axe-core) accessibility tests on your [Storybook stories](https://storybook.js.org/docs/react/api/csf).\n\nIf there are any violations, information about them will be printed, and the command will exit with a non-zero exit code. That way, you can use this as automated accessibility tests on CI.\n\n## Table of contents\n\n- [Code of conduct](#code-of-conduct)\n- [Minimum requirements](#minimum-requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Options](#options)\n- [Story parameters](#story-parameters)\n  - [disabledRules](#disabledrules)\n  - [mode](#mode)\n  - [runOptions](#runoptions)\n  - [context](#context)\n  - [config](#config)\n  - [skip](#skip)\n  - [timeout](#timeout)\n  - [waitForSelector](#waitforselector) (deprecated)\n- [TypeScript](#typescript)\n- [Developing](#developing)\n- [Security](#security)\n- [Inspiration](#inspiration)\n\n## Code of conduct\n\nThis project adheres to the [Contributor Covenant code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating, you are expected to uphold this code. Please report unacceptable behavior to \u003copensource@chanzuckerberg.com\u003e.\n\n## Minimum requirements\n\n- Node 18\n- Storybook 7.0 or 8.0 (for Storybook 6, use axe-storybook-testing v6.3.1)\n- axe-core 4.0\n\n## Installation\n\n```sh\n# via npm\nnpm install --save-dev @chanzuckerberg/axe-storybook-testing\n\n# or with Yarn\nyarn add --dev @chanzuckerberg/axe-storybook-testing\n```\n\n## Usage\n\nTo use:\n\n1. Add a script that creates a storybook build and then executes the axe-storybook command\n   ```jsonc\n   // In package.json\n   \"scripts\": {\n     \"test:axe\": \"storybook build \u0026\u0026 axe-storybook\"\n   },\n   ```\n\n2. Run the tests by calling the script from the previous step\n   ```sh\n   npm run test:axe\n   ```\n\n3. (Optional) Install more browsers. By default Chromium is installed. If you want to also use Firefox and/or Safari, install them with:\n   ```sh\n   npx playwright install\n   ```\n\nYou may also configure your script to run `storybook build --test` instead, and [configure storybook](https://storybook.js.org/docs/api/main-config/main-config-build) to disable irrelevant addons/features for testing.\n\n## Options\n\nThe command-line interface has the following options:\n\n| Option | Default | Values | Description |\n| ------ | ------- | ------ | ----------- |\n| `--browser` | `chromium` | chromium, firefox, webkit | Which browser to run the tests |\n| `--build-dir` | `storybook-static` | path | Storybook static build directory |\n| `--failing-impact` | `all` | all, minor, moderate, serious, critical | The lowest impact level that should be considered a failure |\n| `--headless` | `true` | boolean | Whether to run headlessly or not |\n| `--pattern` | `.*` | regex pattern | Only run tests that match a component name pattern |\n| `--port` |  | number | Port to run Storybook on while testing. If missing, an empty port will automatically be selected. Ignored if storybook-url is provided\n| `--reporter` | `spec` | spec, dot, nyan, tap, landing, list, progress, json, json-stream, min, doc, markdown, xunit | How to display the test run. Can be any [built-in Mocha reporter](https://mochajs.org/#reporters). |\n| `--reporter-options` |  | string | Options to pass to the mocha reporter. Especially useful with the xunit reporter - e.g. `--reporter-options output=./filename.xml` |\n| `--storybook-address`|  | url | **_Deprecated!_** Use `--storybook-url` instead. |\n| `--storybook-url` |  | url | Url to a running Storybook to test against. Alternative to `--build-dir`, which will be ignored if this is set. |\n| `--timeout` | 2000 | number | **_Deprecated!_** Use the `timeout` story parameter instead. |\n\nFor example, to run non-headlessly in Firefox, you would run\n\n```sh\n# If using npm\nnpm run storybook:axe -- --headless false --browser firefox\n\n# or, if using Yarn\nyarn storybook:axe --headless false --browser firefox\n```\n\n## Story parameters\n\nStories can use parameters to configure how axe-storybook-testing handles them.\n\nYou can provide these wherever Storybook accepts [parameters](https://storybook.js.org/docs/writing-stories/parameters) (story, component, or global).\n\n### disabledRules\n\nPrevent axe-storybook-testing from running specific Axe rules on a story by using the `disabledRules` parameter.\n\n```jsx\n// SomeComponent.stories.jsx\n\nexport const SomeStory = {\n  parameters: {\n    axe: {\n      disabledRules: ['select-name'],\n    },\n  }.\n};\n```\n\nRules can also be disabled globally by [setting this parameter for **all stories** in .storybook/preview.js](https://storybook.js.org/docs/react/writing-stories/parameters#global-parameters).\n\n```jsx\n// .storybook/preview.js\n\nexport const parameters = {\n  axe: {\n    disabledRules: ['select-name'],\n  },\n};\n```\n\n### mode\n\nSet whether errors for a story will fail the test suite or not.\n\nValid options are:\n- `off` - the story will be skipped and axe will not run on it. This is the same as setting `skip: true`.\n- `warn` - axe errors will be printed, but won't fail the test suite. Stories with this set will show up as pending.\n- `error` (default) - axe errors will fail the test suite for a story.\n\n```jsx\n// .storybook/preview.js\n\nexport const parameters = {\n  axe: {\n    mode: 'warn',\n  },\n};\n```\n\n### runOptions\n\nAllows use of any of the available [`axe.run`](https://www.deque.com/axe/core-documentation/api-documentation/#options-parameter) options. See the link for more details. When using `runOptions.rules` in combination with `disabledRules`, **`disabledRules` will always take precedent.**\n\n```jsx\nexport const SomeStory = {\n  parameters: {\n    axe: {\n      runOptions: {\n        preload: true,\n        selectors: true,\n        ...\n      }\n    }\n  }\n}\n```\n\n### context\n\n[Axe context](https://www.deque.com/axe/core-documentation/api-documentation/#context-parameter), which is passed to `axe.run`. Useful for including or excluding elements from the tests.\n\n```jsx\nexport const SomeStory = {\n  parameters: {\n    axe: {\n      context: {\n        exclude: '.foo',\n      },\n    }\n  }\n}\n```\n\n### config\n\nAxe configuration, which is passed to [axe.configure](https://www.deque.com/axe/core-documentation/api-documentation/#api-name-axeconfigure).\n\n```jsx\nexport const SomeStory = {\n  parameters: {\n    axe: {\n      config: {\n        checks: [...],\n        ...\n      }\n    }\n  }\n}\n```\n\n### skip\n\nPrevent axe-storybook-testing from running a story by using the `skip` parameter. This is shorthand for setting `mode: 'off'`.\n\n```jsx\n// SomeComponent.stories.jsx\n\nexport const SomeStory = {\n  parameters: {\n    axe: {\n      skip: true,\n    },\n  },\n};\n```\n\n### timeout\n\nOverrides global `--timeout` for this specific test\n\n```jsx\n// SomeComponent.stories.jsx\n\nexport const SomeStory = {\n  parameters: {\n    axe: {\n      timeout: 5000,\n    },\n  },\n};\n```\n\n### waitForSelector\n\n**Deprecated!**\n\nLegacy way of waiting for a selector before running Axe.\n\nNow we recommend using a Storybook [play function](https://storybook.js.org/docs/react/writing-stories/play-function) to do the same thing.\n\n```jsx\n// SomeComponent.stories.jsx\n\n// Old, deprecated way.\nexport const SomeStory = {\n  parameters: {\n    axe: {\n      waitForSelector: '#some-component-selector',\n    },\n  },\n};\n\n// New, better way using a play function - https://storybook.js.org/docs/react/writing-stories/play-function\nSomeStory.play = async () =\u003e {\n  await screen.findByText('some string');\n};\n```\n\n## TypeScript\n\naxe-storybook-testing provides TypeScript types for the story parameters listed above.\nStory parameters can be type checked by augmenting Storybook's `Parameter` type:\n\n```ts\n// overrides.d.ts\n\nimport type { AxeParams } from '@chanzuckerberg/axe-storybook-testing';\n\ndeclare module '@storybook/react' {\n  // Augment Storybook's definition of Parameters so it contains valid options for axe-storybook-testing\n  interface Parameters {\n    axe?: AxeParams;\n  }\n}\n```\n\nAnnotate your stories with the `StoryObj` type, and your parameters will be type-checked!\n\n```ts\n// SomeComponent.stories.ts\n\nexport const SomeStory: StoryObj\u003cArgs\u003e = {\n  parameters: {\n    axe: {\n      timeout: 5000,\n    },\n  },\n};\n```\n\n## Developing\n\nIf you want to work on this project or contribute back to it, see our [wiki entry on Development setup](https://github.com/chanzuckerberg/axe-storybook-testing/wiki/Development-setup).\n\n## Security\n\nTo report security issues, see [./SECURITY.md](./SECURITY.md).\n\n## Inspiration\n\nThis project was originally based on [@percy/storybook](https://github.com/percy/percy-storybook).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanzuckerberg%2Faxe-storybook-testing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchanzuckerberg%2Faxe-storybook-testing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanzuckerberg%2Faxe-storybook-testing/lists"}