axe-core

What is axe-core?

The axe-core npm package is a library for accessibility testing. It allows developers to automatically test their HTML for common accessibility issues using a variety of technologies including JavaScript, React, Angular, Vue, and more. The package can be used in different environments like web browsers, Node.js, and continuous integration systems.

What are axe-core's main functionalities?

Accessibility testing in browser

This code sample demonstrates how to run accessibility tests on the current document in a web browser. The results are logged to the console.

axe.run(document, function(err, results) {
  if (err) throw err;
  console.log(results);
});

Integration with testing frameworks

This code sample shows how axe-core can be integrated with Jest testing framework using jest-axe to ensure that a rendered HTML snippet is accessible.

const { axe, toHaveNoViolations } = require('jest-axe');

test('ensures .foo element is accessible', async () => {
  const render = () => '<div class="foo">bar</div>';
  const html = render();
  expect(await axe(html)).toHaveNoViolations();
});

Command-line accessibility testing

This code sample illustrates how to use axe-core with axe-cli for command-line accessibility testing of a given URL.

const axe = require('axe-core');
const { run } = require('axe-cli');

run(axe, { url: 'http://example.com' }, (err, results) => {
  if (err) throw err;
  console.log(results);
});

Other packages similar to axe-core

pa11y

Pa11y is an automated accessibility testing tool that runs HTML CodeSniffer from the command line for programmatic accessibility reporting. It is similar to axe-core in that it provides automated testing, but it uses a different engine for its analysis and offers a command-line interface out of the box.

lighthouse

Lighthouse is an open-source, automated tool for improving the quality of web pages. It has audits for performance, accessibility, progressive web apps, SEO, and more. The accessibility audits are similar to axe-core, but Lighthouse provides a broader range of audits beyond accessibility.

wave

WAVE is a suite of evaluation tools that helps authors make their web content more accessible to individuals with disabilities. WAVE can provide visual feedback about the accessibility of your web content by injecting icons and indicators into your page. Unlike axe-core, WAVE is primarily a browser extension and web service.

README

axe-core

Axe is an accessibility testing engine for websites and other HTML-based user interfaces. It's fast, secure, lightweight, and was built to seamlessly integrate with any existing test environment so you can automate accessibility testing alongside your regular functional testing.

Sign up for axe news to get the latest on axe features, future releases, and events.

The Accessibility Rules

Axe-core has different types of rules, for WCAG 2.0 and 2.1 on level A and AA, as well as a number of best practices that help you identify common accessibility practices like ensuring every page has an h1 heading, and to help you avoid "gotchas" in ARIA like where an ARIA attribute you used will get ignored.

With axe-core, you can find on average 57% of WCAG issues automatically. Additionally, axe-core will return elements as "incomplete" where axe-core could not be certain, and manual review is needed.

To catch bugs earlier in the development cycle we recommend using the axe-linter vscode extension. To improve test coverage even further we recommend the intelligent guided tests in the axe Extension.

The complete list of rules, grouped WCAG level and best practice, can found in doc/rule-descriptions.md.

Getting started

First download the package:

npm install axe-core --save-dev

Now include the javascript file in each of your iframes in your fixtures or test systems:

<script src="node_modules/axe-core/axe.min.js"></script>

Now insert calls at each point in your tests where a new piece of UI becomes visible or exposed:

axe
  .run()
  .then(results => {
    if (results.violations.length) {
      throw new Error('Accessibility issues found');
    }
  })
  .catch(err => {
    console.error('Something bad happened:', err.message);
  });

Philosophy

The web can only become an accessible, inclusive space if developers are empowered to take responsibility for accessibility testing and accessible coding practices.

Automated accessibility testing is a huge timesaver, it doesn't require special expertise, and it allows teams to focus expert resources on the accessibility issues that really need them. Unfortunately, most accessibility tools are meant to be run on sites and applications that have reached the end of the development process and often don't give clear or consistent results, causing frustration and delays just when you thought your product was ready to ship.

Axe was built to reflect how web development actually works. It works with all modern browsers, tools, and testing environments a dev team might use. With axe, accessibility testing can be performed as part of your unit testing, integration testing, browser testing, and any other functional testing your team already performs on a day-to-day basis. Building accessibility testing into the early development process saves time, resources, and all kinds of frustration.

