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

Let's write a test for a user registration form. Think about what a real user does:

1. Navigate to the registration page
2. Find the form fields
3. Fill them in
4. Submit the form
5. Verify success

# register-success.uc.yaml

id: register-success
title: 'Register a New Account'
type: positive
description:
  'Verify that a new user can create an account with valid information.'

preconditions:
  - 'User does not already have an account'
  - 'Registration is open'

start_location: 'https://app.example.com'

expected_result:
  'User account is created and user is redirected to the welcome page'

data:
  first_name: 'Jane'
  last_name: 'Doe'
  email: '[email protected]'
  password: 'SecurePass123!'

steps:
  # Step 1: Find and click the registration link
  - locate: link "Create Account"
  - focus: link "Create Account"
  - activate: link "Create Account"

  # Step 2: Verify we landed on the registration page
  - verify: url "/register"
  - verify: heading "Create Your Account" level 1

  # Step 3: Fill in the first name
  - locate: field "First Name"
  - focus: field "First Name"
  - enter: field "First Name" value "{{ first_name }}"

  # Step 4: Fill in the last name
  - locate: field "Last Name"
  - focus: field "Last Name"
  - enter: field "Last Name" value "{{ last_name }}"

  # Step 5: Fill in the email
  - locate: field "Email"
  - focus: field "Email"
  - enter: field "Email" value "{{ email }}"

  # Step 6: Fill in the password
  - locate: field "Password"
  - focus: field "Password"
  - enter: field "Password" value "{{ password }}"

  # Step 7: Agree to terms
  - locate: checkbox "I agree to the Terms of Service"
  - select: checkbox "I agree to the Terms of Service"

  # Step 8: Submit the form
  - locate: button "Create Account"
  - focus: button "Create Account"
  - activate: button "Create Account"

  # Step 9: Verify success
  - verify: url "/welcome"
  - verify: heading "Welcome, Jane!"
  - verify: text "Your account has been created"

Notice the recurring pattern in every interaction:

- locate: button "Submit" # 1. Can the user find it?
- focus: button "Submit" # 2. Can the user reach it with a keyboard?
- activate: button "Submit" # 3. Can the user activate it?

This three-step pattern is the backbone of accessibility use case testing. Each step tests a different layer:

1. locate — Is the element in the accessibility tree with the correct role and name?
2. focus — Is the element keyboard-accessible?
3. activate/enter/select — Does the interaction work?

You don't have to use all three every time (e.g., for a verify step), but for any element the user interacts with, this pattern gives you thorough coverage.