Writing Accessibility Use Case Tests with @afixt/usecase-runner

The audit keyword lets you run automated WCAG checks using @afixt/afixt-engine as a step within your use case. This combines the manual interaction testing of the core keywords with automated accessibility auditing in a single workflow.

The audit keyword requires @afixt/afixt-engine (an optional peer dependency):

npm install @afixt/afixt-engine

If the engine is not installed, any audit step will fail with a descriptive error message.

Use audit: page to run WCAG checks against the entire page. This tests every element in the DOM — catching issues like missing landmarks, color contrast failures, unlabeled images, broken heading hierarchy, and missing form labels.

Full-page audits are best placed:

• After navigation — to validate a newly loaded page
• After login or state changes — to test authenticated views
• At each step of a multi-page flow — to ensure every page meets standards

The simplest form audits at WCAG AA (the default level):

- audit: page

To change the WCAG conformance level:

- audit: page level "A" # Level A only (minimum conformance)
- audit: page level "AA" # Level AA (recommended, the default)
- audit: page level "AAA" # Level AAA (strictest conformance)

Example — Audit every page in a multi-step flow:

id: checkout-page-audits
title: 'Audit each page of the checkout flow'
type: positive
start_location: 'https://store.example.com/cart'
expected_result: 'All checkout pages pass WCAG AA'

steps:
  # Audit the cart page
  - verify: heading "Your Cart"
  - audit: page

  # Move to shipping and audit
  - activate: button "Checkout"
  - verify: heading "Shipping Address"
  - audit: page

  # Move to payment and audit
  - activate: button "Continue to Payment"
  - verify: heading "Payment Details"
  - audit: page

  # Move to order review and audit
  - activate: button "Review Order"
  - verify: heading "Order Summary"
  - audit: page

This pattern ensures that every page the user sees during checkout has been tested for accessibility issues, not just the final confirmation page.

You can scope audits to a specific section of the page using the same role tokens as other keywords. Instead of testing the full DOM, the engine only checks the targeted element and its descendants.

Element-scoped audits are ideal for:

• Dynamically loaded content — audit search results, filtered lists, or AJAX-loaded regions after they appear
• Interactive components — audit a dialog, menu, or tab panel after opening it
• Isolating known issues — focus on the section you care about without noise from other parts of the page
• Performance — scoping to a smaller DOM subtree is faster than a full-page audit

- audit: region "Search Results" # A landmark region
- audit: navigation "Main Menu" # A nav landmark
- audit: dialog "Confirm Delete" # A dialog
- audit: region "Checkout Form" level "AAA" # Scoped + custom WCAG level

The runner first locates the element via getByRole() (confirming it exists in the accessibility tree), then derives a CSS selector from it and passes that to the engine as a context scope. Only violations within that element and its descendants are reported.

Example — Audit a dialog after opening it:

id: delete-dialog-audit
title: 'Audit the delete confirmation dialog'
type: positive
start_location: 'https://app.example.com/documents'
expected_result: 'Delete dialog passes WCAG AA'

steps:
  - activate: button "Delete"
  - wait_for: dialog "Confirm Delete"

  # Audit only the dialog — not the page behind it
  - audit: dialog "Confirm Delete"

  - activate: button "Cancel"

Example — Audit dynamic content after interaction:

id: filter-results-audit
title: 'Audit filtered product results'
type: positive
start_location: 'https://store.example.com/products'
expected_result: 'Filtered results region passes WCAG AA'

steps:
  - select: checkbox "In Stock Only"
  - wait_for: region "Product Results"

  # Only audit the results region, which was dynamically updated
  - audit: region "Product Results"

Example — Combine full-page and scoped audits:

A common pattern is to start with a full-page audit for global issues, then use scoped audits for key interactive regions:

id: dashboard-comprehensive-audit
title: 'Comprehensive audit of the dashboard'
type: positive
start_location: 'https://app.example.com/dashboard'
expected_result: 'Dashboard and its key regions pass WCAG AA'

steps:
  - verify: heading "Dashboard"

  # Full-page audit catches global issues (landmarks, skip nav, contrast, etc.)
  - audit: page

  # Scoped audits focus on specific interactive regions
  - audit: navigation "Main Menu"
  - audit: region "Recent Activity"
  - audit: region "Notifications"

This two-level approach is useful when you want broad coverage from the full-page audit but also want to call explicit attention to specific regions — if a scoped audit fails, the report clearly identifies which region has the issue.

Low-priority issues don't fail the test but are recorded in the report so they can be reviewed. Medium and high priority issues cause an immediate failure with full details in the step result.

Place audit steps at key points in your use case — for example, after a page loads or after a dynamic region updates:

steps:
  # Navigate and verify page loaded
  - activate: link "Products"
  - verify: heading "Our Products" level 1

  # Run a full-page audit after navigation
  - audit: page

  # Interact with search
  - enter: field "Search" value "wireless headphones"
  - activate: button "Search"
  - wait_for: region "Search Results"

  # Audit just the results region
  - audit: region "Search Results"

When an audit step produces issues, the report includes full details:

• JSON report: Each step entry includes an audit_result object with total_issues, high, medium, low counts, and an issues array with test_id, check_title, priority, wcag_criteria, element_snippet, and remediation.
• HTML report: Failed or conditional audit steps include an expandable details section listing each issue with its priority, WCAG criteria, element snippet, and remediation advice.