API

Level CI – Cypress API: `levelAnalyze`

`cy.levelAnalyze()` Runs a static analysis on the current page and return a result object that contains violations. By default, it asserts that the number of violations is equal to zero.

Default config


cy.levelAnalyze({})

Full config


type Config = {
  excludeRules: string[] // Provide a list of rules that should be excluded
  includeRules: string[] // Provide a list of rules that should be included
  onResult: (data: Result) => void // Hook that is called when result is ready
  reportPath: string // Path to folder where artifacts are stored (global configuration only). Default is "level-ci-reports"
  ignoreSelectors: string[] // Selectors for elements that should be ignored. Default is ["data-level-ci-app-ignore"]
  switchOff: boolean // Allows turning off rules check without modifying tests
}

Examples


// Save report and screenshots
 
cy.levelAnalyze({
  elementScreenshots: true,
})
 
// Enable rules from includeRules parameter only
 
cy.levelAnalyze({
  level: null,
  includeRules: ['duplicate-id', 'color-contrast'],
})
 
// Disable all rules
 
cy.levelAnalyze({
  level: null,
})
 
// Manually assert
 
cy.levelAnalyze({ strict: false }).then((res) => {
  const { fullReport, violations } = res
  // Log the full report
  console.log(fullReport)
  // Save JSON report
  cy.levelSaveReport(violations, 'json')
  // Assert
  expect(violations).to.have.length(0)
})

`cy.levelSaveReport(config: SaveReportConfig): void`

Save violation reports in manual control mode. It’s handy when you need to save a report conditionally, based on violations or custom logic.

cy.levelSaveReport depends on the report from cy.levelAnalyze and requires violations data.

The output format and path can be customized using the format and reportPath parameters in global configuration.

Ensure the reportPath provided to cy.levelSaveReport and the path defined in global config are the same so screenshots are accessible.


import { setupLevel } from '@level-ci/a11y-cypress'
 
setupLevel({
  reportPath: 'level-ci-reports',
})
cy.levelAnalyze({
  strict: false,
}).then((res) => {
  const { fullReport, violations, screenshotsMeta } = res
  // Save JSON report
  cy.levelSaveReport({ violations, format: 'json' })
})

Config

ignoreSelectors

Default: ["data-level-ci-app-ignore"]

ignoreUrls

Skips tests for specific URLs (array of RegExp).


cy.levelAnalyze({
  ignoreUrls: [/localhost:3000/, /example.com/],
})

reportPath

Custom path for reports and artifacts.
Default: level-ci-reports

Global configuration

cypress.config.js


const { defineConfig } = require('cypress')
 
module.exports = defineConfig({
  e2e: {
    specPattern: 'dev/**/*.cy.{js,jsx,ts,tsx}',
    supportFile: false,
  },
 
  levelAppConfig: {
    // your parameters
  },
})

setupLevel()


import { setupLevel } from '@level-ci/a11y-cypress'
 
setupLevel({
  strict: true,
  reportPath: 'level-ci-reports',
})

Report Path Customization

You can also pass an environment variable:


cypress open --env LEVEL_CI_CA_REPORT_PATH=custom-path

Default reports folder: level-ci-reports

Report Path and Structure

The reportPath should be relative to the project directory from where the Cypress command is executed.

In the following example, a folder artifacts-results will be created at the same level where the Cypress command is executed (most commonly next to the package.json file). The reports folder will contain an HTML file with the output and a subfolder with related screenshots (because elementScreenshots: true was passed to the static analysis function).

Reports are grouped by test title to make it easier to navigate to specific test results.


// cypress/support/e2e.js
 
import { setupLevel } from '@level-ci/a11y-cypress'
 
setupLevel({
  reportPath: 'level-ci-reports',
})
cy.levelAnalyze({
  elementScreenshots: true,
})

Report Structure

Reports are saved to the folder specified by reportPath, or by default in the level-ci-reports folder at the project root.

The structure includes:

reports/ – Accessibility reports containing violation details and references to other artifacts
pages/ – Original HTML of tested web pages

Error Messages and Recommendations

Each violation in the report contains two fields:

errorMessage – Explains the WCAG-related error
recommendation – Provides guidance for fixing the issue

These fields help you understand the root cause of violations and apply the correct fix.

Violation Variations

Some violations may have multiple root causes.

For example:

The image-alt rule can fail if the alt attribute is missing, or if it exists but is empty.

The variant field in the violated element selector points to the specific detail described in errorMessage and recommendation, helping you identify the exact root cause and apply a precise fix.

Global Switch

The Global Switch allows you to toggle accessibility analysis on or off. This is useful when debugging locally with or without static analysis enabled.

You can disable analysis in two ways:

1. Global Config


// cypress.config.js
 
const { defineConfig } = require('cypress')
 
module.exports = defineConfig({
  e2e: {
    specPattern: 'dev/**/*.cy.{js,jsx,ts,tsx}',
    supportFile: false,
  },
 
  levelAppConfig: {
    switchOff: true,
    reportPath: 'level-ci-reports',
  },
})


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

2. Per Test


cy.levelAnalyze({
  switchOff: true,
})

3. Environment Variable

You can also pass an environment variable to Cypress CLI:


cypress open --config-file dev/cypress.config.js --browser chrome --e2e --env LEVEL_CI_CA_SWITCH_OFF=true

For more information about Cypress environment variables, see the official Cypress docs .

API

Level CI – Cypress API: levelAnalyze

cy.levelAnalyze() Runs a static analysis on the current page and return a result object that contains violations. By default, it asserts that the number of violations is equal to zero.