UCDL Accessibility Use Case Definition Language
Document version
1.0.0
Document date
Editors
AFixt Engineering
Reference implementation
@afixt/usecase-runner

Specification

Accessibility Use Case Definition Language (UCDL) and Runner

This specification defines:

  1. A YAML-based document format ("use case document") for describing accessibility test cases in terms of user-visible roles, accessible names, and intent-bearing actions.
  2. A small, keyword-driven domain-specific language ("Step Language") for expressing the steps of a use case in a way that is readable by non-developers and that maps unambiguously to accessibility-aware browser automation.
  3. A processing model that takes one or more use case documents and produces either (a) standalone Playwright .spec.ts files or (b) live execution results, together with a structured report.
  4. A reporting model and scoring rubric that align with AFixt's manual use case testing methodology so that automated and manual results can be compared and aggregated.

Read the specification Start the tutorial

What UCDL is for

  • Fidelity. A use case document SHALL describe a workflow in terms a human tester can follow without a developer's help.
  • Determinism. Two conforming processors SHALL produce equivalent test artifacts from the same input document.
  • Accessibility-first targeting. The DSL SHALL NOT provide CSS or XPath affordances. Targets are identified by role and accessible name.
  • Round-trippability. The same document MUST be executable in either of two modes (codegen or direct execution) without behavioral divergence.
  • Reportable. Results MUST be expressible in the same step/comments rubric used by AFixt for manual use case reports, so that automated and manual results are mergeable.
§1.1 Goals, from the specification

Example

C.1 A positive case

From Appendix C of the specification.

id: login-success
title: 'Log In To The System'
type: positive
description: 'Verify that a user with valid credentials can log in.'

preconditions:
  - 'User has a valid username and password'
  - 'User is not already logged in'

start_location: 'https://www.example.com'
expected_result: 'The user is logged in and redirected to the dashboard'

data:
  username: '[email protected]'
  password: 'xyzpdq123!)'
  dashboard_url: 'https://www.example.com/dashboard'

steps:
  - locate: link "Client Sign In"
  - focus: link "Client Sign In"
  - activate: link "Client Sign In"
  - verify: url "https://www.example.com/login.php"
  - locate: field "username"
  - focus: field "username"
  - enter: field "username" value "{{ username }}"
  - locate: field "password"
  - focus: field "password"
  - enter: field "password" value "{{ password }}"
  - locate: button "Login"
  - focus: button "Login"
  - activate: button "Login"
  - verify: url "{{ dashboard_url }}"