Accessibility testing helper functions

Accessibility

Function

cy.axeCheck(context, tempOptions)

Source file

axeCheck.js

Description

Checks the current page or element and children for aXe violations.

Arguments

context -- a String, defaults to main
tempOptions -- an Object, defaults to an empty Object

To add aXe checks to your tests use the custom cy.axeCheck() command based off the cy.checkA11y() command.

As documented by the plugin, be sure to call cy.injectAxe() after each cy.visit(), after which cy.axeCheck() can be invoked any number of times.

CODE

cy.visit(PAGE_URL);
cy.injectAxeThenAxeCheck();

Depending on the content of a page, it may be more thorough to test accessibility after expanding all accordions (and expandable content in general) on the page. Use the cy.expandAccordions() command for that purpose:

CODE

cy.expandAccordions();
cy.axeCheck(); // Run the aXe check after expanding everything.

Tests written with the form tester automatically check for accessibility, so this command does not need to be used explicitly in such tests.

cy.axeCheck() configuration defaults

The axe-core configuration object looks like this:

CODE

let axeBuilder = {
  runOnly: {
    type: 'tag',
    values: ['section508', 'wcag2a', 'wcag2aa'],
  },
  rules: {
    'color-contrast': {
      enabled: false,
    },
  },
};

The axeCheck helper method scans pages for Section 508, WCAG2.0 A, and WCAG2.0 AA rulesets every time it is called in a Cypress end-to-end test.

The configuration object also disables color-contrast checks. Disabling the color-contrast rule was carefully considered and discussed with the VA 508 office as a way to improve build times and reduce false positive tests.

VSP relies on foundational accessibility tests and automated unit tests to provide good coverage for color contrast. VSP also strongly encourages teams to re-enable the color-contrast check on one or two Cypress tests per suite.

Enable full rulesets

To add an entire ruleset to your Cypress test, call cy.axeCheck() with two arguments:

A CSS selector string
An object wrapping the runOnly.values array with a new ruleset entry

Be sure not to remove any rulesets from the values[] array. Learn more about axe-core rulesets in the axe-core documentation.

CODE

cy.axeCheck('main', {
  runOnly: {
    values: ['section508', 'wcag2a', 'wcag2aa', 'best-practice'],
  },
});

Enable the color-contrast rule, or add another rule

If you want to enable the color-contrast check or add another rule to your tests, call cy.axeCheck() with two arguments:

A CSS selector string
A parent object wrapping the rules object with a dash-separated string and an { enabled: true } Boolean object.

CODE

cy.axeCheck('main', {
  rules: {
    'color-contrast': {
      enabled: false,
    },
    'css-orientation-lock': {
      enabled: true,
    },
  },
});

axe-core documentation

Learn about the axe-core configuration parameters
Learn about axe-core rulesets if you want to add WCAG2.1 or best practice rules to your Cypress test
Learn about individual axe-core rules if you want to add or ignore individual rules in your Cypress test

Accessibility Convenience Function

Function

injectAxeThenAxeCheck(context, tempOptions)

Source file

injectAxeThenAxeCheck.js

Description

A common pattern in Cypress testing on VA.gov is to call cy.injectAxe() followed by cy.axeCheck(). This custom command is a convenience function for calling these two functions, one after the other.

Arguments

The following arguments are passed to cy.axeCheck() when called inside cy.injectAxeThenAxeCheck().

context -- a String, defaults to main
tempOptions -- an Object, defaults to an empty Object

Count Focusable and Tabbable Elements

Function

hasCount(elementCategory, selector, count)

Source file

hasCount.js

Description

Checks if the count of focusable or tabbable elements is correct.

focusable elements are those in the normal tab order (native focusable elements or those with tabIndex 0). The count logic will break on tabindexes > 0 because we do not want to override the browser's base tab order.

tabbable elements are those in the normal tab order (native focusable elements or those with tabIndex >= 0).

Arguments

elementCategory -- a String. Must be either focusable or tabbable.
selector -- a String
count -- an Integer

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.