axe-core-rspec

The axe-core-rspec gem provides a custom matchers BeAxeClean , which can be instantiated using the be_axe_clean helper method.

See a list of RSpec built-in matchers

Usage

• In your Gemfile, add the axe-core-rspec gem.

“mfile source “https://rubygems.org”

gem ‘axe-core-rspec’

“

• Simply requrire axe-rspec which extends RSpec with the custom matcher BeAxeClean .

“b require ‘axe-rspec’

“

• Use with webdriver of choice.

Matcher

BeAxeClean

To construct an axe accessibility RSpec check, begin with expect(page).to be_axe_clean , and append any clauses necessary, where page object is provided by the webdriver of choice.

Clauses

Clauses are chainable methods for the be_axe_clean custom matcher.Configurable clauses allows for greater granularity with testing and expectaions.

within - Inclusion clause

The inclusion clause within '#selector' specifies which elements of the page should be checked. A valid CSS selector must be provided. Within accepts a single selector, an array of selectors, or a hash describing iframes with selectors.

see additional context parameter documentation

Examples:

“b

Simple selector

expect(page).to be_axe_clean.within ‘#selector1’

Compound selector

Include all elements with the class ‘selector2’ inside the element with id ‘selector1’

expect(page).to be_axe_clean.within ‘#selector1 .selector2’

Multiple selectors

Include the element with id ‘selector1’ and all elements with class ‘selector2’

expect(page).to be_axe_clean.within ‘#selector1’, ‘.selector2’

IFrame selector

Include the element with id ‘selector1’ inside the IFrame with id ‘frame1’

expect(page).to be_axe_clean.within iframe: ‘#frame1’, selector: ‘#selector1’

Multiple IFrame selectors

Include the element with id ‘selector1’ inside the IFrame with id ‘frame1’

Include the element with id ‘selector2’ inside the IFrame with id ‘frame2’

expect(page).to be_axe_clean.within( ‘#frame1’, selector: ‘#selector1’, ‘#frame2’, selector: ‘#selector2’ )

Simple selectors and IFrame selector

Include the element with id ‘selector1’ and all elements with class ‘selector2’

Include the element with id ‘selector3’ inside the IFrame with id ‘frame’

expect(page).to be_axe_clean.within ‘#selector1’, ‘.selector2’, iframe: ‘#frame’, selector: ‘#selector3’

Nested IFrame selectors

Include the element selector1 inside the IFrame with id ‘frame2’,

inside the IFrame with id ‘frame1’

expect(page).to be_axe_clean.within(iframe: ‘#frame1’, selector: ‘#frame2’, selector: ‘#selector1’ )

“

excluding - Exclusion clause

The exclusion clause excluding '#selector' specifies which elements of the document should be ignored. A valid CSS selector must be provided. Excluding accepts a single selector, an array of selectors, or a hash describing iframes with selectors.

see additional context parameter documentation

Examples:

“

Simple selector

expect(page).to be_axe_clean.excluding ‘#selector1’

Compound selector

Exclude all elements with the class ‘selector2’ inside the element with id ‘selector1’

expect(page).to be_axe_clean.excluding ‘#selector1 .selector2’

Multiple selectors

Exclude the element with id ‘selector1’ and all elements with class ‘selector2’

expect(page).to be_axe_clean.excluding ‘#selector1’, ‘.selector2’

IFrame selector

Exclude the element with id ‘selector1’ inside the IFrame with id ‘frame1’

expect(page).to be_axe_clean.excluding iframe: ‘#frame1’, selector: ‘#selector1’

Multiple IFrame selectors

Exclude the element with id ‘selector1’ inside the IFrame with id ‘frame1’

Exclude the element with id ‘selector2’ inside the IFrame with id ‘frame2’

expect(page).to be_axe_clean.excluding( ‘#frame1’, selector: ‘#selector1’, ‘#frame2’, selector: ‘#selector2’ )

Simple selectors with IFrame selector

Exclude the element with id ‘selector1’ and all elements with class ‘selector2’

Exclude the element with id ‘selector3’ inside the IFrame with id ‘frame’

expect(page).to be_axe_clean.excluding ‘#selector1’, ‘.selector2’, iframe: ‘#frame’, selector: ‘#selector3’

Nested IFrame selectors

Exclude the element selector1 inside the IFrame with id ‘frame2’,

inside the IFrame with id ‘frame1’

expect(page).to be_axe_clean.excluding(iframe: ‘#frame1’, selector: ‘#frame2’, selector: ‘#selector1’ )

“

according_to - Accessibility Standard (Tag) clause

The tag clause specifies which accessibility standard (or standards) should be used to check the page. The accessibility standards are specified by name (tag). According to accepts a single tag, or an array of tags.

The acceptable tag names are documented as well as a complete listing of rules that correspond to each tag.

“

Single standard

expect(page).to be_axe_clean.according_to :wcag2a

Multiple standards

expect(page).to be_axe_clean.according_to :wcag2a, :section508

“

checking - Checking Rules clause

The checking-rules clause specifies which additional rules to check (in addition to the specified tags, if any, or the default ruleset). Checking accepts a single rule, or an array of rules.

see rules documentation for a list of valid rule IDs

“

Checking a single rule

expect(page).to be_axe_clean.checking :label

Checking multiple rules

expect(page).to be_axe_clean.checking :label, :tabindex

Example specifying an additional best practice rule in addition to all rules in the WCAG2A standard

expect(page).to be_axe_clean.according_to(:wcag2a).checking(:tabindex)

“

checking_only - Exclusive Rules clause

The checking only rules clause specifies which rules to exclusively check. Using this matcher excludes all rules outside of the list.

“

Checking a single rule

expect(page).to be_axe_clean.checking_only :label

Checking multiple rules

expect(page).to be_axe_clean.checking_only :label, :tabindex

“

skipping - Skipping Rules clause

The skipping-rules clause specifies which rules to skip. This allows an accessibility standard to be provided (via the tag clause) while ignoring a particular rule. The rules are specified by comma-separated rule IDs.

see rules documentation for a list of valid rule IDs

“

Skipping a single rule

expect(page).to be_axe_clean.skipping :label

Skipping multiple rules

expect(page).to be_axe_clean.skipping :label, :tabindex

Example specifying an additional best practice rule in addition to all rules in the WCAG2A standard

expect(page).to be_axe_clean.according_to(:wcag2a).skipping(:label)

“

Interoperability between clauses

All of the described clauses may be mixed and matched with method chaining. Below are some examples.

“ expect(page).to be_axe_clean.within(‘.main’, ‘.header’).excluding(‘.footer’)

expect(page).to be_axe_clean.excluding(‘#sidebar’).according_to(:wcag2a, :wcag2aa).skipping(‘color-contrast’)

expect(page).to be_axe_clean.within(‘.main’).checking_only ‘document-title’, :label

expect(page).to be_axe_clean.according_to(:best-practice).checking(:aria-roles, ‘definition-list’)

“