Stormbreaker

Stormbreaker automatically adds axe assertions to your ruby selenium tests on top of rspec assertions while providing some additional functionality to sort, group, and display accessibility violations. While it would be fairly easy to add the axe-rspec matchers to an existing suite, stormbreaker adds simple on/off functionality so that you don't have to bloat your testing suite with a huge number of axe assertions. Various configuration options exist to allow certain accessibility rules or severity types (critical / serious / moderate / minor) to be enabled/disabled.

Rules can be found at https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md

Stormbreaker provides extra value for mature testing suites where selenium tests exercise a majority of an application's views.

What does adding assertions on top of RSpec assertions mean?

expect(page.find_element('#important_title').text).to eq('Important Title')

Without Stormbreaker:

In the above example, selenium would retrieve the text of an element on a page and then check its contents with RSpec.

With Stormbreaker:

In the above example, selenium will still retrieve the text of an element on a page and then check its contents with RSpec, but it will first check to see if page is accessible according to the configured rules.

An accessibility violation will not immediately cause a test to fail. Instead, a test will run either until completion, or until a failed non-axe assertion. Any axe violations will be collected along the way, ensuring that each test provides as much accessibility coverage as possible. Accessibility violations will be reported on a detailed per-test basis and will be summarized for each suite.

In addition to violations being reported in the standard RSpec output, an html file utilizing client-side javascript will also be produced to help sort violations by severity and violation type.

Configuring Stormbreaker

In your spec_helper.rb add:

  require 'stormbreaker'
  Stormbreaker.install!
  Stormbreaker.configure do |config|
    # Driver configuration -- can be a lambda or an object. May need to be a lambda if your driver isnt
    #  available in your spec_helper.rb. This wont be referenced until an assertion is first run
    config.driver = lambda { Driver.new }

    # Axe config
    config.rules = %i[wcag2a wcag2aa section508]
    config.skip = %i[color-contrast duplicate-id]
    config.enabled_severity_categories = %i[critical serious moderate minor]

    # Standard results output
    config.results_path = 'results.html'

    # Serialization configuration
    config.serialize_output = true
    config.serialized_input_path = '.'
    config.serialize_prefix = 'stormbreaker_results'
  end

After adding stormbreaker to your Gemfile and installing it, then run bundle exec rspec

Running tests in parallel

Stormbreaker's code is largely prepended onto RSpec's code, so it should not affect any parallelization. However, if you'd like to generate an html that includes all of the different runs, stormbreaker provides an option to dump each run's serialized results and then combine them into a single html file using a rake task.

bundle exec rake stormbreaker:combine_results['<path/to/#{serialize_prefix}*>']