Getting started

The @level-ci/a11y-cypress package enables accessibility testing in your Cypress workflow.
It extends Cypress commands so you can run static page analysis and generate detailed reports of accessibility violations based on WCAG guidelines and ACT rules.

// cypress/e2e/my-test.js
import '@level-ci/a11y-cypress'
 
it('example test', () => {
  cy.visit('http://localhost:5000')
  cy.levelAnalyze()
})

Prerequisites

• Cypress version 10.0.0 or higher

Installation

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

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}

2. Declare a Cloudsmith Token

export CLOUDSMITH_TOKEN=MY_CLOUDSMITH_TOKEN

By using the CLOUDSMITH_TOKEN you will be able to install the needed package.

3. Install the package.

You can do this by using either npm or yarn.

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

yarn add -D @level-ci/a11y-cypress

This will add @level-ci/a11y-cypress to the dev dependencies in package.json.

Setup

For succesfull working cy.levelAnalyze() Cypress tasks need be configured in cypress.config.* file

// cypress/cypress.config.ts
import { createLevelCiTasks } from '@level-ci/a11y-cypress/tasks'
import { defineConfig } from 'cypress'
 
export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('task', createLevelCiTasks(config))
    },
  },
})

Level CI App Cypress extends Cypress commands and must be imported in your Cypress support file.

Call cy.levelAnalyze() right away

Import @level-ci/a11y-cypress in your support file and use the command in tests:

// cypress/support/e2e.js
import '@level-ci/a11y-cypress'
 
// cypress/e2e/google-accessibility.cy.js
it('Google basic example', () => {
  cy.visit('https://www.google.com')
  cy.levelAnalyze()
})

Use levelSetup for global setup

// cypress/support/e2e.js
import { levelSetup } from '@level-ci/a11y-cypress'
 
levelSetup({
  reportPath: 'level-ci-reports-custom',
  stableSelectorAttributes: ['data-testid'],
})

Then you will be able to use it in tests:

// cypress/e2e/demo.cy.js
it('runs Level CI analysis on the home page', () => {
  cy.visit('/')
  cy.levelAnalyze()
})

Note: For more details see levelSetup usage.

Running cy.levelAnalyze() will create a report folder, where all of the issues data will be contained. File structure for the directory enables issue deduplication, which helps in achieving faster scans.

TypeScript Support

If you are using TypeScript, add @level-ci/a11y-cypress to the types section in your tsconfig.json:

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

If you are not using TypeScript, you can still enable autocompletion by adding type references at the top of your test files:

/// <reference types="cypress" />
 
/// <reference types="@level-ci/a11y-cypress" />