Skip to main content
Skip table of contents

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:

  1. A CSS selector string

  2. 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:

  1. A CSS selector string

  2. 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

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


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.