Socket
Socket
Sign inDemoInstall

@chanzuckerberg/axe-storybook-testing

Package Overview
Dependencies
13
Maintainers
9
Versions
40
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@chanzuckerberg/axe-storybook-testing

[![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) [!


Version published
Maintainers
9
Created

Changelog

Source

8.0.2

  • [fix] Ensure Storybook is ready before extract-ing stories #94

Readme

Source

@chanzuckerberg/axe-storybook-testing

Package Status Tests Release

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

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:

OptionDefaultValuesDescription
--browserchromiumchromium, firefox, webkitWhich browser to run the tests
--build-dirstorybook-staticpathStorybook static build directory
--failing-impactallall, minor, moderate, serious, criticalThe lowest impact level that should be considered a failure
--headlesstruebooleanWhether to run headlessly or not
--pattern.*regex patternOnly run tests that match a component name pattern
--reporterspecspec, dot, nyan, tap, landing, list, progress, json, json-stream, min, doc, markdown, xunitHow to display the test run. Can be any built-in Mocha reporter.
--reporter-optionsstringOptions to pass to the mocha reporter. Especially useful with the xunit reporter - e.g. --reporter-options output=./filename.xml
--storybook-addressurlDeprecated! Use --storybook-url instead.
--storybook-urlurlUrl to a running Storybook to test against. Alternative to --build-dir, which will be ignored if this is set.
--timeout2000numberDeprecated! 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,
        ...
      }
    }
  }
}

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.

FAQs

Last updated on 13 May 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc