npm run test:axe runs automated accessibility checks using axe-core via Puppeteer.

This is a useful safety net, but there are a couple of known gotchas when running colour contrast checks in a headless browser.

Known gotchas

Pseudo-elements and colour contrast

axe can be conservative when determining an element’s effective background colour if pseudo-elements are involved (for example, decorative ::before / ::after styling). When that happens, the color-contrast rule may be reported as incomplete (needs review) rather than a clear pass/fail.

If you are confident the pseudo-elements are purely decorative and you want axe to evaluate contrast against the underlying background, you can add a test-only CSS override via buildHTML({ extraCss }) in the component’s accessibility.test.js:

/* Example: remove pseudo-elements for this component during tests */
.asp-component *::before,
.asp-component *::after {
  content: none !important;
}

This keeps the production CSS unchanged, but can make headless contrast evaluation more reliable.

1:1 contrast ratios reported as “incomplete”

We’ve observed an axe edge case where color-contrast reports a 1:1 contrast ratio using the equalRatio message key, but classifies it as incomplete rather than a violation.

In practice this means:

• a true WCAG 2.1 AA failure can appear as incomplete (not a hard failure)
• the test output should be treated as “needs review” for these cases

If you need strict enforcement for colour contrast in CI, you may need an additional deterministic check (outside of axe) for those edge cases.

What the output means

• Violations: axe is confident the rule failed.
• Incomplete: axe could not confidently determine pass/fail (needs review).
• Pass: axe is confident the rule passed.

Source

Imported from docs/accessibility-testing.md in asp-frontend.