Accessibility Scan with Cypress

Extend Cypress E2E Tests with Level CI Accessibility Analysis

Level CI integrates accessibility analysis directly into your existing Cypress end-to-end tests through the @level-ci/a11y-cypress npm package. This package extends Cypress commands, collects accessibility insights during test execution, and saves reports in the level-ci-reports directory.

1. Configure `.npmrc` and Install `@level-ci/a11y-cypress` Package

Follow these steps to configure your project and install the Level CI Cypress package:

A. Configure your `.npmrc` file

Run the following commands in the root of your project to configure the registry and authentication:


npm config --location project set @level-ci:registry https://npm.levelaccess.net/level-ci/
npm config --location project set //npm.levelaccess.net/level-ci/:\_authToken=\${CLOUDSMITH_TOKEN}

B. Declare your Cloudsmith Token

Export your Cloudsmith token as an environment variable:


export CLOUDSMITH_TOKEN=<token>

(Replace the example token above with your actual token.)

C. Install `@level-ci/a11y-cypress`

Install the package in the root of your Cypress E2E project:


npm install --save-dev @level-ci/a11y-cypress

For more details on installation, refer to the Level CI documentation.

2. Update Cypress Support File

Import and invoke the setupLevelCI() function in your Cypress support file (typically cypress/support/e2e.js or cypress/support/e2e.ts) to initialize accessibility analysis:


// cypress/support/e2e.js
 
import { setupLevelCI } from '@level-ci/a11y-cypress'
 
setupLevelCI({
  reportPath: './level-ci-reports',
})

This sets up the default configuration and output directory.

3. Update Cypress E2E Tests

Use the cy.levelAnalyze() function in your existing tests to perform accessibility checks at any point during execution. Each invocation generates a report saved in the level-ci-reports folder.


cy.levelAnalyze()

Best Practice: Invoke cy.levelAnalyze() at the end of each test case.

Example Usage:


it('basic example', () => {
  cy.visit('https://example.com')
  cy.levelAnalyze()
})

Note: Each invocation counts toward your project’s Self-Hosted scan quota.

For full configuration options, see the Cypress API documentation.

4. Optional Configuration

TypeScript Users: Update your tsconfig.json to include the package types:


{
  "compilerOptions": {
    "types": ["cypress", "@level-ci/a11y-cypress"]
  }
}

Git Ignore Reports: Add the report directory to .gitignore to avoid committing generated reports:


level-ci-reports

5. Verify Configuration

Before committing changes, validate that your setup works:

Apply all the steps above.
Run your E2E tests locally.
Confirm there are no errors and all tests pass.
Check level-ci-reports/ for JSON report files. The number of reports should match the number of cy.levelAnalyze() invocations. Example file: level-ci-report-lvoeobzh.json.

For troubleshooting, refer to the Level CI troubleshooting documentation.

6. Prerequisites

Compatible with Chrome and Chromium only
Cypress v10.0.0 or higher
Node.js v16.20.2 or higher