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

Returns

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

Usage

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

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

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.

Usage

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[]
  experimental?: {
    cssSelector?: {
      stableAttributes?: string[]
      includeClasses?: boolean
      ignoredClassPatterns?: string[]
    }
  }
}

switchOff   boolean

Disable rules check globally or per specific test.

Default: false
Environment variable: LEVEL_CI_SWITCH_OFF
Example value: true
See code examples here.

reportPath   string

Folder path to store analysis artifacts.

Default: 'level-ci-reports'
Environment variable: LEVEL_CI_REPORT_PATH
Example value: 'my-custom-report-path'
See code examples here.

The reportPath should be relative to the project directory from where the Cypress command is executed. 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). Reports are saved to the folder specified by reportPath, or by default in the level-ci-reports folder at the project root.

ignoreUrls   RegExp[]

Skip analysis for URLs matching these patterns.

Example value: [/home/, /settings\/privacy/, /articles\/*/]
See code examples here.

customTags   string[]

Add custom tags for scan identification.

Example values: ['alpha', 'beta', 'scenario-1']
See code examples here.

If you pass ‘scenario-1’ as a custom tag, you will see it among the other tags for the newly found issues on the dashboard. This way you can identify which issue appeared, while testing scenario-1.

Experimental selector configuration

Tune how Level CI builds CSS selectors for elements with accessibility issues. When omitted, Level CI uses its default selector behavior.

stableAttributes   string[]

Use stable attributes when element IDs or generated classes can change between runs. Level CI uses the selector to recognize the same issue over time. If the selector changes, an existing issue can appear resolved and return as a new issue.

Add an attribute whose value stays stable:

<button data-testid="submit-order">Submit order</button>

List attribute names in priority order. Level CI uses the first one that uniquely identifies the element.

Default: ['id']

Example values: ['data-testid'], ['data-testid', 'data-qa']

cy.levelAnalyze({
  experimental: {
    cssSelector: {
      stableAttributes: ['data-testid', 'data-qa'],
    },
  },
})

includeClasses   boolean

Set this to false when your application generates class names that change between builds. Level CI then omits all class names from generated selectors.

cy.levelAnalyze({
  experimental: {
    cssSelector: {
      includeClasses: false,
    },
  },
})

ignoredClassPatterns   string[]

Use this option when only some class names are unstable. Each value is a regular expression pattern for class names Level CI should omit. Write the pattern without leading or trailing /.

Example values: ['^sc-', '^css-']

cy.levelAnalyze({
  experimental: {
    cssSelector: {
      ignoredClassPatterns: ['^sc-', '^css-'],
    },
  },
})

Examples

Set custom report path

Option 1: Globally with levelSetup

levelSetup({
  reportPath: './custom-reports-folder',
})

Option 2: Per test with cy.levelAnalyze

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

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

Option 2: Per test with cy.levelAnalyze

cy.levelAnalyze({
  switchOff: true,
})

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

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

Option 2: Per test with levelAnalyze

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

Configure experimental CSS selectors

Option 1: Globally with levelSetup

levelSetup({
  experimental: {
    cssSelector: {
      stableAttributes: ['data-testid', 'data-qa'],
      includeClasses: false,
      ignoredClassPatterns: ['^sc-', '^css-'],
    },
  },
})

Option 2: Per test with cy.levelAnalyze

cy.levelAnalyze({
  experimental: {
    cssSelector: {
      stableAttributes: ['data-testid', 'data-qa'],
      includeClasses: false,
      ignoredClassPatterns: ['^sc-', '^css-'],
    },
  },
})