@barrieretest/core

Open-source core for single-page accessibility audits.

@barrieretest/core powers the free single-page checks behind barrieretest.at. It includes:

• axe-core audits for single pages
• optional pa11y fallback support
• scoring and severity levels
• screenshots
• baseline workflows for CI
• optional AI analysis for a single page
• cookie banner dismissal before audits

It does not include:

• multi-page crawling or page discovery
• cross-page AI synthesis
• PDF reports
• payments
• email delivery
• invoice generation

Install

For most use cases, install the core plus Puppeteer:

npm install @barrieretest/core puppeteer

Add pa11y only if you want the optional pa11y engine:

npm install @barrieretest/core puppeteer pa11y

What you need

• URL audits and the CLI need puppeteer
• Existing Playwright or Puppeteer page audits use the page you pass in
• engine: 'pa11y' needs both pa11y and puppeteer
• Default engine is axe

Quick start

Audit a URL with the default axe engine:

import { audit } from '@barrieretest/core'

const result = await audit('https://example.com')
console.log(`Score: ${result.score}/100`)
console.log(`Issues: ${result.issues.length}`)

Audit an existing page directly:

const result = await audit(page)

Use pa11y explicitly:

const result = await audit('https://example.com', {
  engine: 'pa11y',
})

CLI

Run a single-page audit:

npx barrieretest https://example.com
npx barrieretest https://example.com --json
npx barrieretest https://example.com -d minimal
npx barrieretest https://example.com -s serious
npx barrieretest https://example.com -o results.json
npx barrieretest https://example.com --engine pa11y

Default CLI engine: axe.

Baseline workflow:

# Create a baseline
npx barrieretest baseline https://example.com -o baseline.json

# Audit against a baseline (only new issues fail)
npx barrieretest https://example.com -b baseline.json

# Accept the last audit run into a baseline
npx barrieretest baseline:accept baseline.json

# Re-audit and update all baselines in a directory
npx barrieretest baseline:update ./baselines

results.json from -o is an audit result, not a baseline file.

API

audit(target, options?)

Run a single-page accessibility audit.

import { audit } from '@barrieretest/core'

const result = await audit('https://example.com')

const filtered = await audit('https://example.com', {
  engine: 'axe',
  minSeverity: 'serious',
  ignore: ['color-contrast'],
  detail: 'fix-ready',
  baseline: './baseline.json',
})

const fromPage = await audit(page)

const pa11yResult = await audit('https://example.com', {
  engine: 'pa11y',
})

Options

Notes:

• engine: 'axe' is the default and recommended engine
• engine: 'pa11y' requires pa11y and puppeteer
• URL audits with the axe engine require puppeteer
• detail: 'fix-ready' adds fix suggestions to formatted output
• Source localization only runs when auditing an existing Puppeteer page

Returns

{
  url: string
  documentTitle: string
  score: number
  severityLevel: string
  scoreInterpretation: { ... }
  issues: Issue[]
  screenshot?: Uint8Array
  timestamp: string
  baseline?: BaselineInfo
}

Browser pages

The default axe engine can run directly on an existing browser page.

That means:

• Puppeteer pages are supported directly
• Playwright pages are supported directly
• the current session state is preserved
• cookie banner dismissal still runs before the audit

If you use engine: 'pa11y', only Puppeteer pages are supported.

Baselines

Use baselines to treat existing issues as known and fail only on regressions.

const result = await audit('https://example.com', {
  baseline: './accessibility-baseline.json',
})

if (result.baseline) {
  console.log(`New: ${result.baseline.newIssues.length}`)
  console.log(`Known: ${result.baseline.knownIssues.length}`)
  console.log(`Fixed: ${result.baseline.fixedIssues.length}`)
}

Update a baseline in code:

await audit(url, { baseline: './baseline.json', updateBaseline: true })

Or with an environment variable:

BARRIERETEST_UPDATE_BASELINE=true npx barrieretest https://example.com -b baseline.json

Issue formatting helpers

import { formatIssues } from '@barrieretest/core'

formatIssues(result.issues, 'minimal')
formatIssues(result.issues, 'actionable')
formatIssues(result.issues, 'fix-ready')

AI enhancement

const result = await audit('https://example.com', {
  ai: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4o',
    maxIssues: 10,
  },
})

Providers: openai, anthropic, nebius.

Cookie banner dismissal

Cookie banner dismissal runs before audits for both:

• URL audits
• existing browser page audits

You can also call it directly:

import { dismissCookieBanner } from '@barrieretest/core'

await dismissCookieBanner(page)

Playwright integration

See @barrieretest/playwright for Playwright test integration on live Playwright pages.

Requirements

• Node.js 18+
• puppeteer for URL audits and CLI usage
• pa11y only if you want the optional pa11y engine

License

MIT