API - Level CI Documentation

Level CI – Puppeteer 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


await levelAnalyze(page, {
  strict: true,
})

Manual assertion:


await 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)
 
  includeIframes?: boolean // Include subdocuments (iframes)
 
  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, printViolationsTable.

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:


// puppeteer.config.js
 
const { setupLevel } = require('@level-ci/a11y-puppeteer')
 
setupLevel({
  saveReport: 'json',
  reportPath: 'level-ci-reports',
})

Example Puppeteer Usage


const puppeteer = require('puppeteer')
 
const { levelAnalyze } = require('@level-ci/a11y-puppeteer')
 
;(async () => {
  const browser = await puppeteer.launch({ headless: true })
  const page = await browser.newPage()
  await page.goto('http://localhost:5000')
  await levelAnalyze(page, {
    strict: true,
  })
 
  await browser.close()
})()

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

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


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

Ensure reportPath matches the global setup for correct screenshot references.

Config Defaults

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

Report Structure


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

Reports grouped by execution timestamp.
Violations include errorMessage and recommendation.
Grouped issues (like duplicate IDs) use issuesGroup.

Global Switch – Enable/Disable Analysis


setupLevel({ switchOff: true }) // Disable globally
 
await levelAnalyze(page, { switchOff: true }) // Disable per test

Or via environment variable:


LEVEL_CI_SWITCH_OFF=true node ./dev/puppeteer.test.js

Level CI – Puppeteer API: levelAnalyze