Migrating to axe DevTools for Web v4.x for Ruby

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

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

Axe DevTools for Web Gems 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 gems were re-architected to slim down the provided integration tools and offer a better developer experience.

Compared to previous versions where only a single gem was provided, this version provides a collection of gems allowing end users to choose what is essential and fits best with their current workflow.

Migration Steps

Given the split from a monolithic gem structure to individual gems, some migration steps are required. You can use the following migration guide.

Developer Setup

There are no changes from the previous developer setup. The necessary requirements are as follows:

Ruby (the latest version)
Bundler for gem dependencies
Rake as a task runner
RSpec or Cucumber for testing
Node and Npm for installing the axe-core package

Installing axe DevTools for Web Gems

Ensure you have access to Deque's registry. If not, refer to the setup guide.

After you have access to Deque's registry, you may install any of the following gems by including them in either the Gemfile or gemspec files.

gem "axe-devtools-cucumber"

Alternatively, you can specify a source to the gem:

gem "attest-devtools-cucumber", :source => 'https://agora.dequecloud.com/artifactory/api/gems/devtools-gems'

The available gems are:

Please refer to the documentation for usage instructions and detailed information about the APIs.

Uninstalling the Ruby Integrations

You may uninstall the previous Ruby integrations by running the commands below:

gem uninstall axe-matchers
gem uninstall attest-ruby

Noteworthy Changes

Other noteworthy changes to the Ruby integration include:

The environment variable for configuring custom rules has been changed from ATTEST_PATH to AXE_RULESET_PATH. Refer to advanced usage.
The default ruleset has changed. Axe DevTools for Web audits a given page with wcag2 as the default ruleset. No change is required by the end-user. If you want to configure a different ruleset, you may use the respective clauses offered in the Cucumber documentation or the RSpec documentation.
The be_accessible Matchers in RSpec has been renamed to be_axe_clean.
The be accessible Step definition in RSpec has been renamed to be axe clean.