yukey-testkit
=============

A dependency-free CDP client for driving a page with *trusted* input,
and reading its state between steps.

It exists because synthetic DOM events can't drive real focus traversal:
a `KeyboardEvent` dispatched from JavaScript won't move focus on Tab,
won't type into an input, and won't trigger hover.
Trusted input (`Input.dispatchKeyEvent` and friends over the Chrome DevTools Protocol)
is what a real keyboard and mouse produce, so a test built on it exercises the same paths a user does.
That's the only kind of test that can prove a keyboard-first UI actually works from the keyboard.

Node 22+, using its built-in `WebSocket`.  Nothing else.


What's in it
------------

- `yukey-testkit/cdp`: the `Cdp` class.
  `Cdp.connect(wsUrl)` to a page target; then `key`, `click`, `mouseMove`, `wheel` for trusted input,
  `js(expr)` for state reads, `screenshot()`, and `cmd` for any other protocol method.
- `yukey-testkit/checks`: the `Checks` collector (a PASS/FAIL line protocol with a summary),
  the `Scenario` and `ScenarioContext` shapes a suite runner can share, and `shot` for optional screenshot evidence
  (written only when `YUKEY_E2E_SHOTS_DIR` is set).
- `yukey-testkit/sleep`: a promise-returning sleep for polling loops.

Launching Chrome and serving your page are yours to do; they vary too much per app to belong here.
Yukey's own `packages/e2e/harness.ts` is one worked example (static files on an ephemeral port, a headless Chrome with a throwaway profile).


License
-------

SPDX-License-Identifier: Apache-2.0 OR MIT