cypress-axe error timed out waiting for a11y audit

cypress-axe error timed out waiting for a11y audit - how to fix it

TL;DR

Give the audit time or shrink what it chews on: raise the Cypress command timeout for checkA11y, scope the audit to a smaller context, and check the page is not still loading. Axe on a huge DOM inside Cypress's constrained browser can take a minute. One line of why: Cypress default timeouts assume fast commands, and a full-page axe analysis is not a fast command.

The error, verbatim

Error: Timed out retrying after 4000ms: checkA11y did not complete
    at checkA11y (node_modules/cypress-axe/dist/index.js)
    page: /reports/all (12k DOM nodes)

Fix it step by step

Step 1: Reproduce the timeout

npx cypress run --spec cypress/e2e/a11y.cy.js | rg -i 'timed out' | head -5

Expected: The checkA11y timeout repeats on the heavy page.

Step 2: Time a manual axe run

npx @axe-core/cli https://example.com/reports/all --save /dev/null | tail -2

Expected: If the CLI also takes very long, the DOM is the problem, not Cypress.

Step 3: Raise the timeout and scope the audit

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

Expected: Add a timeout option to checkA11y and scope context to the content region.

Step 4: Re-run the spec

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

Expected: Spec completes the audit within the raised timeout.

Step 5: Re-run twice to rule out flakes

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. checkA11y accepts timeout and context options. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

checkA11y timed out

Same error, same fix.

cypress axe audit timeout heavy page

Practitioner phrasing, the DOM is usually huge.

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

Axe analysis time scales with DOM size and rule count, and Cypress wraps checkA11y in its command timeout (default 4 seconds), which a big page blows past. CI runners with throttled CPU stretch it further. The fix has two levers: more time (timeout option) and less work (context scoping, fewer rules). Scoping to the region under test is usually the right call anyway, since the spec is testing a feature, not the whole app shell. 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

• Scope checkA11y context to the feature under test, auditing the whole app in every spec is slow and noisy.
• Run the heavy a11y specs serially, parallel Cypress runners on small CI machines starve the browser.
• If the CLI scan is fast but Cypress times out, the Cypress browser constraints (memory, CPU) are the bottleneck.
• 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_567ll019kzgdwn2hUkD4Zw