cypress-axe failed cannot read properties of undefined

cypress-axe failed cannot read properties of undefined - how to fix it

TL;DR

Find which object is undefined: it is usually cy.get yielding nothing, axe not injected before checkA11y, or a custom command mis-wired. Run the spec headed and read the stack frame. One line of why: cypress-axe is a thin wrapper, and cannot read properties of undefined almost always comes from the test code around it, not from axe itself.

The error, verbatim

TypeError: Cannot read properties of undefined (reading 'run')
    at checkA11y (node_modules/cypress-axe/dist/index.js)
    at Context.eval (cypress/e2e/a11y.cy.js:18:5)

Fix it step by step

Step 1: Reproduce headed to see the stack

npx cypress run --spec cypress/e2e/a11y.cy.js | rg -B2 -A8 'TypeError' | head -30

Expected: The stack shows whether the undefined is the axe object, the subject, or a config.

Step 2: Verify injectAxe ran first

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

Expected: Confirms injectAxe is called before checkA11y in the same test, the classic ordering bug.

Step 3: Check the custom command wiring

rg -n 'checkA11y|injectAxe' cypress/support/commands.js | head -10

Expected: Shows how the commands are registered; a typo here produces the undefined.

Step 4: Fix the ordering and re-run

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

Expected: Spec passes with real violation output or a clean run, no TypeError.

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 and axe-core 4.x. The injectAxe/checkA11y pairing is the API contract. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

cypress-axe cannot read properties undefined reading run

The full error, an ordering or wiring bug in the spec.

checkA11y undefined error

Practitioner phrasing, same triage.

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

Cypress-axe exposes injectAxe (loads axe into the app iframe) and checkA11y (runs it). Calling checkA11y without injectAxe, or in a before hook that runs before cy.visit, leaves the axe handle undefined and produces this TypeError. The other common shape is a custom Cypress command that shadows or mis-registers checkA11y. Axe itself is innocent in nearly every instance of this error. 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

• injectAxe must run after cy.visit in the same test, not in a before hook for a different spec.
• If you use cypress-axe with component testing, the injection target differs, check the docs for the CT pattern.
• Do not catch and swallow this TypeError, it masks a broken harness, not a passing audit.
• 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_tNpJT-02JXPzPcI2SzVqpg