API Methods

levelAnalyze

levelAnalyze(page: Page, config?: LaunchConfig): Promise<AnalysisResultData>

Runs a static accessibility analysis on the current page and generates a folder with analysis result data.

Properties

Returns

Returns a Promise, which should resolve, otherwise return value will contain error object.

Usage

test('homepage accessibility', async ({ page }) => {
  await levelAnalyze(page, {
    reportPath: './custom-reports-folder',
  })
})

Important: Make sure to use levelAnalyze after your tests have run successfully. If you add it to some kind of an afterTest hook, add a condition to check the success of test execution:

if (test.succeeded) {
  await levelAnalyze(page)
}

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: LaunchConfig): void

Configure global settings for all Level CI analysis runs. Use this in Playwright fixtures for a clean setup.

Properties

Returns

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

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

Usage

You can use levelSetup in multiple ways. The recommended approach would be to use Playwright’s fixtures  to expose a helper per test.

Option 1: Pass page to analyze function

// playwright/fixtures.ts
import { test as base } from '@playwright/test'
import { levelAnalyze, levelSetup } from '@level-ci/a11y-playwright'
 
export const test = base.extend({
  levelCiAnalyze: async ({}, use) => {
    levelSetup({
      reportPath: 'level-ci-reports-custom',
      stableSelectorAttributes: ['data-testid'],
    })
 
    await use(levelAnalyze)
  },
})

Then you will be able to use it in tests:

// playwright/demo.spec.ts
import { expect } from '@playwright/test'
import { test } from '../fixtures'
 
test.describe('test', () => {
  test('runs Level CI analysis on the home page', async ({
    levelCiAnalyze,
    page,
  }) => {
    await page.goto('/')
 
    const config = {}
    await levelCiAnalyze(page, config)
  })
})

Option 2: Page pre-configured in fixture

Or you can pass page parameter to levelAnalyze in fixture:

// playwright/fixtures.ts
import { test as base } from '@playwright/test'
import { levelAnalyze, levelSetup } from '@level-ci/a11y-playwright'
 
export const test = base.extend({
  levelCiAnalyze: async ({ page }, use) => {
    levelSetup({
      reportPath: 'level-ci-reports-custom',
      stableSelectorAttributes: ['data-testid'],
    })
 
    const analyzePage = (args) => levelAnalyze(page, args)
    await use(analyzePage)
  },
})

// playwright/demo.spec.ts
import { expect } from '@playwright/test'
import { test } from '../fixtures'
 
test.describe('test', () => {
  test('runs Level CI analysis on the home page', async ({
    levelCiAnalyze,
    page,
  }) => {
    await page.goto('/')
 
    const config = {}
    await levelCiAnalyze(config)
  })
})

Config

LaunchConfig

interface LaunchConfig {
  switchOff?: boolean
  reportPath?: string
  ignoreUrls?: RegExp[]
  customTags?: string[]
  stableSelectorAttributes?: 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.

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.

stableSelectorAttributes   string[]

Add to reliably identify elements with dynamic IDs.

Example values: ['data-testid']
See code examples here

Why is this needed? Flaky issues often occur when elements have dynamic IDs. Level CI tracks elements across scans to monitor accessibility issues, but if an element’s id changes between scans, it treats it as a new element. This causes old issues to close and new issues to open for the same element.

Usage:

1. Add a stable attribute to elements with dynamic IDs, e.g.:

<p data-testid="hello-paragraph-element">
  Hello from an element with a dynamic id attribute
</p>

2. Configure Level CI to use this attribute in levelAnalyze:

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

Examples

Set custom report path

Option 1: Globally with levelSetup

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

Option 2: Per test with levelAnalyze

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

Option 3: Using environment variable

LEVEL_CI_REPORT_PATH=./custom-reports

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

Disable rule check

Option 1: Globally with levelSetup

levelSetup({
  switchOff: true,
})

Option 2: Per test with levelAnalyze

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

Option 3: Using environment variable

LEVEL_CI_SWITCH_OFF=true

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

Ignore specific URLs during analysis

Option 1: Globally with levelSetup

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

Option 2: Per test with levelAnalyze

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