Cypress API

API Methods

cy.levelAnalyze

cy.levelAnalyze(config?: AnalyzeConfig): Chainable<AnalysisResult>

Runs a static accessibility analysis on the current page and generates a folder with analysis result data. By default, asserts that the number of violations is equal to zero.

Properties

Property	Type	Default	Description
config	AnalyzeConfig	{}	Optional configuration object

Returns

Returns a Cypress Chainable that resolves to the analysis result. Use .then() to access violations and reports when strict: false.

Usage

Important: Make sure to use cy.levelAnalyze() after your tests have run successfully. If you add it to an afterEach hook, add a condition to check the success of test execution. Otherwise, every rerun of a test (if you have retries) will produce a new report that is to be uploaded and processed, even when the test fails in the middle of execution.

levelSetup

levelSetup(config: AnalyzeConfig): void

Configure global settings for all Level CI analysis runs. Use this in your Cypress support file for a clean setup.

Properties

Property	Type	Default	Description
config	AnalyzeConfig	—	Global configuration object

Returns

No return value (void). Configuration is stored globally and applied to all subsequent cy.levelAnalyze calls.

Note: Global configuration can be overridden per test. For this provide config per cy.levelAnalyze call. Arrays and objects are merged with test-level config.

Config

AnalyzeConfig

Component-level screenshots (experimental)

To enable component-level screenshots for detected accessibility issues, add the experimental.elementScreenshots option to your cy.levelAnalyze() configuration.

This setting is currently experimental. Enabling component-level screenshots may increase scan execution time because screenshots are   captured during the accessibility analysis.

Examples

Examples

Use these examples to set a custom report path, disable rule checks, ignore specific URLs during analysis, add tags, and add stable selector attributes.

Method cy.levelAnalyze

|
cy.levelAnalyze(config?: AnalyzeConfig): Chainable<AnalysisResult>
        

Usage cy.levelAnalyze

|
it('homepage accessibility', () = {
  cy.visit('/')
  cy.levelAnalyze({
    reportPath: './custom-reports-folder',
  })
})
        

Method levelSetup

|
levelSetup(config: AnalyzeConfig): void
        

Option 1 In Cypress support file

|
// cypress/support/e2e.js
import { levelSetup } from '@level-ci/a11y-cypress'

levelSetup({
  reportPath: 'level-ci-reports-custom',
  ignoreSelectors: ['data-level-ci-app-ignore'],
})
        

Then use in tests

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

Option 2 Via cypress.config.js

|
// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    supportFile: 'cypress/support/e2e.js',
  },
  levelAppConfig: {
    reportPath: 'level-ci-reports',
    switchOff: false,
  },
})
        

Config AnalyzeConfig

|
interface AnalyzeConfig {
  switchOff?: boolean
  reportPath?: string
  ignoreUrls?: RegExp[]
  customTags?: string[]
  stableSelectorAttributes?: string[]
}
        

switchOff boolean

|
// 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)
})
        

Component-level screenshots (experimental)

Enable component-level screenshots Experimental

|
          cy.levelAnalyze({
          experimental: {
          elementScreenshots: true,
          },
          })
        

Examples

Set custom report path Option 1: Globally with levelSetup

|
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' })
})
        

Set custom report path Option 2: Per test with cy.levelAnalyze

|
cy.levelAnalyze({
  reportPath: './custom-reports-folder',
})
        

Set custom report path Option 3: Using environment variable

|
cypress run --env LEVEL_CI_REPORT_PATH=./custom-reports
        

Disable rule check Option 1: Globally with levelSetup

|
levelSetup({
  switchOff: true,
})
        

Disable rule check Option 2: Per test with cy.levelAnalyze

|
cy.levelAnalyze({
  switchOff: true,
})
        

Disable rule check Option 3: Using environment variable

|
cypress run --env LEVEL_CI_SWITCH_OFF=true
        

Ignore specific URLs during analysis Option 1: Globally with levelSetup

|
levelSetup({
  ignoreUrls: [/localhost:3000/, /example.com/],
})
        

Ignore specific URLs during analysis Option 2: Per test with cy.levelAnalyze

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

Add specific tags for this analysis run Option 1: Globally with levelSetup

|
levelSetup({
  customTags: ['my-tag', 'regression'],
})
        

Add specific tags for this analysis run Option 2: Per test with levelAnalyze

|
await levelAnalyze(page, {
  customTags: ['my-tag', 'regression'],
})
        

Add stable selector attributes Option 1: Globally with levelSetup

|
levelSetup({
  stableSelectorAttributes: ['data-testid', 'data-qa'],
})
        

Add stable selector attributes Option 2: Per test with levelAnalyze

|
await levelAnalyze(page, {
  stableSelectorAttributes: ['data-testid', 'data-qa'],
})