# cypress-axe error a11y violations found in test run - how to fix it

## TL;DR

Read the violation table, fix the flagged rules, and keep the test red until they are fixed: the error means the harness works and your page has real violations. Triage by impact (critical first), apply the rule-specific fixes, and re-run. One line of why: checkA11y fails the test on purpose when violations exist, the error is the feature, not a bug.

## The error, verbatim

```text
AssertionError: a11y violations found!
    3 violations:
    - color-contrast (serious): 12 nodes
    - image-alt (critical): 2 nodes
    - link-name (serious): 4 nodes
    at checkA11y (node_modules/cypress-axe/dist/index.js)

```

## Fix it step by step

### Step 1: Reproduce and capture the table

```bash
npx cypress run --spec cypress/e2e/a11y.cy.js | rg -A30 'violations found' | head -40
```

Expected: The violation table with rule ids, impacts, and node counts.

### Step 2: Get the full JSON for node targets

```bash
rg -n 'checkA11y' cypress/e2e/a11y.cy.js | head -5
```

Expected: Find the checkA11y call to add a violation callback that logs targets, or run axe DevTools on the same page.

### Step 3: Fix critical first

```bash
npx cypress run --spec cypress/e2e/a11y.cy.js | rg 'critical' | head -10
```

Expected: Watch the critical count drop as you apply the rule-specific fixes.

### Step 4: Re-run to green

```bash
npx cypress run --spec cypress/e2e/a11y.cy.js | tail -4
```

Expected: Spec passes with zero violations.

### Step 5: Re-run twice to rule out flakes

```bash
npx pa11y https://example.com/ | tail -2
```

Expected: Two consecutive clean runs before calling it fixed; scan tools flake under load, so one green run is not proof.

## When to use this skill

- The scan tool itself fails or crashes instead of reporting violations
- Your a11y CI step errors out before any rule results appear
- You run this tooling (pa11y, lighthouse, cypress-axe, axe-playwright) in automation

## When NOT to use this skill

- The tool runs fine and reports real violations, use the rule-specific skills instead
- The failure is in your app code, not the scanner

## Compatibility

cypress-axe 1.x with Cypress 12/13. The violation output maps to axe-core rule ids, fix each with its rule skill. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### checkA11y found violations

Same assertion, same triage.

### cypress a11y test failing violations

Practitioner phrasing, the test is doing its job.

### same failure locally and in CI

Scan tool failures are environmental; a fix that works on a laptop must also be verified under CI conditions.

## Why it happens

checkA11y asserts zero violations by default, so any axe failure fails the Cypress test. Teams newly adding the spec see this on the first run and read it as a tool error, but it is the test working as designed. The right response is triaging the table: critical impact first, then serious, then the rest. The wrong response is configuring checkA11y to ignore rules until it passes without fixing anything. Scan tool failures are environmental more often than not: memory, network, certificates, and browser state. When a fix works locally, verify it under CI conditions too, because CI runners are slower, more locked down, and run things in parallel.

## Edge cases

- Use the includedImpacts option to fail only on critical and serious while the team works through moderate issues.
- Log the violation callback output to a file in CI so triage does not require re-running Cypress.
- Do not exclude rules permanently to get green, track exclusions with a fix-by date.
- Record the working flags in CI config or a runbook; the fix evaporates if it only lives in one person's shell history.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_wEh1SWGavER0sUXxsxiIQA