June 22, 2026
TestInspector's accessibility assertions execute axe-core against the rendered page at a specific step in a test run and return any WCAG violations found, grouped by severity level. Adding an accessibility assertion requires inserting one step — no separate tool, no external service, no code. The assertion runs in TestInspector's Selenium-backed browser environment on Chrome, Firefox, Edge, or Safari, against the real rendered page at whatever point in the test flow the step is placed.
Axe-core is an open-source accessibility testing engine maintained by Deque Systems. It inspects the DOM of a rendered web page and evaluates it against a rule set derived from WCAG 2.0 and WCAG 2.1 success criteria. For each rule, axe-core returns one of three results: pass (the rule is satisfied), violation (the rule is not satisfied), or incomplete (the rule could not be evaluated definitively, typically because it requires human judgment). Axe-core does not require visual rendering analysis — it works on the DOM structure, ARIA attributes, color contrast values, and element relationships that determine programmatic accessibility.
TestInspector wraps axe-core as a native assertion step type. When an accessibility assertion step executes, TestInspector runs axe-core against the current page state in the browser instance handling the test, collects all violations, and evaluates them against the severity threshold configured in the step. The step passes if no violations at or above the configured severity level are found. The step fails if one or more violations at or above the threshold are present, with each violation listed in the run report: rule ID, affected element, description of the failure, and WCAG success criterion violated.
Because the assertion runs as a step within a test flow, accessibility checks are not limited to the initial page load. An accessibility assertion placed after a modal opens checks the modal's accessibility in context. An assertion placed after a form validation error triggers checks whether the error messages are accessible. An assertion placed at the end of a multi-step wizard checks the final confirmation screen. This ability to check accessibility at any application state — not just static pages — is the primary practical advantage over running axe-core as a standalone scan outside the test flow.
For context on where accessibility assertions fit within a broader test automation strategy, see Astaqc's test automation services and the complete software testing guide.
Axe-core classifies every violation on a four-level severity scale: critical, serious, moderate, and minor. TestInspector's accessibility assertion step accepts a severity threshold that determines which violations constitute a test failure.
| Severity Level | What It Means | Example Violation |
|---|---|---|
| Critical | Users are completely blocked from accessing the content or completing the action | Image with no alt attribute, button with no accessible name |
| Serious | Users encounter significant barriers that prevent or strongly impede use | Insufficient color contrast on body text, form input missing associated label |
| Moderate | Users experience a meaningful inconvenience but can generally work around the issue | Skipped heading levels, redundant ARIA roles |
| Minor | Low-impact issues that affect a small set of users or are easily worked around | Scrollable region not reachable by keyboard (some contexts), deprecated ARIA attribute |
Setting the threshold to "critical" in a TestInspector accessibility assertion means the step fails only when violations at the critical level are present. Setting it to "serious" means it fails on critical or serious violations. Setting it to "minor" means any violation at any level causes a failure. The right threshold depends on the team's accessibility policy and the maturity of the application under test.
A practical approach for teams introducing accessibility assertions for the first time is to start with a critical-only threshold. This produces a low false-positive rate and surfaces only the issues that most severely affect users. Once critical violations are resolved and the baseline is clean, the threshold can be lowered to serious, then moderate, incrementally building toward full WCAG 2.1 AA compliance. This staged approach prevents the accessibility assertion from immediately failing every test across the suite before the team has the capacity to address all violations.
The run report for a failed accessibility assertion lists each violation individually. Each entry shows the axe-core rule ID (for example, color-contrast, button-name, label), the severity level, the HTML element or elements that triggered the violation, and a link to the corresponding Deque documentation explaining the rule, the impact, and the fix. This allows developers triaging accessibility failures to understand the issue without leaving the TestInspector interface. For teams that need external QA support for accessibility remediation, see Astaqc's software testing services and the manual vs. automated testing guide.
Accessibility assertions are added in the same way as any other assertion step in TestInspector — through the chat interface or the step editor. The chat interface approach involves describing the assertion in natural language ("add an accessibility assertion after the login step at serious severity") and TestInspector generates the step. The step editor approach involves selecting "Accessibility" from the assertion type list, configuring the severity threshold, and inserting the step at the desired position in the test sequence.
Two parameters configure an accessibility assertion step. The first is the severity threshold — critical, serious, moderate, or minor — described above. The second is the scope of the assertion: by default, axe-core evaluates the full page DOM, but the step can be scoped to a specific element using a CSS selector or element reference. Scoping is useful when a test covers a complex page where only one component is the focus of accessibility validation — a form, a modal, a navigation menu — and full-page violations from unrelated parts of the page would create noise.
Placing accessibility assertions effectively in a test requires thinking about which page states are most important to validate. The highest-value placements are:
Adding an accessibility assertion to an existing test that already covers these states is typically a one-step operation per state. The additional execution time per accessibility assertion step is generally 1–3 seconds, depending on DOM complexity, making it practical to include multiple accessibility assertions within a single test without significantly increasing run duration. See Astaqc's manual testing service for guidance on which accessibility scenarios benefit from manual verification alongside automated assertions.
Accessibility assertions become most valuable as part of the regular test execution cycle rather than as one-time scans. TestInspector supports scheduled runs and CI/CD API triggers, both of which can be applied to suites that include accessibility assertions.
Scheduling accessibility assertion tests on a nightly or per-release cadence provides a consistent baseline. Many accessibility regressions are introduced by UI changes — a developer updates a component, the aria-label that was present on the button is dropped, the label association on a form field breaks. These changes are caught by a scheduled accessibility test run against staging that runs after each deployment, the same way a functional regression suite catches behavioral regressions.
CI/CD integration uses TestInspector's API trigger. A test suite that includes accessibility assertions can be triggered from a GitHub Actions workflow, a GitLab CI pipeline, or any CI system that supports HTTP requests. The trigger sends an API call with the suite ID and optional environment parameters; TestInspector executes the suite and returns a run ID. A subsequent polling call or a webhook callback returns the final pass/fail result, which the CI step uses to pass or fail the pipeline stage. This means accessibility regressions can gate deployments — a suite with a critical-level accessibility assertion step will block deployment if a critical WCAG violation is introduced.
The combination of scheduling and CI triggers allows a layered approach: run accessibility tests on every deployment via CI trigger to catch regressions introduced by that deployment, and run the full accessibility suite on a nightly schedule to catch violations introduced by external content updates, third-party widget changes, or browser engine updates that CI-triggered runs might not cover. For complete CI/CD integration guidance, see the guide to outsourcing QA and Astaqc's test automation services.
Axe-core covers the subset of WCAG success criteria that are programmatically determinable from the DOM and rendered page state. This is a significant and useful subset, but it is not the complete set of WCAG requirements. Understanding these limitations informs a realistic accessibility testing strategy that uses automated assertions for what they can reliably detect and manual review for what they cannot.
What automated axe-core assertions cannot fully cover:
The practical implication is that passing all axe-core accessibility assertions at the minor severity threshold does not mean the application meets WCAG 2.1 AA. It means the programmatically detectable subset of WCAG 2.1 AA violations has been addressed. For full WCAG 2.1 AA conformance, automated assertion coverage should be complemented by manual testing with assistive technologies and real users with disabilities. For structured accessibility audit services, see Astaqc's software testing services and the AI in software testing guide for context on how AI-assisted tools fit into comprehensive testing strategies.
Axe-core evaluation adds approximately 1–3 seconds per assertion step, depending on DOM size and complexity. For most web application pages, the overhead is under 2 seconds. A test with five accessibility assertion steps placed at different page states will add roughly 5–15 seconds to the total run time, which is generally acceptable when the assertions are providing meaningful WCAG coverage that would otherwise require a separate tool run.
Yes. TestInspector's accessibility assertion step accepts a CSS selector that limits the axe-core evaluation to a specific element and its descendants. This is useful for component-level accessibility testing — validating that a reusable form component or navigation pattern meets WCAG criteria without including unrelated page elements in the assertion scope.
Axe-core's rule set covers WCAG 2.0 and WCAG 2.1 success criteria that are programmatically determinable. The specific WCAG success criterion for each rule is documented in axe-core's rule documentation and is referenced in the violation output within TestInspector's run reports. WCAG 2.2 criteria are progressively being added to axe-core's rule set as they are published and as the engine is updated.
Axe-core supports a suppression mechanism for known issues that have been triaged and accepted. TestInspector's accessibility assertion step can be configured with rule exclusions that suppress specific rule violations by rule ID. This allows a team to acknowledge a known violation — for example, a third-party embedded widget with a color contrast issue that cannot be changed — without having the assertion gate deployments on an issue the team has already evaluated. Suppressed violations still appear in the run report as informational items, maintaining visibility without blocking the pipeline.
Automated axe-core testing alone is not sufficient to make a defensible WCAG 2.1 AA compliance claim. Studies from accessibility auditing firms indicate that automated tools can detect approximately 30–40% of WCAG violations; the remainder require human judgment, assistive technology testing, and user testing. Automated testing is a necessary component of an accessibility program, but not a complete one. See Astaqc's software testing services for guidance on combining automated and manual accessibility testing.
Yes. Accessibility assertions and visual regression steps are both available as step types within the same test definition. A test can include a visual regression screenshot step immediately followed by an accessibility assertion step at the same page state, capturing both the visual appearance and the programmatic accessibility of the page in a single run. This is particularly useful for testing components after UI changes — the visual regression step confirms appearance did not change unexpectedly, and the accessibility assertion confirms the markup remains accessible after the change. See TestInspector's documentation for the current set of available step types and their configuration options.
June 22, 2026
Sign up to receive and connect to our newsletter
We founded ASTAQC as a tight-knit group of professional Software Testers and software developers.
Subscribe to our Newsletter
