Architecture Autopsies
Case #07False-Positive CI7 min read

Autopsy #07: Green CI, Broken Prod: What JSDOM Hid From Your Tests

Production Symptom

100% of unit and component tests pass in CI while the mobile navigation dropdown is completely unclickable in production.

The Incident & The False Culprit

A routine header refactor adjusted the mobile promo banner wrapper and added a touchstart scroll lock for the navigation drawer. All 412 Vitest + JSDOM tests passed in 11 seconds on CI.

Twenty minutes after deploy, mobile RUM telemetry showed the primary navigation menu completely dead on phones while desktop clicks stayed normal.

  1. T+00:00Header refactor ships to production after 100% green CI.
  2. T+10:00`nav_dropdown_open` events drop from 14,200/hr to 0/hr on viewports `< 768 px`.
  3. T+20:00Mobile bounce rate climbs 38% across iOS Safari and Android Chrome.
  4. T+32:00Manual device debugging reveals a transparent `.promo-banner-backdrop` covering `.nav-trigger` and a non-passive `touchstart` listener swallowing taps.
REJECTED PATCH

The Red Herring — Why the First Reflex Failed

The first Slack reflex was to bump .dropdown-menu to z-index: 9999 and re-run the Vitest suite. CI stayed green in 11 seconds, and the team merged the hotfix.

Production remained 100% broken on mobile. JSDOM does not run CSS layout or hit-testing, so it never detected that the trigger button itself was occluded by .promo-banner-backdrop, nor that touchstart called preventDefault() before tap-to-click synthesis.

Causal Chain Traversed

Step-by-step propagation across atomic concepts. Hover or click any step to inspect the underlying mechanism.

  1. 01Rendering Pipeline
    Render Tree & Layout

    An unclosed transparent sticky header overlay covers the dropdown trigger in the real CSS box tree.

  2. 02DOM & Events
    Passive Event Listeners and Compositor Scrolling

    A non-passive touchstart handler and touch-action conflict swallow mobile tap gestures before click synthesis.

  3. 03Testing & Verification
    Simulated DOM (JSDOM/HappyDOM) vs Real Browser Engines

    JSDOM skips CSS layout, stacking-context hit-testing, and compositor touch routing, passing synthetic clicks directly.

  4. 04Testing & Verification
    Async Determinism, Fake Timers & Microtask Draining

    vi.useFakeTimers() advances animation delays synchronously, masking a 300ms transition race that hides the menu.

  5. 05Testing & Verification
    Accessibility-Tree Queries vs DOM Implementation Coupling

    Tests query internal class names instead of ARIA roles, leaving aria-expanded and focus traps unverified.

The failure survives CI because five verification layers decouple in sequence:

  1. A sticky layout overlay occludes the trigger in production.
  2. A non-passive touchstart listener drops mobile tap synthesis.
  3. JSDOM skips CSS geometry, stacking contexts, and hit-testing.
  4. Fake timers erase a 250 ms transition race.
  5. CSS class selectors pass even when the accessibility tree is inert.

Failure Reproduction Lab

Use the comparator below to inspect why the JSDOM test reports a false positive while the Playwright Chromium test fails immediately on actionability hit-testing.

Interactive Simulator

CI Fidelity: JSDOM Synthetic Clicks vs Real Browser Hit-Testing

Compare a green JSDOM test that bypasses layout and touch listeners against a real Chromium Playwright test that catches the unclickable mobile dropdown.

Lines of Code
Before
6
After
6
Reflows / Browser Cost
Before
0 layout / 0 hit-test
After
Full Blink layout + hit-test
BeforeJSDOM + Enzyme/RTL Synthetic Test (False Green)
vi.useFakeTimers();
const { container } = render(<MobileNavDropdown />);
fireEvent.click(container.querySelector('.nav-trigger')!);
// JSDOM ignores zero-rect box geometry, passive touchstart,
// and pointer-events: none overlays — passes in 14ms
expect(container.querySelector('.dropdown-menu')).toBeTruthy();
Lines: 6Reflows: 0 layout / 0 hit-testDependencies: JSDOM + vi.useFakeTimers()

Passes 100% in CI even when a sticky header overlay intercepts every tap at (x, y) in production.

After (Native)Real Chromium Engine + A11y Locator (Playwright)
await page.setViewportSize({ width: 390, height: 844 });
const trigger = page.getByRole('button', { name: 'Menu' });
await trigger.tap();
// Blink computes box tree, hit-tests stacking context,
// and verifies ARIA expanded state in a real frame
await expect(page.getByRole('menu')).toBeVisible();
Lines: 6Reflows: Full Blink layout + hit-testDependencies: Playwright Chromium

Fails immediately with 'element intercepts pointer events' when the sticky backdrop covers the trigger.

Layer-by-Layer Dissection

01 → 02

Layout Occlusion Meets Touch Routing

At 390x844, two real-engine barriers block the menu trigger:

02 → 03

Why JSDOM Never Sees the Collision

Simulated DOM (JSDOM/HappyDOM) vs Real Browser Engines skips CSS layout and hit-testing entirely:

  • fireEvent.click(trigger) dispatches a synthetic MouseEvent straight to <button>.
  • No getBoundingClientRect() geometry or stacking-context occlusion check runs.
03 → 04

Fake Timers Mask the Transition Race

The dropdown sets hidden after a 250 ms close timer. Using Async Determinism, Fake Timers & Microtask Draining with vi.advanceTimersByTime(300) without draining microtasks hides the race where a stale close timer conceals a reopened menu.

04 → 05

Class Selectors Hide Broken Semantics

Finally, the test asserts container.querySelector('.dropdown-menu') instead of using Accessibility-Tree Queries vs DOM Implementation Coupling. Because .dropdown-menu remained in the DOM with inert and aria-hidden="true", the class selector passed while screen readers and pointer users had no reachable control.

Architectural Fix & Invariants

TS
import { test, expect } from '@playwright/test';

test('mobile nav trigger opens reachable menu on 390px viewport', async ({ page }) => {
  await page.setViewportSize({ width: 390, height: 844 });
  await page.goto('/');

  const trigger = page.getByRole('button', { name: 'Navigation menu' });
  await expect(trigger).toBeVisible();
  await trigger.tap();

  const menu = page.getByRole('menu', { name: 'Primary navigation' });
  await expect(menu).toBeVisible();
  await expect(trigger).toHaveAttribute('aria-expanded', 'true');
});

Architectural Invariants:

  • No layout or pointer claims in JSDOM: Restrict JSDOM tests to pure state reducers and markup structure, never hit-testing, occlusion, z-index, or touch gesture synthesis.
  • Role-based locators only: Assert getByRole and aria-expanded visibility in a real browser engine rather than .className DOM presence.
  • Passive touch defaults: Use CSS overscroll-behavior: contain and touch-action on scroll-lock overlays instead of non-passive touchstart listeners that block compositor tap synthesis.

Golden Rule: JSDOM tests JavaScript DOM APIs, not browser rendering; verify geometry, touch routing, and ARIA actionability in a real browser engine.

Primary Sources

Last verified: 2026-11-16