Concepts — Testing Library, Browser Automation, and DevTools

Phase 5 · Spec areas §40, §41, §42. Prerequisites: fw-02, bi-04.

1. Why these are one module

All three are instrumentation: making a running system observable, from three angles. Building small versions of each teaches what your tools are actually doing, which is what lets you diagnose them when they lie to you.

2. mini-testing-library (§40)

Build user-centric queries: by role, by accessible name, by label, by visible text.

DOM -> accessibility tree -> testing queries -> user semantics

The lesson is that the accessibility tree is the honest description of your UI. A query by role that cannot find your button is telling you a real thing about real users — the same information, arriving through a channel engineers actually read.

Build order: visible-text query → label association (all the mechanisms: for, wrapping, aria-label, aria-labelledby) → role computation for a subset of elements → accessible-name computation → assertion helpers.

Failure lab: find four ways to make a button that your role query cannot find. Each is a real accessibility bug. Then find a case where your query succeeds and a real screen reader would still fail the user — and say what that means about testing-library-style tests as an accessibility strategy.

3. mini-automation (§41)

A small layer over a browser automation protocol: navigation, selectors, DOM queries, event dispatch, screenshots, network interception, console events, tracing, frames, contexts.

Key insight: synthetic events dispatched from JS are not the same as real input. A dispatchEvent(new MouseEvent('click')) skips hit testing, does not go through the compositor (bi-10), and has isTrusted: false. Automation protocols inject at a lower level for exactly this reason. Demonstrate the difference — it is the clearest possible illustration of why the input path in bi-02 matters.

Connect to the vertical trace: an automated click is a real opportunity to observe OS input → browser → compositor → renderer → handler.

4. mini-devtools (§42)

Instrument your fw-02/fw-05 runtime to display: component tree, render counts, state changes, network requests, performance marks.

The hard part is not the UI — it is instrumenting without changing what you measure. Your observer must not itself cause re-renders, retain components (a bi-04 leak), or add so much overhead that the timings become fiction.

Then study the Chrome DevTools architecture and the DevTools Protocol: DevTools is a client speaking a protocol to the browser, which is why it can run remotely and why the protocol is also what automation uses. That single fact explains the whole design.

4.5 Deep dive: accessible name computation is an algorithm

"Query by accessible name" sounds simple. The computation is a specified algorithm (accname) with a precedence order, and implementing a subset teaches you why so much ARIA advice is wrong.

Roughly, in order:

1. aria-labelledby (follow the ids, recursively)
2. aria-label
3. native host-language labelling — <label for>, wrapping <label>, <caption>, alt, <legend>, title as a last resort
4. subtree text content, if the role permits name-from-content
5. title attribute

Facts that fall out and that matter in real code:

• aria-labelledby beats visible text. An element can display "Submit" and be announced as something else entirely — a common accessibility bug that visual review never catches.
• Name-from-content depends on role. A button takes its name from its contents; a div does not, which is why <div onclick> is invisible to a role query.
• The algorithm recurses, so a labelled element referencing another labelled element resolves through.
• Whitespace normalisation matters; naive string comparison produces flaky tests.

Implementing steps 1–3 for a handful of elements is enough to internalise the precedence, and it makes you notice the bug class immediately: the accessible name and the visible name have diverged.

4.6 Deep dive: synthetic events versus real input

The consequences are concrete and they explain real test failures:

• A synthetic click on an element covered by an overlay still fires, because hit testing was skipped. Your test passes; the user cannot click the button. This is the single most valuable thing to know about testing tools, and it is why Playwright/CDP-based tests catch a class of bug that jsdom-based tests structurally cannot.
• APIs gated on user activation (fullscreen, clipboard write, autoplay with sound, popups) reject synthetic events. This is a deliberate security design, not an inconvenience.
• Automation frameworks inject at the browser level precisely to get real hit testing and real activation.

The testing-strategy consequence: a component test with synthetic events verifies your handler logic. It does not verify the element is reachable, visible, unobstructed, or activatable. Those require real input. Knowing which question each layer answers is the whole of test-strategy design — and "we have 90% coverage" tells you nothing about which.

4.7 Deep dive: DevTools is a protocol client

Chrome DevTools is a web application that speaks the Chrome DevTools Protocol to the browser. It is not privileged internals; it is a client.

That single architectural fact explains everything else:

• Remote debugging works — the client can be anywhere.
• Automation uses the same protocol — Puppeteer and Playwright drive CDP; DevTools and your test runner are peers.
• DevTools can be extended via panels that also speak the protocol.
• Anything DevTools shows you, you can obtain programmatically. Coverage, heap snapshots, traces, layer trees, accessibility trees — all protocol domains.

The last point is the actionable one and it is underused: if DevTools can show it, you can put it in CI. Performance traces, unused-CSS coverage, accessibility trees, and layer counts are all scriptable. Most teams look at these manually once and never again; a Principal engineer wires the important ones into a pipeline.

The instrumentation constraint remains, though: your own devtools layer must not perturb what it measures. Specifically it must not hold strong references to component instances (a bi-04 leak), must not trigger re-renders by writing observable state, and must be cheap enough that the timings remain true. An observability layer that changes the system is producing fiction, and that is worth stating explicitly because it is the failure mode of most home-grown render-count trackers.

5. Principal Engineer Review

1. Testing-library queries by accessible role. Argue this makes tests better and accessibility better. Then give the case where it produces a false sense of security.

2. Synthetic events differ from real input. Enumerate the differences that matter, and give a bug that only real input reveals.

3. Your observability layer changes the thing observed. Give three concrete instances from frontend tooling, and how each is mitigated.

4. DevTools is a protocol client. What does that architecture buy, and what does it cost?

5. You must set an org-wide policy on E2E vs integration tests. Write it in four sentences, including the criterion for choosing.