Autopsy #07: Green CI, Broken Prod: What JSDOM Hid From Your Tests
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.
- T+00:00Header refactor ships to production after 100% green CI.
- T+10:00`nav_dropdown_open` events drop from 14,200/hr to 0/hr on viewports `< 768 px`.
- T+20:00Mobile bounce rate climbs 38% across iOS Safari and Android Chrome.
- T+32:00Manual device debugging reveals a transparent `.promo-banner-backdrop` covering `.nav-trigger` and a non-passive `touchstart` listener swallowing taps.
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.
- 01Rendering PipelineRender Tree & Layout
An unclosed transparent sticky header overlay covers the dropdown trigger in the real CSS box tree.
- 02DOM & EventsPassive Event Listeners and Compositor Scrolling
A non-passive touchstart handler and touch-action conflict swallow mobile tap gestures before click synthesis.
- 03Testing & VerificationSimulated DOM (JSDOM/HappyDOM) vs Real Browser Engines
JSDOM skips CSS layout, stacking-context hit-testing, and compositor touch routing, passing synthetic clicks directly.
- 04Testing & VerificationAsync Determinism, Fake Timers & Microtask Draining
vi.useFakeTimers() advances animation delays synchronously, masking a 300ms transition race that hides the menu.
- 05Testing & VerificationAccessibility-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:
- A sticky layout overlay occludes the trigger in production.
- A non-passive
touchstartlistener drops mobile tap synthesis. - JSDOM skips CSS geometry, stacking contexts, and hit-testing.
- Fake timers erase a 250 ms transition race.
- 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.
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.
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();Passes 100% in CI even when a sticky header overlay intercepts every tap at (x, y) in production.
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();Fails immediately with 'element intercepts pointer events' when the sticky backdrop covers the trigger.
Layer-by-Layer Dissection
Layout Occlusion Meets Touch Routing
At 390x844, two real-engine barriers block the menu trigger:
- Layout occlusion: Blink's Render Tree & Layout places a sticky
.promo-banner-backdrop(pointer-events: auto) directly over.nav-trigger. - Touch swallowing: Even on exposed pixels, a non-passive Passive Event Listeners and Compositor Scrolling
touchstarthandler callspreventDefault(), stalling mobile tap-to-click synthesis.
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 syntheticMouseEventstraight to<button>.- No
getBoundingClientRect()geometry or stacking-context occlusion check runs.
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.
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
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
getByRoleandaria-expandedvisibility in a real browser engine rather than.classNameDOM presence. - Passive touch defaults: Use CSS
overscroll-behavior: containandtouch-actionon scroll-lock overlays instead of non-passivetouchstartlisteners 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