Concepts — Testing Library, Browser Automation, and DevTools

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

0. Orientation

The 60-second version

Testing libraries, browser automation, and DevTools are the same thing from three angles: instrumentation — making a running system observable. Building small versions of each teaches what your tools are actually doing, which is what lets you diagnose them when they lie to you.

Two facts carry the module, and both change how you design a test strategy:

1. A synthetic click and a real click are different operations.

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 CDP-based tests catch a class of bug that jsdom-based tests structurally cannot.

2. DevTools is a protocol client, not privileged internals. It is a web application speaking the Chrome DevTools Protocol to the browser. Everything else follows: remote debugging works, automation uses the same protocol, and — the underused consequence — anything DevTools can show you, you can obtain programmatically and put in CI.

The instrumentation constraint

Your own observability layer must not perturb what it measures. It must not hold strong references to component instances (a fe-02 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 the failure mode of most home-grown render-count trackers.

What you should be able to do after this module

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.

Core terminology

Mental models

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. That is why user-centric queries make tests better and accessibility better, and it is also where the false sense of security lives (see §7).

Accessible name computation is an algorithm with a precedence order, roughly: aria-labelledby (recursively) → aria-label → native labelling (<label for>, wrapping <label>, <caption>, alt, <legend>) → subtree text if the role permits name-from-content → title.

Two consequences that matter in real code: aria-labelledby beats visible text, so an element can display "Submit" and be announced as something else — a bug visual review never catches. And name-from-content depends on role, which is exactly why <div onclick> is invisible to a role query.

Each testing layer answers a different question, and coverage numbers tell you nothing about which.

Knowing which question each layer answers is test-strategy design.

If DevTools can show it, you can put it in CI. Coverage, heap snapshots, traces, layer trees and accessibility trees are all protocol domains. Most teams look at these manually once and never again; wiring the important ones into a pipeline is a high-leverage, low-cost intervention.

An observability layer that changes the system produces fiction. Worth stating explicitly because it is the standard failure of home-grown render-count trackers — which typically retain component instances, trigger the renders they are counting, or cost more than what they measure.

Common misconceptions

1. "A passing click test means the user can click it." A synthetic click skips hit testing, so it fires through an overlay. The test is passing and the button is unclickable.

2. "jsdom is close enough for interaction tests." It has no layout, no compositor, no hit testing, and no user activation. It answers "is my handler correct?" — a genuinely useful question, and not the one people think they are asking.

3. "dispatchEvent is what user-event does." Libraries that drive real dispatch paths produce different microtask interleaving (fe-01) and different form semantics (fe-04's dirty value flag) from fireEvent. Both findings say the harness is what is wrong.

4. "APIs rejecting synthetic events are being awkward." User activation gating is a deliberate security design: it stops a page opening popups, going fullscreen, or writing to the clipboard without the user having acted.

5. "90% coverage means we're well tested." It reports lines executed, not questions answered. Which layer covered them is the only interesting part.

6. "Testing-library queries make the app accessible." They verify the tree has a role and a name. A real screen-reader user can still be blocked by focus order, live-region behaviour, or an announcement that is technically present and useless.

7. "DevTools has privileged access." It is a client speaking a protocol. That single fact explains remote debugging, extension panels, and why Playwright and DevTools are peers.

8. "Our render tracker is lightweight." Check that it does not retain instances, does not write observable state, and does not dominate the timings. Most fail at least one.

Interview talking points

• "The most valuable thing I know about testing tools is that a synthetic click skips hit testing. A dispatchEvent click on a button covered by an overlay still fires — so the test passes and the user can't click it. That's a class of bug jsdom-based tests structurally cannot catch, and it's the whole argument for having some real-input tests."
• "I don't design test strategy around a coverage number, I design it around which question each layer answers. Component tests with synthetic events verify handler logic. They don't verify the element is reachable, visible, unobstructed or activatable — that needs real input. Coverage tells you nothing about which of those you have."
• "The accessibility tree is the honest description of the UI, so a role query that can't find your button is a real finding, not a test problem. But I'd flag the limit too: the tree having a role and a name doesn't mean a screen-reader user can complete the task."
• "Accessible name computation is a specified algorithm with a precedence order, and the thing that bites is that aria-labelledby beats visible text. An element can display 'Submit' and be announced as something else — voice-control users say the visible label and nothing happens, and visual review never catches it."
• "DevTools is a protocol client, not privileged internals, and the underused consequence is that anything it can show you is scriptable. Coverage, traces, layer counts, accessibility trees — most teams look at those manually once. Wiring the important ones into CI is cheap and high-leverage."
• "Any observability layer you build has to not perturb what it measures — no strong references to component instances, no writing observable state, and cheap enough that the timings stay true. Most home-grown render-count trackers fail at least one of those, and then they're producing fiction."

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.

Connections to other modules

• fw-02 / fw-05 — the runtimes you instrument; render counts and component trees only mean something against an implementation you understand.
• fw-11 — reading production source and instrumenting a running system are the same skill from two directions.
• bi-02 — the input path: why automation protocols inject at the browser level rather than dispatching from script.
• bi-09 / bi-10 — hit testing and the compositor, the two things synthetic events skip.
• bi-04 — the retainer-chain skill your devtools layer must not violate.
• fe-01 — real vs synthetic dispatch produces different microtask interleaving; same finding, measured from outside.
• fe-04 — the dirty value flag: a second case where a synthetic interaction has different semantics and the test passes while the form rejects the input.
• fe-24 — the limits of automated accessibility checking, which this module makes concrete.