@chanzuckerberg/axe-storybook-testing

Command line interface for running axe-core accessibility tests on your Storybook stories.

If 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.

Table of contents

• Code of conduct
• Minimum requirements
• Installation
• Usage
• Options
• Story parameters
  • disabledRules
  • mode
  • runOptions
  • context
  • config
  • skip
  • timeout
  • waitForSelector (deprecated)
• TypeScript
• Developing
• Security
• Inspiration

Code of conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.

Minimum requirements

• Node 18
• Storybook 7.0 or 8.0 (for Storybook 6, use axe-storybook-testing v6.3.1)
• axe-core 4.0

Installation

# via npm
npm install --save-dev @chanzuckerberg/axe-storybook-testing

# or with Yarn
yarn add --dev @chanzuckerberg/axe-storybook-testing

Usage

To use:

1. Add a script that creates a storybook build and then executes the axe-storybook command

   // In package.json
   "scripts": {
     "test:axe": "storybook build && axe-storybook"
   },

2. Run the tests by calling the script from the previous step

   npm run test:axe

3. (Optional) Install more browsers. By default Chromium is installed. If you want to also use Firefox and/or Safari, install them with:

   npx playwright install

Options

The command-line interface has the following options:

Option	Default	Values	Description
--browser	chromium	chromium, firefox, webkit	Which browser to run the tests
--build-dir	storybook-static	path	Storybook static build directory
--failing-impact	all	all, minor, moderate, serious, critical	The lowest impact level that should be considered a failure
--headless	true	boolean	Whether to run headlessly or not
--pattern	.*	regex pattern	Only run tests that match a component name pattern
--port		number	Port to run Storybook on while testing. If missing, an empty port will automatically be selected. Ignored if storybook-url is provided
--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.
--reporter-options		string	Options to pass to the mocha reporter. Especially useful with the xunit reporter - e.g. --reporter-options output=./filename.xml
--storybook-address		url	Deprecated! Use --storybook-url instead.
--storybook-url		url	Url to a running Storybook to test against. Alternative to --build-dir, which will be ignored if this is set.
--timeout	2000	number	Deprecated! Use the timeout story parameter instead.

For example, to run non-headlessly in Firefox, you would run

# If using npm
npm run storybook:axe -- --headless false --browser firefox

# or, if using Yarn
yarn storybook:axe --headless false --browser firefox

Story parameters

Stories can use parameters to configure how axe-storybook-testing handles them.

You can provide these wherever Storybook accepts parameters (story, component, or global).

disabledRules

Prevent axe-storybook-testing from running specific Axe rules on a story by using the disabledRules parameter.

// SomeComponent.stories.jsx

export const SomeStory = {
  parameters: {
    axe: {
      disabledRules: ['select-name'],
    },
  }.
};

Rules can also be disabled globally by setting this parameter for all stories in .storybook/preview.js.

// .storybook/preview.js

export const parameters = {
  axe: {
    disabledRules: ['select-name'],
  },
};

mode

Set whether errors for a story will fail the test suite or not.

Valid options are:

• off - the story will be skipped and axe will not run on it. This is the same as setting skip: true.
• warn - axe errors will be printed, but won't fail the test suite. Stories with this set will show up as pending.
• error (default) - axe errors will fail the test suite for a story.

// .storybook/preview.js

export const parameters = {
  axe: {
    mode: 'warn',
  },
};

runOptions

Allows use of any of the available axe.run options. See the link for more details. When using runOptions.rules in combination with disabledRules, disabledRules will always take precedent.

export const SomeStory = {
  parameters: {
    axe: {
      runOptions: {
        preload: true,
        selectors: true,
        ...
      }
    }
  }
}

context

Axe context, which is passed to axe.run. Useful for including or excluding elements from the tests.

export const SomeStory = {
  parameters: {
    axe: {
      context: {
        exclude: '.foo',
      },
    }
  }
}

config

Axe configuration, which is passed to axe.configure.

export const SomeStory = {
  parameters: {
    axe: {
      config: {
        checks: [...],
        ...
      }
    }
  }
}

skip

Prevent axe-storybook-testing from running a story by using the skip parameter. This is shorthand for setting mode: 'off'.

// SomeComponent.stories.jsx

export const SomeStory = {
  parameters: {
    axe: {
      skip: true,
    },
  },
};

timeout

Overrides global --timeout for this specific test

// SomeComponent.stories.jsx

export const SomeStory = {
  parameters: {
    axe: {
      timeout: 5000,
    },
  },
};

waitForSelector

Deprecated!

Legacy way of waiting for a selector before running Axe.

Now we recommend using a Storybook play function to do the same thing.

// SomeComponent.stories.jsx

// Old, deprecated way.
export const SomeStory = {
  parameters: {
    axe: {
      waitForSelector: '#some-component-selector',
    },
  },
};

// New, better way using a play function - https://storybook.js.org/docs/react/writing-stories/play-function
SomeStory.play = async () => {
  await screen.findByText('some string');
};

TypeScript

axe-storybook-testing provides TypeScript types for the story parameters listed above. Story parameters can be type checked by augmenting Storybook's Parameter type:

// overrides.d.ts

import type { AxeParams } from '@chanzuckerberg/axe-storybook-testing';

declare module '@storybook/react' {
  // Augment Storybook's definition of Parameters so it contains valid options for axe-storybook-testing
  interface Parameters {
    axe?: AxeParams;
  }
}

Annotate your stories with the StoryObj type, and your parameters will be type-checked!

// SomeComponent.stories.ts

export const SomeStory: StoryObj<Args> = {
  parameters: {
    axe: {
      timeout: 5000,
    },
  },
};

Developing

If you want to work on this project or contribute back to it, see our wiki entry on Development setup.

Security

To report security issues, see ./SECURITY.md.

Inspiration

This project was originally based on @percy/storybook.