axe-core

Original🇺🇸 English
Translated

axe-core - accessibility testing engine for automated WCAG compliance checks. USE WHEN: user mentions "axe", "automated accessibility testing", "a11y tests", asks about "integrating accessibility checks", "CI/CD accessibility", "Playwright accessibility", "Jest accessibility", "Vitest axe" DO NOT USE FOR: manual accessibility audits - use `wcag` skill instead

39installs
Added on

NPX Install

npx skill4agent add claude-dev-suite/claude-dev-suite axe-core

Tags

Translated version includes tags in frontmatter

axe-core - Quick Reference

When NOT to Use This Skill

  • Manual WCAG compliance audits - Use the
    wcag
    skill for understanding guidelines and manual testing
  • Screen reader testing - axe-core doesn't replace manual screen reader verification
  • Complex ARIA pattern implementation - Use
    wcag
    skill for ARIA authoring practices
  • Accessibility strategy planning - This is for test automation, not accessibility consulting
Deep Knowledge: Use
mcp__documentation__fetch_docs
with technology:
axe-core
for comprehensive documentation on rules, configuration, and integrations.

Setup Base

bash
npm install -D @axe-core/react  # For React
npm install -D axe-core         # Core library

Pattern Essenziali

React DevTools Integration

typescript
import React from 'react';
import ReactDOM from 'react-dom/client';

if (process.env.NODE_ENV !== 'production') {
  import('@axe-core/react').then(axe => {
    axe.default(React, ReactDOM, 1000);
  });
}

Jest/Vitest Integration

typescript
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('should have no accessibility violations', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Playwright Integration

typescript
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('should not have accessibility issues', async ({ page }) => {
  await page.goto('/');

  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});

// With specific rules
test('should pass WCAG AA', async ({ page }) => {
  await page.goto('/');

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

  expect(results.violations).toEqual([]);
});

Cypress Integration

typescript
// cypress/support/commands.ts
import 'cypress-axe';

// In test
describe('Accessibility', () => {
  it('has no violations', () => {
    cy.visit('/');
    cy.injectAxe();
    cy.checkA11y();
  });
});

Programmatic Usage

typescript
import axe from 'axe-core';

async function checkAccessibility() {
  const results = await axe.run();

  if (results.violations.length > 0) {
    console.log('Violations:', results.violations);
  }
}

Anti-Patterns

Anti-PatternWhy It's WrongCorrect Approach
Running axe on empty/loading statesTests incomplete DOM, false negativesWait for content to load before running axe
Ignoring all violationsDefeats purpose of automated testingFix violations or document exceptions with reasoning
Testing only homepageMost accessibility issues in complex interactionsTest all critical user flows and components
Not configuring WCAG levelTests against all rules, may be too strictSet
withTags(['wcag2a', 'wcag2aa'])
for target level
Running axe synchronously in loopsSlow test executionUse
Promise.all()
for parallel execution
Committing violations to CIPrevents catching regressionsFail builds on new violations
Testing hidden/inactive componentsAxe tests invisible elements unnecessarilyUse
exclude
parameter for hidden sections
No baseline for legacy codeAll violations block progressCreate baseline, track improvements incrementally

Quick Troubleshooting

IssueDiagnosisSolution
axe finds no violations but page is inaccessibleAutomated tools catch only ~30-40% of issuesSupplement with manual keyboard and screen reader testing
"No violations" but form has issuesaxe doesn't test form logic/flowTest form submission, error handling manually
Timeout in Playwright axe testsLarge/complex page takes too longIncrease timeout or analyze specific regions
False positive on custom componentaxe rule doesn't understand patternUse
disableRules
or add proper ARIA to fix
Violations in third-party widgetsCan't modify external codeDocument exceptions, contact vendor, or replace widget
Different results in different browsersBrowser-specific rendering differencesRun axe in multiple browsers, use cross-browser test suite
CI fails but local passesEnvironment differences (timing, content)Ensure consistent test data and wait conditions
Too many violations to fix at onceLegacy codebase with extensive issuesCreate baseline, use
--save
flag to track improvements