# Interaction Test Harness

## Objective

Test the app the way a person uses it, through real clicks, keys, and focus.

A test setup that drives menus, dialogs, forms, and navigation through genuine user interactions and asserts on what the user can see.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Find elements the way a user finds them — by their visible label, their role, and their accessible name — rather than by class names or internal test hooks, so a test breaks when the interface becomes unusable and not when a wrapper is renamed.
2. Drive each interaction through both pointer and keyboard where both are supported, and assert on where focus ends up as well as on what the screen shows.
3. Assert on the visible outcome and wait for it to appear, rather than sleeping for a fixed interval and hoping. A timer-based wait is either slow on every run or flaky on a loaded machine.
4. Cover interruptions and repeats explicitly: a dialog closed while its request is still in flight, a submit button pressed twice, a menu reopened before its close animation finishes, a navigation triggered mid-save.
5. Rendered appearance is covered by Visual Regression Testing and accessibility rule checking by the Accessibility Test Suite; this brief owns behaviour under interaction. Do not assert on pixel positions or repeat contrast checks here.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Selectors tied to implementation detail pass while the interface is broken and fail while it is fine, so a test that finds a control by its internal identifier is testing the wrong thing entirely.
- A flow that works with a mouse can be unreachable by keyboard, and a suite that only clicks will never notice — every interaction test needs to say whether it exercised pointer, keyboard, or both.
- Fixed sleeps are the main source of flake; the harness must wait for the element or the text the user would wait for, with a bounded timeout that fails loudly rather than silently passing.
- Repeated and interrupted actions are where real defects live — double submits, a dialog dismissed before its response returns, a rapid second click on a control that was meant to disable itself — and none of these appear in a happy-path script.
- Asserting on an element that is in the DOM but visually hidden or covered by an overlay produces a passing test for something the user cannot reach; check visibility, not presence.
- Tests that share state through a common fixture will pass in isolation and fail when run in a different order, so each test must set up and tear down its own data.
- Animations and transitions make elements briefly present but not yet interactive; either disable them under test or wait for the settled state rather than the first appearance.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Tests locate controls by visible text, role, or accessible name, and no test depends on a class name or internal identifier.
- [ ] Each covered flow is exercised by pointer and by keyboard, with focus position asserted at the key transitions.
- [ ] No test contains a fixed sleep; every wait is for a visible outcome with a bounded timeout.
- [ ] Double submission, interruption mid-request, and rapid repeat interactions each have a test.
- [ ] Assertions confirm the element is genuinely visible and reachable, not merely present in the DOM.
- [ ] The suite passes when tests are run in a randomised order.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.