Cypress API Reference for Axe DevTools for Web

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Reference for the APIs in the @axe-devtools/cypress package

Not for use with personal data

Cypress Chainable Commands (analyze)

`cy.axeAnalyze()`

This chainable command injects axe-core into the page and into every iframe it can reach, and then runs the analysis on the page. Iframes that cannot be injected into, such as cross-origin iframes and iframes with a sandbox attribute, are skipped rather than failing the test. See Cross-Origin and Sandboxed Iframes.

Parameter	Type	Default Value	Description
name (optional)	String	undefined	Sets the identifier for this scan result stored in the report. Defaults to a timestamp if not provided.
context (optional)	axe.ElementContext	undefined	Defines the scope of the analysis--the part of the DOM that you would like to analyze. This will typically be the document or a specific selector such as class name, ID, selector, etc.
options (optional)	axe.RunOptions	undefined	Set of options passed into rules or checks, temporarily modifying them. This contrasts with `axe.configure`, which is more permanent.
log (optional)	Boolean	false	Returns output to stdout with the number of elements that are not accessible and violation impacts as a table.

`cy.isAxeClean()`

This chainable command is an assertion that the page has no accessibility violations.

Parameters:

Parameter	Type	Default Value	Description
context (optional)	axe.ElementContext	undefined	Defines the scope of the analysis--the part of the DOM that you would like to analyze. This will typically be the document or a specific selector such as class name, ID, selector, etc.
options (optional)	axe.RunOptions	undefined	Set of options passed into rules or checks, temporarily modifying them. This contrasts with `axe.configure`, which is more permanent.

Cypress Chainable Commands (configuration)

Integrate Axe DevTools for Web with Cypress using custom Cypress chainable commands to configure analyzed results.

`cy.setAxeSource()`

This chainable command sets the version of axe-core.

Parameter	Type	Default Value	Description
File path (required)	String	null	Path relative to the root of the project that should include `axe.source` or minified version of axe-core.

`cy.setAxeCustom()`

This chainable command allows the use of custom rulesets.

Axe DevTools for Web Cypress will also implicitly read axe-ruleset.json when placed in the root level of the project or will also use custom ruleset files when the AXE_RULESET_PATH environment variable is set.

Parameter	Type	Default Value	Description
File path (required)	String	null	Path relative to the root of the project that should include checks and rules

`cy.setAxeRuleset()`

This chainable command allows users to run rules per tags, similar to configuring axe.run().

Parameter	Type	Default Value	Description
ruleset (required)	'508', 'en301549', 'rgaav4', 'ttv5', 'wcag2', 'wcag2.1', 'wcag2.2', 'wcag2aaa', 'wcag2.1aaa', 'wcag2.2aaa'	'wcag2.1'	Array of tags that this rule is assigned.

`cy.setAxeReportName()`

This chainable command allows users to set the name of the report file.

Parameter	Type	Default Value	Description
reportName (required)	String	`@axe-devtools-cypress`	Name of the report file.

`cy.getAxeResults()`

This chainable command allows users to utilize the results after running cy.axeAnalyze().

Responses from getAxeResults() returns the data shape axe.AxeResults.

Example:

after(() => {
  cy.axeAnalyze();
  cy.getAxeResults().then(data => {
    cy.writeFile('./results.json', data)
  })
})

`cy.getUniversalResults()`

This chainable command returns the results of the most recent cy.axeAnalyze() call in the Axe Universal Format. Returns null if no analysis has been run yet.

Example:

after(() => {
  cy.axeAnalyze();
  cy.getUniversalResults().then(data => {
    cy.writeFile('./results-universal.json', data)
  })
})

Usage Service

The usage service allows you to gain insight into Axe DevTools for Web usage trends within your organization.

Environment Variables

These environment variables allow you to configure the usage service and change the properties of reported events.

Name	Type	Can Override	Description
`AXE_DISTINCT_ID`	String	—	A UUID identifier that remains the same for the logged-in user (unless it is regenerated). In Ruby, this variable is named `DEQUE_DISTINCT_ID`.
`AXE_INCLUDE_TEST_RESULTS`	Boolean	—	Set to `true` to include the full axe-core results in the `testResults` object of each event (default is `false`). Supported by the CLI and the Node.js APIs only.
`AXE_METRICS_URL`	String	—	The URL of the REST usage endpoint (default is `https://usage.deque.com`)
`AXE_TRACK_USAGE`	Boolean	—	Set to `false` to disable usage service reporting. Reporting is enabled by default.
`AXE_APPLICATION`	String	false	The application that was used to check for accessibility errors
`AXE_DEV_INSTANCE`	Boolean	true	Indicates whether this event is from a software developer's actions. Useful for marking and later removing events logged during development or testing.
`AXE_DEPARTMENT`	String	true	The user's department within the organization
`AXE_KEYCLOAK_ID`	String	false	The user's Keycloak ID
`AXE_LOGGED_IN`	Boolean	false	Records whether the user is logged in to the application under test
`AXE_ORGANIZATION`	String	true	The user's organization. To have your usage appear in Axe Reports, set this to your organization's ID (contact Deque to obtain it).
`AXE_SESSION_ID`	String	false	A UUID identifying the user's session
`AXE_USER_ID`	String	false	A specific user's identity such as an email address, name, or login ID. Axe Reports counts unique users from this value.
`AXE_USER_JOB_ROLE`	String	false	The user's job role
`AXE_USER_STATUS`	String	false	Status information you want to associate with the user

`cy.task('enableTracking', <boolean>)`

This Cypress task allows users to opt in to or out of sending data to the usage service. Sending is enabled by default.

`cy.task('setTrackingUrl', <string>)`

This cypress task allows users to change where the usage metrics data are sent.

`cy.task('setDistinctId', <string>)`

This cypress task allows users to change the distinct id being stored or used.

Next Steps

If you have any issues installing Axe DevTools for Web, contact your Deque representative directly, ask us via our support desk, or send us an email. We’ll be happy to help you get up and running.