Skip to content

axe-core-integration.md

Latest commit

 

History

History
142 lines (101 loc) · 4.73 KB

axe-core-integration.md

File metadata and controls

142 lines (101 loc) · 4.73 KB

axe-core Integration

The agents review your code and enforce accessibility patterns during development. axe-core tests the rendered page in a real browser. Together, they cover both sides: code-time enforcement and runtime verification.

Three Levels of Integration

  1. MCP tool (run_axe_scan) - Agents trigger axe-core scans programmatically via the MCP server
  2. Agent instructions - The testing-coach and web-accessibility-wizard know when and how to run scans
  3. VS Code task - Manual scan trigger in the VS Code command palette

How the MCP Tool Works

The run_axe_scan tool:

  1. Takes a URL (your running dev server), an optional CSS selector, and an optional report file path
  2. Runs @axe-core/cli against the live page
  3. Parses the JSON results
  4. Returns violations grouped by severity (Critical > Serious > Moderate > Minor)
  5. Includes affected HTML elements, WCAG criteria, and fix suggestions
  6. When reportPath is provided, writes a structured markdown report to that file

Prerequisites:

npm install -g @axe-core/cli

Report Generation

The tool generates markdown reports with:

  • Scan metadata (URL, date, standard, scanner)
  • Summary table of violations by severity
  • Each violation with WCAG criteria, help link, and affected elements
  • HTML snippets showing problematic code
  • Fix suggestions from axe-core

Output files:

File Written By Contents
ACCESSIBILITY-SCAN.md run_axe_scan tool Raw axe-core scan results
ACCESSIBILITY-AUDIT.md web-accessibility-wizard Consolidated: agent review + axe-core, deduplicated, with fixes

How Agents Use It

The web-accessibility-wizard (Phase 9) asks if you have a dev server running and triggers a scan:

/web-accessibility-wizard run a full audit on this project
@web-accessibility-wizard audit this project for accessibility

The testing-coach runs ad-hoc scans:

/testing-coach run an axe-core scan on http://localhost:3000/dashboard
@testing-coach scan http://localhost:3000/checkout for accessibility issues

Any agent can interpret results you feed manually:

npx @axe-core/cli http://localhost:3000 --save results.json
/accessibility-lead triage the violations in results.json

CI/CD Pipeline

GitHub Actions:

- name: Run axe-core accessibility tests
  run: |
    npx @axe-core/cli http://localhost:3000 \
      --tags wcag2a,wcag2aa,wcag21a,wcag21aa \
      --exit

Test framework packages:

npm install --save-dev @axe-core/playwright   # Playwright
npm install --save-dev cypress-axe axe-core   # Cypress
npm install --save-dev jest-axe               # Jest (React)

What Catches What

Issue Type Agents axe-core Manual Testing
Missing alt text Yes Yes Yes
ARIA pattern correctness Yes Partial Yes
Computed contrast ratios No Yes Yes
Focus management logic Yes No Yes
Live region timing Yes No Yes
Tab order design Yes No Yes
Keyboard trap detection Yes No Yes
Third-party widget issues No Yes Yes
Screen reader UX No No Yes

Agents catch ~70% of issues during code generation. axe-core catches some of the remaining issues by testing the rendered DOM. Manual testing covers what tools cannot.

Playwright + axe-core (Layer 3)

The @axe-core/playwright package enables axe-core scanning within Playwright, creating a third assessment layer that catches defects in dynamic states that the CLI cannot reach:

MCP Tools

Tool axe-core Usage
run_playwright_state_scan Clicks triggers, runs AxeBuilder on revealed content
run_playwright_viewport_scan Runs AxeBuilder at each viewport width

What Playwright + axe-core Catches

Scenario axe-core CLI Playwright + axe-core
Static page violations Yes Yes
Violations in expanded accordions No Yes
Violations in open menus No Yes
Violations in modal dialogs No Yes
Viewport-specific violations No Yes
Touch target size at mobile widths No Yes

Three-Source Confidence

When an issue is found by all three sources (agent code review + axe-core CLI + Playwright behavioral scan), it receives Confirmed confidence with a 1.2x weight multiplier in severity scoring.

Installation

npm install -D playwright @axe-core/playwright
npx playwright install chromium

Playwright is optional. Without it, the CLI-based workflow continues as before.

See Playwright Integration for full details.