Programmatic Audits

runAccessibilityAudit returns a promise that resolves to an array of AccessKitAuditFinding. It uses the same default WCAG rule tags as DevTools (2.0 / 2.1 / 2.2 levels A, AA, and AAA) and accepts the same optional additionalTags as AccessKitDevTools’ additionalRules.

Browser Only:

The audit runs against a real Document. In Node, window must exist; use a browser, Playwright’s page context, or a DOM environment such as Vitest’s jsdom (see below). Plain Node without a DOM will not run rules.

Basic usage

import {
  runAccessibilityAudit,
  formatAuditFindingsForConsole,
} from "@access-kit/react"

// In a browser context (e.g. after navigation in Playwright):
const findings = await runAccessibilityAudit(document, {
  additionalTags: ["best-practice", "cat.forms"],
  logToConsole: true,
})

console.log(formatAuditFindingsForConsole(findings))

Tests with Vitest + jsdom

Point Vitest at the jsdom environment so document exists. This is ideal for component-level smoke checks; for full-page visual and contrast behavior, prefer Playwright or the CI script in Auditing in CI.

import { describe, it, expect } from "vitest"
import { runAccessibilityAudit } from "@access-kit/react"

describe("MyPage", () => {
  it("has no blocking WCAG errors in default rules", async () => {
    document.body.innerHTML = `
      <main><h1>Hello</h1><button>OK</button></main>
    `
    const findings = await runAccessibilityAudit(document)
    const errors = findings.filter((f) => f.severity === "error")
    expect(errors).toEqual([])
  })
})

Run with

vitest run --environment jsdom

Options

• additionalTags: Same values as DevTools (e.g. "best-practice", "section508", "cat.color").
• logToConsole: When true, prints a formatted summary via formatAuditFindingsForConsole.

See also

• Auditing in CI: headless multi-page audits in the pipeline.
• Custom reporting: filter and export findings.