Migrating to axe DevTools for Web v4.x for Node.js

Link to Migrating to axe DevTools for Web v4.x for Node.js copied to clipboard

Steps for migrating to version 4.x of axe DevTools for Web for Node.js

Axe DevTools NPM v4.x is a major rewrite of the entire project. The most notable changes are summarized below, followed by more specific changes to relevant packages.

Summary

The axe-devtools-* suite of npm packages, involved a rebranding perspective as well as to unify integration tools to be more specific to developer experience.

With this in mind, all packages have been rebranded to utilize the axe devtools namespace and the binaries have been combined to a single binary package.

Beware of breaking changes

Given the rebranding of the API, it is fair to outline that migration to v4.0 involves following this migration guide in a step by step fashion

Environment Setup

There is no changes with the default requirements. The desired requirements are as below:

  • Node LTS Version
  • NPM for npm dependencies

Installing axe DevTools NPM Packages

Ensure you have access to Deque's registry. If not, refer to the install information for your package:

You may install any of the below npm packages by including them in the package.json file.

npm install @axe-devtools/browser
// package.json
{
  "@axe-devtools/browser": "^4.0.0"
}

The npm packages available are:

Please refer to each of the above npm packages, for usage instructions and detailed API documentation.

Optionally, one may uninstall the previous node integrations (for scoped or unscoped packages) by running the below commands:

npm uninstall attest-js
npm uninstall @deque/attest-js

Noteworthy Changes

Asides installation and usage changes with the outlined gems, some noteworthy changes include:

  • The Environment variable for configuring custom rules has been changed from ATTEST_PATH to AXE_RULESET_PATH.
  • The default ruleset has changed. Axe DevTools audits a given page with wcag2 as the default ruleset. No change is required by the end-user. If one wished to configure a different ruleset, they may use @axe-devtools/cli to generate a different ruleset or create an axe-ruleset.json file with their desired rulesets.
  • All packages will utilize axe-core v4.0.X.
  • Axe DevTools Webdriverio will no longer support webdriverio v4 and will now only support webdriverio v5 and v6.

Changes to binaries

Attest-standards and Attest Reporter will no longer be shipped with binaries. All of the previous functionality of the binaries will be included in @axe-devtools/cli as subcommands. For axe DevTools 4.0, Attest-standards will be deprecated and will not have a 4.0 release.