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

- **Canonical URL:** https://frontend.rocks/autopsies/green-ci-broken-prod-jsdom/
- **Case:** #07
- **Failure Mode:** False-Positive CI
- **Production Symptom:** 100% of unit and component tests pass in CI while the mobile navigation dropdown is completely unclickable in production.
- **Last Verified:** 2026-11-16

## Causal Chain
1. [Render Tree & Layout](https://frontend.rocks/concepts/render-tree-layout.md): An unclosed transparent sticky header overlay covers the dropdown trigger in the real CSS box tree.
2. [Passive Event Listeners and Compositor Scrolling](https://frontend.rocks/concepts/passive-event-listeners.md): A non-passive touchstart handler and touch-action conflict swallow mobile tap gestures before click synthesis.
3. [Simulated DOM (JSDOM/HappyDOM) vs Real Browser Engines](https://frontend.rocks/concepts/simulated-dom-vs-real-engines.md): JSDOM skips CSS layout, stacking-context hit-testing, and compositor touch routing, passing synthetic clicks directly.
4. [Async Determinism, Fake Timers & Microtask Draining](https://frontend.rocks/concepts/async-determinism-fake-timers.md): vi.useFakeTimers() advances animation delays synchronously, masking a 300ms transition race that hides the menu.
5. [Accessibility-Tree Queries vs DOM Implementation Coupling](https://frontend.rocks/concepts/a11y-tree-queries-vs-dom-selectors.md): Tests query internal class names instead of ARIA roles, leaving aria-expanded and focus traps unverified.

## Primary Sources
- https://playwright.dev/docs/actionability
- https://dom.spec.whatwg.org/
- https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#passive

---
## Incident Report

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:00**: Header 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:00**: Mobile bounce rate climbs 38% across iOS Safari and Android Chrome.
- **T+32:00**: Manual device debugging reveals a transparent `.promo-banner-backdrop` covering `.nav-trigger` and a non-passive `touchstart` listener swallowing taps.

## The Red Herring

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

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 Simulator

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.

## Layer Dissection

### 01 → 02: Layout Occlusion Meets Touch Routing

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

- **Layout occlusion**: Blink's [Render Tree & Layout](/concepts/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](/concepts/passive-event-listeners) `touchstart` handler calls `preventDefault()`, stalling mobile tap-to-click synthesis.

### 02 → 03: Why JSDOM Never Sees the Collision

[Simulated DOM (JSDOM/HappyDOM) vs Real Browser Engines](/concepts/simulated-dom-vs-real-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](/concepts/async-determinism-fake-timers) 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](/concepts/a11y-tree-queries-vs-dom-selectors). 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.
