API - Level CI Documentation

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


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

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.

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[]
  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)
})

Examples

Set custom report path

Option 1: Globally with levelSetup

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

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

Add stable selector attributes

Option 1: Globally with levelSetup


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

Option 2: Per test with levelAnalyze


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