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:
Happy testing!
Top comments (3)
omg great article this is rad
Hi Chris, thanks for this post. does this use axe-matcher or axe-core ? as far as i know, axe-matcher is deprectaed
Thanks for pointing that out, Bhaskar. The axe-matcher library became depreciated after the article was originally published.
I've updated the article with reference to the new 'axe-core-rspec' library. Code examples have also been updated with the latest syntax.
I've also included a spec_helper configuration that I have found works better in CI environments than the one that was originally included in the article.