API

Level CI – Playwright API: `levelAnalyze`

Runs a static accessibility analysis on the current page and returns a result object containing violations.
By default, it asserts that the number of violations is zero.

Default Config


levelAnalyze(page, {
  strict: true,
})

For manual assertion:


levelAnalyze(page, { strict: false }).then((res) => {
  expect(res.violations).to.have.length(0)
})

Full Config


type AnalyzeConfig = {
 
  includeRules?: string[] // Only include these rules
 
  excludeRules?: string[] // Exclude rules (overrides includeRules)
 
  strict?: boolean // Set false to manually process results
 
  saveReport?: 'json' // Format for report
 
  reportPath?: string // Folder to store artifacts (global config only, default: 'level-ci-reports')
 
  ignoreSelectors?: string[] // Default: ["data-level-ci-app-ignore"]
 
  ignoreUrls?: RegExp[] // Skip analysis for specific URLs
 
  switchOff?: boolean // Disable rules check globally or per test
 
  onResult?: (data: AnalysisResult) => void // Hook called when result is ready
 
}

Removed fields: failInapplicable, failIncomplete, userwayAnalysis references.

Examples


// Save HTML report and screenshots
await levelAnalyze(page, {
  saveReport: 'json',
})
 
// Enable only includeRules
await levelAnalyze(page, {
  level: null,
  includeRules: ['duplicate-id', 'color-contrast'],
})
 
// Disable all rules
await levelAnalyze(page, { level: null })
 
// Manual assertion
await levelAnalyze(page, { strict: false }).then((res) => {
  console.log(res.fullReport)
  expect(res.violations).to.have.length(0)
})

Global Setup – `setupLevel(config: AnalyzeConfig)`

Set global configuration once to avoid passing config on every call.


// playwright.config.ts
 
import { defineConfig } from '@playwright/test'
 
import { setupLevel } from '@level-ci/a11y-playwright'
 
setupLevel({
  saveReport: 'json',
  reportPath: 'level-ci-reports',
})
 
export default defineConfig({})

Or in global setup file:


// global.setup.ts
 
import { test as setup } from '@playwright/test'
 
import { setupLevel } from '@level-ci/a11y-playwright'
 
setupLevel({
  saveReport: 'json',
  reportPath: 'level-ci-reports',
})
 
setup('do login', async ({ page }) => {
  // test setup steps
})

Global configuration can be overridden per test. Arrays and objects are merged.

Saving Reports Manually – `saveReportArtifacts(config: SaveReportConfig)`

Useful for conditional saving based on violations:


await levelAnalyze(page, { strict: false }).then((res) => {
  saveReportArtifacts({ violations: res.violations, saveReport: 'json' })
})

Ensure reportPath matches the global setup so screenshots are accessible.

Config Defaults

Field	Default
`strict`	`true`
`ignoreSelectors`	`["data-level-ci-app-ignore"]`
`saveReport`	`'json'`
`reportPath`	`'level-ci-reports'`
`includeRules`	`[]`
`excludeRules`	`[]`
`switchOff`	`false` (can also use env variable)

Report Path & Structure

Default folder: level-ci-reports
Structure:


level-ci-reports/
├─ reports/ # Accessibility reports (HTML/JSON/CSV)
├─ pages/ # Original HTML of tested pages
└─ screenshots/ # Screenshots (if enabled)

Reports are grouped by test title.
Violations include errorMessage and recommendation fields.
Grouped issues (like duplicate IDs) use issuesGroup for clarity.

Global Switch – Enable/Disable Analysis

Disable globally:


setupLevel({ switchOff: true })

Disable per test:


await levelAnalyze(page, { switchOff: true })

Or via environment variable:


LEVEL_CI_SWITCH_OFF=true playwright test ./tests/my-test.spec.ts

API

Level CI – Playwright API: levelAnalyze