Accessibility Specs

Last Updated: June 2024

The GitHub rspec.yml workflow runs on all pull requests. It runs a series of checks to ensure that the pull request meets the accessibility standards required by Berkeley.

As of June 2024, all Berkeley websites must meet the WCAG 2.0 AA standards. WCAG 2.2 AA is the most recent version of the standard, so the tests include optional checks for both standards.

All tests are built around the axe-core library, which is also available as a browser extension. The tests are run in a headless Google Chrome session, using the Selenium WebDriver.

Running the Tests

Ensure you have installed all dependencies and can build the website, e.g. by running bundle install and bundle exec jekyll serve.

  • Bundle install grabs the necessary Ruby gems for accessibility tests.
  • Install Google Chrome and the ChromeDriver for Selenium tests.
    • brew install chromedriver on macOS.
    • apt-get install chromedriver on Ubuntu.
    • The chromedriver version must match the Chrome version. You can check your Chrome version by navigating to chrome://version/ in the browser.
  • Run the tests with bundle exec rspec.

After passing all tests, add the following to your README: (Just make sure to replace ORG/REPO with your GitHub repo path.)

[![Run rspec tests](https://github.com/ORG/REPO/actions/workflows/rspec.yml/badge.svg)](https://github.com/ORG/REPO/actions/workflows/rspec.yml)

Test Details

They are run on each page listed in sitemap.xml. (This file is built automatically by the jekyll-sitemap plugin.)

  • Only pages that end with .html or / (e.g. index pages) are tested.
  • The tests are run using the axe-core library, inside a headless Google Chrome session.
  • The default configuration runs all tests for WCAG 2.0 AA, on all pages.

Test Results and Fixing Issues

The test results show the list of failures for each page. If you see a lot of failures, you should consider the following:

bundle exec rspec --next-failure

This presents only 1 failed page at a time, but still shows all failures for that page.

Configuring Test Cases

After you get tests passing, you may want to get more advanced with some configurations.

Different Site Build / Configurations

By default, the tests build/run the site using the _config.yml file. If you have different configurations for different environments, you can specify the configuration file to use.

RSPEC_CONFIG_FILE=_config_dev.yml bundle exec rspec

WCAG 2.2 AA Tests

By default, WCAG 2.2 AA tests are not run. To enable them, remove the :skip tag from the spec/accessibility_spec.rb file.

    it 'according to WCAG 2.2 AA', :skip do
    # becomes
    it 'according to WCAG 2.2 AA' do

Exceptions to the Tests

Sometimes, you might need to embed a video or use a color that doesn’t meet the standards. In these cases, you can add an exception to the test.

<div data-a11y-external-errors="true">
   Content inside this div is ignored by the accessibility tests.
</div>

The tests have a setup to ingore content that matches a list of selectors. data-a11y-external-errors="true" suggests that the content inside the div is not part of the page’s content. If you have other reasons to exclude a section, you can add a custom selector to the spec/accessibility_spec.rb file.

:warning: Note: This is a last resort. Selectors should match the smallest possible section of the page. If you find yourself adding a lot of exceptions, you should consider refactoring the page to meet the standards, or whether there are other ways to meet the standards.

Additional Resources

Use the #a11y channel in the EECS Crossroads Slack for questions or help with accessibility.

This section is a work in progress.