CapybaraAccessibilityAudit

Extend your Capybara-powered System Tests to automatically audit the page for WCAG Stardards-based accessibility violations.

Usage

Failure:
Found 1 accessibility violation:

1) label: Form elements must have labels (critical)
    https://dequeuniversity.com/rules/axe/4.4/label?application=axeAPI
    The following 1 node violate this rule:

        Selector: input
        HTML: <input>
        Fix any of the following:
        - Form element does not have an implicit (wrapped) <label>
        - Form element does not have an explicit <label>
        - aria-label attribute does not exist or is empty
        - aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
        - Element has no title attribute
        - Element has no placeholder attribute
        - Element's default semantics were not overridden with role="none" or role="presentation"

Invocation: axe.run({:exclude=>[]}, {}, callback);

Installing the gem will automatically configure your System Tests to audit for accessibility violations after common actions, including:

• visit
• click_button
• click_link
• click_link_or_button
• click_on

Under the hood, capybara_accessibility_audit relies on axe-core-rspec, which uses aXe to audit for accessibility violations. To configure which options are passed to the be_axe_clean matcher, override the class-level accessibility_audit_options. Supported keys include:

• according_to:
• checking_only:
• checking:
• excluding:
• skipping:
• within:

To override the class-level setting, wrap code in calls to the with_accessibility_audit_options method:

with_accessibility_audit_options according_to: :wcag21aaa do
  visit page_with_violations_path
end

Frequently Asked Questions

My application already exists, automated accessibility audits are uncovering violations left and right. Do I have to fix them all at once?

Your suite has control over which rules are skipped and which rules are enforced through the accessibility_audit_options configuration.

Configuration overrides can occur at any scope, ranging from class-wide to block-wide.

For example, to skip a rule at the suite-level, override it in your ApplicationSystemTestCase:

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  accessibility_audit_options.skipping = %w[label button-name image-alt]
end

To skip a rule at the test-level, wrap the test in a with_accessibility_audit_options block:

class MySystemTest < ApplicationSystemTestCase
  test "with overridden accessibility audit options" do
    with_accessibility_audit_options skipping: %w[label button-name image-alt] do
      visit examples_path
      # ...
    end
  end
end

To skip a rule at the block-level, wrap the code in a with_accessibility_audit_options block:

class MySystemTest < ApplicationSystemTestCase
  test "with overridden accessibility audit options" do
    visit examples_path

    with_accessibility_audit_options skipping: %w[label button-name image-alt] do
      click_on "A link to a page with a violation"
    end

    # ...
  end
end

As you resolve the violations, you can remove entries from the list of skipped rules.

I've implemented a custom Capybara action to toggle a disclosure element. How can I automatically audit for violations after it's called?

You can add the method to the list of methods that will initiate an automated audit:

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  def toggle_disclosure(locator)
    # ...
  end

  accessibility_audit_after :toggle_disclosure
end

How can I turn off auditing for the entire suite?

You can disable automated auditing within your ApplicationSystemTestCase:

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  self.accessibility_audit_enabled = false
end

How can I turn off auditing for a block of code?

You can disable automated auditing temporarily by wrapping code in a skip_accessibility_audits block:

class MySystemTest < ApplicationSystemTestCase
  test "with overridden accessibility audit options" do
    skip_accessibility_audits do
      visit a_page_with_violations_path

      click_on "A link to a page with a violation"
    end

    # ...
  end
end

How can I turn off auditing hooks for a method?

You can remove the method from the test's Set of accessibility_audit_after_methods configuration by calling skip_accessibility_audit_after:

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  skip_accessibility_audit_after :visit
end

How can I turn off auditing for a test file?

You can disable automated auditing at the class-level:

class MySystemTest < ApplicationSystemTestCase
  self.accessibility_audit_enabled = false
end

As you gradually address violations, you can re-enable audits within with_accessibility_audits blocks:

class MySystemTest < ApplicationSystemTestCase
  self.accessibility_audit_enabled = false

  test "a test with a violation" do
    visit examples_path

    with_accessibility_audits do
      click_on "A link to a page with violations"
    end
  end
end

Installation

Add this line to your application's Gemfile:

gem "capybara_accessibility_audit"

And then execute:

$ bundle

Contributing

Please read CONTRIBUTING.md.

License

The gem is available as open source under the terms of the MIT License.