What can a component test not prove when its host is a simulated document rather than a real browser engine?

## What a simulated host actually is A simulated document is an implementation of the document APIs written to run inside the test process. It holds a tree of nodes, supports creating and moving them, dispatches events with realistic propagation, tracks attributes and properties, and models enough of the accessibility-relevant structure that role- and name-based queries work. It boots in milliseconds and has no window on screen. That covers what most component tests are about: given these inputs, does the tree contain the right things, and does interacting with it produce the right changes. The gap is narrower than people fear — and sharper than they expect. ## Where the gap is | Capability | Simulated document | Real engine | | --- | --- | --- | | Tree structure, attributes, text | modelled | real | | Event dispatch and propagation | modelled | real | | Box sizes and positions | stubbed, typically zero | measured after layout | | Style resolution over the cascade | partial at best | full | | Overflow, clipping, scrolling | absent | real | | Paint, compositing, animation frames | absent | real | | Pointer hit-testing | absent — dispatch goes where you aim it | decided by geometry | | Navigation | recorded, not performed | performed | The consequence is not that visual bugs are missed in some vague sense. It is specific: **every behaviour a component derives from a measurement is untested there.** A component that collapses a toolbar when it is narrower than its contents, a list that decides how many rows fit, a popover that flips side when it would leave the viewport, a control that scrolls the selected option into view — all of them run their measurement branch against zeros. ## Why stubs are worse than errors If a geometry query threw, the test would fail and the author would notice. Instead it answers with zero, and zero is a value: - a guard like *only flip if the box would extend past the edge* never fires, so the default branch is the only branch the test ever sees; - an assertion that a measurement is not negative passes for the wrong reason; - an element with no size is not treated as hidden by most queries, so the test finds things a user could not see. That is the honest formulation of the limitation: the test does not go red, it goes green about something it never checked. A passing suite in a simulated host supports claims about structure, text, state transitions and interaction wiring — and supports no claim at all about layout. ## Where the missing coverage goes A real engine closes the gap because it is the real thing: it lays out, paints, hit-tests and navigates. It is also slower to start, needs a display or a headless mode, adds a process boundary between the test and the tree, and is more sensitive to timing and to environment differences between machines. Those are not reasons to avoid it; they are reasons to keep the number of cases small and chosen. A reasonable division: 1. **Simulated host, high volume** — rendered structure and text, state transitions, interaction wiring, conditional branches that do not depend on measurement. 2. **Real engine, low volume** — geometry-dependent behaviour, scrolling and overflow, focus and pointer interaction that depends on hit-testing, real navigation, and anything about what is actually visible. 3. **Neither** — claims about appearance in a specific browser, which need image comparison rather than assertions, and belong to a different kind of suite entirely. The thing to avoid is the middle failure mode: writing a measurement-dependent assertion in a simulated host, watching it pass, and believing the branch is covered. ## Recognising it in a failure Two signatures come up repeatedly. - A test passes but the feature is visibly broken, and the code near the failure reads a size, a position or a scroll offset. The test exercised the zero path. - A test fails with an inexplicable value — a height of zero where markup clearly implies content. Nothing was laid out; the number is a stub, not a defect in the component. In both cases the fix is not to make the simulated host lie more convincingly by stubbing measurements with plausible numbers. Hand-fed geometry proves only that the component does what you told it to do with the numbers you invented. Either move the case to a real engine, or restructure the component so the interesting decision is a pure function of a measurement it receives, and test that function directly with values you choose deliberately. ## The summary a reviewer wants A simulated host is the right default because it is fast and covers most of what component tests assert. Be explicit about its edge, treat a measurement in that host as an invented number rather than an observation, and keep a small, deliberate real-engine suite for the behaviour that only geometry can decide.