Introducing automated accessibility testing in Rails apps with RSpec and aXe.

chrislewis60 profile image Chris Lewis ・4 min read

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-matchers.

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 uses the Apparition driver which allows us to run Capybara integration tests in the Chrome browser in a headless state.

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-matchers'
  gem 'capybara'
  gem 'apparition'

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 'rspec/rails'
require 'capybara/rspec'
require 'capybara/apparition'
require 'axe/rspec'

Capybara.javascript_driver = :apparition

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_accessible

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)
     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)
     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)
     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_accessible.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_accessible.within '#selector1'

Or exclude certain parts:

# spec/integration/user_views_accessible_welcome_page_spec.rb
expect(page).to be_accessible.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 integration page.


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:

Happy testing!

Posted on by:

chrislewis60 profile

Chris Lewis


Full Stack Developer with a focus on security. For me, nothing beats a good penetration testing report and a strong cup of Yorkshire Tea.


markdown guide