Automated accessibility testing in Rails with RSpec and aXe.

We all love to make great looking websites, but we also have a responsibility to make our websites as accessible as possible for people with disabilities.

However, checking that a website meets certain accessibility standards can often be a very time-consuming process, involving 3rd party tools and online validators.

Wouldn't it be great if we could automatically test accessibility as part of our normal testing and Continuous Integration (CI) processes? Some key benefits could be that:

developers can immediately see when accessibility issues are introduced if checks are done every time code is pushed to the repository
all developers would be exposed to accessibility checks, helping to develop a team-wide appreciation for the guidelines
it helps to ensure that there are no accessibility regressions once a site has gone live

axe - The Standard in Accessibility Testing

Thankfully, the awesome folk at Deque have developed a set of accessibility rules known as 'axe-core' that can be used to automatically test a wide range of web applications, including Rails apps.

The main repository for Rails and RSpec integration can be found at: deque/axe-core-rspec.

Browser testing environment

The accessibility tests need to be run in an instance of a web browser. For example, this could be an instance of Chrome, Firefox, or Chrome in a headless state (without a graphical display). But there are other browsers that can be used.

This example is going to use a customised headless Chrome browser.

Example Rails and RSpec setup

Start by creating a new Rails app, or open a pre-existing Rails project, and make sure the following gems are in Gemfile:

# Gemfile
group :development, :test do
  gem 'rspec-rails', '~> 4.0.0'
  gem 'axe-core-rspec'
  gem 'capybara'
  gem 'selenium-webdriver'
  gem 'webdrivers'
end

Run bundle to install the gems.

If you haven't got RSpec set up, then run:

rails generate rspec:install

Include the relevant libraries at the top of spec_helper.rb:

# spec/spec_helper.rb
require File.expand_path("../../config/environment", __FILE__)
require 'rspec/rails'
require 'capybara/rspec'
require 'axe-rspec'
require 'webdrivers/chromedriver'

# This configuration seems to work well in CI environments:
Capybara.register_driver :chrome_headless do |app|
  options = ::Selenium::WebDriver::Chrome::Options.new
  options.add_argument('--headless')
  options.add_argument('--no-sandbox')
  options.add_argument('--disable-dev-shm-usage')
  options.add_argument('--window-size=1400,1400')

  Capybara::Selenium::Driver.new(app, browser: :chrome, options: options)
end

# Change default_driver to :selenium_chrome if you want to actually see the tests running in a browser locally. Should be :chrome_headless in CI though.
Capybara.default_driver = :chrome_headless
Capybara.javascript_driver = :chrome_headless

Create a new welcome/index route (or find a controller and view you'd like to test):

rails generate controller welcome index

Adding an integration test to your RSpec tests

Create a new integration test to check that the welcome page is accessible:

# spec/integration/user_views_accessible_welcome_page_spec.rb
require 'spec_helper'

feature 'welcome', js: true do
  scenario 'index is accessible' do
    visit welcome_index_path
    expect(page).to be_axe_clean
  end
end

And run the test with:

bundle exec rspec spec/integration/user_views_accessible_welcome_page_spec.rb

The default layout and view created by the Rails generator should have some accessibility failures. This is actually quite useful because you can immediately see that the tests are working. Some examples you might see include:

Found 3 accessibility violations:

 1) html-has-lang: <html> element must have a lang attribute (serious)
     https://dequeuniversity.com/rules/axe/3.5/html-has-lang?application=axeAPI
     The following 1 node violate this rule:

         Selector: html
         HTML: <html>
         Fix any of the following:
         - The <html> element does not have a lang attribute

 2) landmark-one-main: Document must have one main landmark (moderate)
     https://dequeuniversity.com/rules/axe/3.5/landmark-one-main?application=axeAPI
     The following 1 node violate this rule:

         Selector: html
         HTML: <html>
         Fix all of the following:
         - Document does not have a main landmark

 3) region: All page content must be contained by landmarks (moderate)
     https://dequeuniversity.com/rules/axe/3.5/region?application=axeAPI
     The following 2 nodes violate this rule:

         Selector: h1
         HTML: <h1>Axe matchers example Rails app (RSpec)</h1>
         Fix any of the following:
                 - - Some page content is not contained by landmarks

         Selector: p
         HTML: <p>
         Fix any of the following:
                 - - Some page content is not contained by landmarks

What accessibility standards can be tested?

You can target the following standards:

Tag Name	Accessibility Standard
wcag2a	WCAG 2.0 Level A
wcag2aa	WCAG 2.0 Level AA
section508	Section 508
best-practice	Best practices endorsed by Deque

For example, to only test for Level WCAG 2.0 Level A accessibility:

# spec/integration/user_views_accessible_welcome_page_spec.rb
expect(page).to be_axe_clean.according_to :wcag2a

Does the whole page have to be tested?

You can target certain parts of a page rather than testing the whole thing:

# spec/integration/user_views_accessible_welcome_page_spec.rb
expect(page).to be_axe_clean.within '#selector1'

Or exclude certain parts:

# spec/integration/user_views_accessible_welcome_page_spec.rb
expect(page).to be_axe_clean.excluding '#selector1'

There are many more options to help you customise the scope of your tests. The full range can be found on the deque/axe-matchers-rspec page.

Summary

Automated accessibility testing can go a long way to improving a development team's knowledge and understanding of the accessibility guidelines. It also makes sure that accessibility is not forgotten about during any stage of the development process. By including these automated tests in the CI process, it's possible to get continuous feedback on accessibility compliance and it keeps everyone's focus on maintaining good accessibility standards.

However, it would be prudent to also cross-reference these automated tests by testing sites using tools like Total Validator from time to time.

Plus, there's no substitute for actually opening up a site and making sure that it is usable, using screen readers like:

Jaws
NVDA

Happy testing!

Blog