FAQ & Troubleshooting

FAQ & Troubleshooting

Here we document some commonly seen issues, with details on the cause(s) and ways to resolve. For any new issues, feel free to file an issue and we can discuss and include as needed.

"Axe is already running" errors on most / all accessibility tests

Symptoms

• You may encounter many / all tests suddenly failing in CI or when running a configured script which runs axe-storybook
• The error may also suggest running tests by using await axe.run()
• This may have occurred after a recent upgrade to other project packages (e.g., storybook addons, or other plugins that alter stories)

Problems and Solutions

Problem: a storybook addon has imported axe-core which conflicts with the version provided by axe-storybook-testing

• Importing multiple copies of axe-core can put window.axe in an unstable state
• axe-storybook-testing uses axe-core to run, so having any other addon import the package will break the test run
• As of v8.5.0, @storybook/addon-a11y uses axe-core in a way that conflicts with axe-storybook-testing

Solution: disable offending addon(s) when running axe-storybook-testing

Related Issue(s): #103

With storybook, it is possible to build stories using different configuration during test. Configure axe-storybook to run after building the stories without the conflicting addon(s).

• Use storybook build --test in your npm script

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

• In your storybook config file (likely either main.js or main.js), add in test config to disable the conflicting package.

// in your main.(js|ts) file config
build: {
  test: {
    disabledAddons: ['@storybook/addon-a11y'], 
  },
},