Extend your Capybara-powered System Tests to automatically audit the page for WCAG Standards-based accessibility violations.
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:
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:
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
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
You can disable automated auditing within your ApplicationSystemTestCase
:
class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
self.accessibility_audit_enabled = false
end
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
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
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
Add this line to your application's Gemfile:
gem "capybara_accessibility_audit"
And then execute:
$ bundle
Please read CONTRIBUTING.md.
The gem is available as open source under the terms of the MIT License.
This repo is maintained and funded by thoughtbot, inc. The names and logos for thoughtbot are trademarks of thoughtbot, inc.
We love open source software! See our other projects. We are available for hire.