Accessibility Testing

Accessibility Testing

An automated scan finds a minority of accessibility defects, and none of the ones that make a product unusable: focus that disappears, a dialog you cannot leave, a form whose errors are never announced. Those are found by operating the product without a mouse.

This skill is not dropped because nobody asked. It is dropped only when there is no user interface.

1. The target

Take it from the project: a stated policy, a contractual level, a component library's claim, or the regulation the client is subject to. When nothing is stated, work to WCAG 2.2 level AA and say that is what was applied.

Record the target in the report. accessible with no reference means nothing.

2. Order of passes

1  keyboard, the whole critical flow, no mouse at all
2  structure and semantics
3  forms and error handling
4  dynamic content: dialogs, menus, live regions, async updates
5  visual: contrast, zoom, reflow, motion, target size
6  assistive technology, on the critical flow
7  automated scan, last

The scan runs last on purpose. Run first, it anchors the session on the findings a tool can produce and the session stops there.

3. The keyboard pass

The single highest yield activity in this skill. Full sheet in resources/keyboard-pass.md.

Tab through the flow: does focus reach every interactive element
Is the focus indicator visible on every one of them, including custom controls
Does the focus order match the visual order
Can every action be triggered by Enter or Space, as its role implies
Does Escape close what it opened, and return focus to the trigger
Is there a skip link, or another way past a long navigation
Does focus ever leave the page, or land on something invisible
Does focus ever get trapped where it should not be
After an asynchronous update, where does focus go

A control that cannot be reached by Tab is a defect regardless of what a scanner says, and a control with no visible focus is unusable even when it is reachable.

4. Structure and semantics

one main landmark, and content that lives inside landmarks
headings that describe the structure, in order, no level skipped for styling
lists marked up as lists, tables as tables with headers
buttons that are buttons and links that are links, by behaviour and by element
every image: meaningful alternative text, or empty alt when decorative
every control: an accessible name that matches its visible label
language declared on the document, and on any passage in another language
page title unique and descriptive per view

The button and link rule is not pedantry: a link that acts as a button cannot be activated with Space, and a div that acts as a button cannot be activated at all.

5. Forms

every field has a programmatically associated label, not a placeholder
required fields are marked in the accessible name, not only in colour
errors are associated with their field
errors are announced when they appear, not only rendered
focus moves to the first invalid field, or to a summary that links to it
the field keeps its value after a failed submit
instructions and format requirements are available before the error, not after
grouped controls have a group name, radio sets included

6. Dynamic content

dialog          focus moves in, is trapped while open, returns to the trigger
                on close, and the background is inert
menu            opens, is navigable by arrow keys, closes on Escape
tabs            arrow keys move between tabs, the panel is associated
accordion       state is exposed, not implied by an icon
toast or alert  announced through a live region, with a duration a person can
                actually read, and reachable if it carries an action
async update    the user learns that content changed, without a visual scan
infinite scroll there is a keyboard path to what lies beyond the scroll

7. Visual and physical

contrast: text against its actual background, in both themes, including
  disabled states, placeholder text and text over images
information never carried by colour alone
zoom to 200 percent: nothing lost, nothing overlapping
reflow at 320 CSS pixels wide: no horizontal scrolling of the page
line spacing and letter spacing overrides do not clip content
target size adequate for touch, with adequate spacing
motion respects the reduced motion preference, and nothing flashes rapidly
content that moves or auto-advances can be paused

8. Assistive technology

Use one screen reader on the critical flow. Which one is a project decision; the point is that a real one is used at least once.

does the page announce what it is, on arrival
are landmarks and headings usable for navigation
does every control announce its role, name and state
do errors and status messages reach the user
is anything announced twice, or announced as unlabelled
can the whole critical flow be completed

If no screen reader is available in the environment, say so in the report and do not imply the pass happened.

9. Reporting a finding

ID          A11Y-07
Criterion   WCAG 2.2, 2.4.3 Focus Order, level A
Location    /teams/{id}/members, invitation dialog
Barrier     focus returns to the top of the page after the dialog closes
Who         keyboard and screen reader users
Effect      the user must Tab through 24 elements to resume the task
Evidence    keyboard-pass recording, step 14
Fix         return focus to the triggering button on close
Severity    High: the flow is completable but hostile

Severity is about the barrier, not about the effort to fix. Blocking means the task cannot be completed by that user at all.

10. Prohibitions

• Never report an automated scan as an accessibility test.
• Never claim a screen reader pass that was not performed.
• Never accept a positive scan on a page whose controls cannot be reached by Tab.
• Never fix a name or a role only in the test, leaving the interface unchanged.
• Never add ARIA to a native element that already had the semantics.
• Never treat contrast as passing because a design token says so; measure the rendered pair.
• Never reduce a finding to add aria-label when the underlying element is the wrong element.

11. Protocol

1. Establish the target and the pages in scope from the contract.
2. Run the keyboard pass on each critical flow, recording every step.
3. Check structure and semantics on each page in scope.
4. Check forms, including the error path, which is where most defects are.
5. Exercise every dynamic component in the flow.
6. Check contrast, zoom, reflow, motion and target size.
7. Run the assistive technology pass on the critical flow, or record that it could not be run.
8. Run the automated scan last and reconcile it with what was found manually.
9. Map every finding to a criterion, a barrier and a person.
10. Hand the reproducible ones to playwright-automation so they become permanent keyboard and focus tests.

12. Auto-critique

Score from 0 to 5: keyboard pass actually performed on the whole flow, focus management verified on dynamic components, forms and error announcement covered, contrast measured on rendered pairs, reflow and zoom checked, assistive technology used or its absence stated, findings mapped to criteria and to a human consequence.

Threshold: no axis below 3, average at least 4. A campaign whose accessibility evidence is a scanner report scores 0 and is rerun.

13. Interfaces

• Upstream: quality-engineering for the target and the scope, ui-ux-engineering for what the interface was specified to be.
• Lateral: playwright-automation to automate keyboard and focus checks, exploratory-testing for the flows worth checking first.
• Downstream: frontend-engineering for remediation, test-reporting for the findings, technical-documentation for the accessibility statement.