About axe - our Manifesto

• Axe is open source.
• It returns zero false positives (bugs notwithstanding).
• It's designed to work on all modern browsers and with whatever tools, frameworks, libraries and environments you use today.
• It's actively supported by Deque Systems, a major accessibility vendor.
• It integrates with your existing functional/acceptance automated tests.
• It automatically determines which rules to run based on the evaluation context.
• Axe supports in-memory fixtures, static fixtures, integration tests and iframes of infinite depth.
• Axe is highly configurable.

Supported Browsers

The axe-core API fully supports the following browsers:

• Microsoft Edge v40 and above
• Google Chrome v42 and above
• Mozilla Firefox v38 and above
• Apple Safari v7 and above
• Internet Explorer v11

Support means that we will fix bugs and attempt to test each browser regularly. Only Firefox, Chrome, and Internet Explorer 11 are currently tested on every pull request.

There is limited support for JSDOM. We will attempt to make all rules compatible with JSDOM but where this is not possible, we recommend turning those rules off. Currently the color-contrast rule is known not to work with JSDOM.

We can only support environments where features are either natively supported or polyfilled correctly. We do not support the deprecated v0 Shadow DOM implementation.

Contents of the API Package

The axe-core API package consists of:

• axe.js - the JavaScript file that should be included in your web site under test (API)
• axe.min.js - a minified version of the above file

Localization

Axe can be built using your local language. To do so, a localization file must be added to the ./locales directory. This file must have be named in the following manner: <langcode>.json. To build axe using this locale, instead of the default, run axe with the --lang flag, like so:

grunt build --lang=nl

or equivalently:

npm run build -- --lang=nl

This will create a new build for axe, called axe.<lang>.js and axe.<lang>.min.js. If you want to build localized versions, simply pass in --all-lang instead.

To create a new translation for axe, start by running grunt translate --lang=<langcode>. This will create a json file fin the ./locales directory, with the default English text in it for you to translate. We welcome any localization for axe-core. For details on how to contribute, see the Contributing section below. For details on the message syntax, see Check Message Template.

To update existing translation file, re-run grunt translate --lang=<langcode>. This will add new messages used in English and remove messages which were not used in English.

Additionally, locale can be applied at runtime by passing a locale object to axe.configure(). The locale object must be of the same shape as existing locales in the ./locales directory. For example:

axe.configure({
  locale: {
    lang: 'de',
    rules: {
      accesskeys: {
        help: 'Der Wert des accesskey-Attributes muss einzigartig sein.'
      }
      // ...
    },
    checks: {
      abstractrole: {
        fail: 'Abstrakte ARIA-Rollen dürfen nicht direkt verwendet werden.'
      },
      'aria-errormessage': {
        // Note: doT (https://github.com/olado/dot) templates are supported here.
        fail:
          'Der Wert der aria-errormessage ${data.values}` muss eine Technik verwenden, um die Message anzukündigen (z. B., aria-live, aria-describedby, role=alert, etc.).'
      }
      // ...
    }
  }
});

Supported ARIA Roles and Attributes.

Refer axe-core ARIA support for a complete list of ARIA supported roles and attributes by axe.

Contributing

Read the Proposing Axe-core Rules guide

Read the documentation on the architecture

Read the documentation on contributing

Projects using axe-core

List of projects using axe-core

Acknowledgements

Thanks to Dulin Marat for his css-selector-parser implementation which is included for shadow DOM support.

Thanks to the Slick Parser implementers for their contribution, we have used some of their algorithms in our shadow DOM support code.

Changelog

4.2.3 (2021-06-22)

Bug Fixes

• accText: ignore text in embedded content elements (#3022) (8fb4635), closes #3017
• color-contrast: add special case for new sr-only technique (#2985) (79cbf01)
• color-contrast: check for pseudo elements on element itself, not just parents (#2980) (3122550)
• frame-tested: run without respondable (#2942) (a1d725d)
• publish-metadata: use fail message for rules with reviewOnFail:true (#2987) (00fefa9)
• sri-history: add backported releases (#3004) (0332e80)