Testing Observers in JSDOM & Real Browsers

Observer code is unusually easy to write and unusually hard to test, because the thing that makes it valuable — that the browser computes geometry for you — is exactly what a Node-based test runner cannot provide. This page sets out where the boundary sits: what a mock can honestly prove, what it can only pretend to prove, and which assertions have to move into a real browser to mean anything.

Concept Framing

Every test suite that touches IntersectionObserver or ResizeObserver under JSDOM hits the same wall on the first run: ReferenceError: IntersectionObserver is not defined. The instinct is to treat this as a gap in JSDOM. It is better understood as an honest refusal.

JSDOM implements the DOM: a tree of nodes, attributes, events and a CSS object model. What it deliberately does not implement is layout. No element has a box, nothing has a position, nothing scrolls and nothing paints. getBoundingClientRect() returns zeros for everything. Since an intersection ratio is defined as the overlap between two rectangles, and both rectangles are always zero, the only implementation JSDOM could ship would return fabricated numbers that agree with nothing.

That has a direct consequence for how you should structure tests. Observer-driven features split cleanly into two halves:

• The reaction. Given an entry that says the element is 60% visible, does the component add the class, start the fetch, record the impression, unobserve the target? This half is pure logic and belongs in fast unit tests.
• The trigger. Given a real page and a real scroll, does an entry saying 60% actually arrive at the right moment? This half is geometry and belongs in a browser.

Mocking is how you test the first half honestly. It becomes dishonest the moment a mock starts asserting things about the second half — which is why a test that stubs getBoundingClientRect to return plausible numbers and then checks a threshold calculation is testing arithmetic you wrote, in a world you invented.

Spec / Signature Reference Table

A mock is only useful if it reproduces the parts of the contract your code actually depends on. These are the members worth implementing, and the behaviour each must have.

The two easiest details to get wrong are thresholds and the initial delivery. The real constructor normalises threshold: 0.5 into thresholds: [0.5], and code that reads observer.thresholds.length will behave differently against a mock that stores the raw option. And a ResizeObserver mock that only fires when a test asks it to will hide a whole class of bug in components that rely on the guaranteed first measurement.

Step-by-Step Implementation

1. Install the constructor before any module is imported

The error happens at module evaluation time, so the stub must be in place before the module under test loads. In Vitest that means a setupFiles entry; in Jest, setupFilesAfterEnv.

// test/setup-observers.ts — loaded via setupFiles, before any import under test
type IOCallback = (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void;

class MockIntersectionObserver implements IntersectionObserver {
  static instances: MockIntersectionObserver[] = [];

  readonly root: Element | Document | null;
  readonly rootMargin: string;
  readonly thresholds: ReadonlyArray<number>;
  readonly targets = new Set<Element>();

  private queued: IntersectionObserverEntry[] = [];

  constructor(private cb: IOCallback, opts: IntersectionObserverInit = {}) {
    this.root = opts.root ?? null;
    this.rootMargin = opts.rootMargin ?? '0px';
    this.thresholds = Array.isArray(opts.threshold)
      ? [...opts.threshold].sort((a, b) => a - b)
      : [opts.threshold ?? 0];
    MockIntersectionObserver.instances.push(this);
  }

  observe(el: Element): void {
    this.targets.add(el);
    // the real API never fires synchronously — neither do we
    queueMicrotask(() => {
      if (this.targets.has(el)) this.deliver([makeEntry(el, { isIntersecting: false, ratio: 0 })]);
    });
  }

  unobserve(el: Element): void { this.targets.delete(el); }
  disconnect(): void { this.targets.clear(); }
  takeRecords(): IntersectionObserverEntry[] { const q = this.queued; this.queued = []; return q; }

  /** Test-facing: deliver a synthetic entry for a target this instance is watching. */
  trigger(el: Element, init: { isIntersecting: boolean; ratio?: number }): void {
    if (!this.targets.has(el)) throw new Error('trigger() called for an element that is not observed');
    this.deliver([makeEntry(el, { isIntersecting: init.isIntersecting, ratio: init.ratio ?? (init.isIntersecting ? 1 : 0) })]);
  }

  private deliver(entries: IntersectionObserverEntry[]): void { this.cb(entries, this); }
}

globalThis.IntersectionObserver = MockIntersectionObserver as unknown as typeof IntersectionObserver;

The instances array is what lets a test reach the observer a component created internally, without the component having to expose it.

2. Build entries that look like the real thing

A component that reads entry.intersectionRatio or entry.boundingClientRect will crash against a half-built entry, and a test that only sets isIntersecting will not catch that. Build the full shape once:

function makeEntry(
  target: Element,
  { isIntersecting, ratio }: { isIntersecting: boolean; ratio: number },
): IntersectionObserverEntry {
  const rect = target.getBoundingClientRect(); // all zeros under JSDOM — that is fine and honest
  return {
    target,
    isIntersecting,
    intersectionRatio: ratio,
    time: 0,                       // deterministic: never Date.now() in a test double
    boundingClientRect: rect,
    intersectionRect: rect,
    rootBounds: null,
  } as IntersectionObserverEntry;
}

Note the zeros. Resist the urge to fill them with plausible numbers: a test that asserts against invented geometry is the exact failure mode this page is about.

3. Give the suite a flush helper

Because delivery is asynchronous, every test needs one await between the action and the assertion.

export const flushObservers = () => new Promise<void>((r) => queueMicrotask(() => r()));

export function lastObserver(): MockIntersectionObserver {
  const list = MockIntersectionObserver.instances;
  if (!list.length) throw new Error('no IntersectionObserver was constructed');
  return list[list.length - 1];
}

// reset between tests, or instances leak across the file
afterEach(() => { MockIntersectionObserver.instances.length = 0; });

4. Write the test against behaviour

it('swaps data-src into src once the image is in view', async () => {
  const { container } = render(<LazyImage dataSrc="/hero.jpg" alt="" />);
  const img = container.querySelector('img')!;

  await flushObservers();                       // initial, non-intersecting delivery
  expect(img.getAttribute('src')).toBeNull();   // still deferred

  lastObserver().trigger(img, { isIntersecting: true, ratio: 1 });
  await flushObservers();

  expect(img.getAttribute('src')).toBe('/hero.jpg');
  expect(lastObserver().targets.has(img)).toBe(false);  // unobserved after loading
});

Every assertion here is about what the component did. None of them mentions how it was configured.

Configuration Variants

Different runners need the stub installed in different places, and a few need extra care.

One variant deserves a warning. Some teams install the stub globally and then, in browser-based tests, forget to remove it — so the suite that was supposed to exercise the real API quietly exercises the mock. Keep the setup file scoped to the JSDOM project in your runner configuration, and add one assertion at the top of the browser suite that IntersectionObserver.toString() contains [native code].

Edge Cases & Gotchas

A component that constructs its observer lazily. If the observer is only created on first interaction, lastObserver() throws in a test that never interacts. Prefer a helper that waits: poll instances.length across a microtask or two before failing, and make the error message say what was expected.

Multiple observers on one page. A component that uses one observer for lazy loading and another for impressions gives you two instances, and lastObserver() returns whichever was constructed second. Select by options instead — find the instance whose rootMargin matches — or expose a find(pred) helper.

Strict Mode double-invocation. Under React Strict Mode in development, effects run twice, so two instances appear for a single mount. That is not a bug, and a test that asserts instances.length === 1 will fail for the wrong reason. Assert on the last instance and on teardown behaviour instead, as covered in fixing doubled observer callbacks in React Strict Mode.

takeRecords() in teardown paths. Code that drains pending records before disconnecting will call takeRecords() on the mock. If the mock returns undefined, the teardown throws inside a cleanup function, and the resulting error is reported against an unrelated test. Always return an array.

Timers plus observers. A dwell-timer impression test needs both fake timers and an observer flush, and the order matters: trigger the entry, flush microtasks so the callback runs and starts the timer, then advance the fake clock. Advancing the clock first does nothing, because the timer does not exist yet.

JSDOM's getBoundingClientRect is not patchable per element by default. Libraries that stub it globally affect every element in the document for the rest of the file. If a test needs one element to report a size, stub that element's own method and restore it in afterEach.

Framework Integration Patterns

React Testing Library. Render, flush, trigger, flush, assert. The double flush is not superstition: the first lets the initial delivery land, the second lets the state update from the triggered entry commit.

render(<RevealOnScroll>content</RevealOnScroll>);
await flushObservers();
act(() => lastObserver().trigger(screen.getByTestId('panel'), { isIntersecting: true }));
await flushObservers();
expect(screen.getByTestId('panel')).toHaveClass('is-visible');

Vue Test Utils. The composable pattern described in Vue observer composables makes this easier, because the composable can be tested directly with a plain element and no component wrapper. Mount only when you are testing the template binding.

Angular TestBed. Directives that use NgZone.runOutsideAngular need fakeAsync plus a tick() for the microtask, and a fixture.detectChanges() afterwards, because the re-entry into the zone is what normally triggers change detection.

Testing the teardown, in every framework. This is the assertion most suites lack and the bug most likely to reach production:

it('disconnects when the component unmounts', async () => {
  const { unmount } = render(<RevealOnScroll>content</RevealOnScroll>);
  await flushObservers();
  const observer = lastObserver();
  expect(observer.targets.size).toBe(1);

  unmount();
  expect(observer.targets.size).toBe(0);   // disconnect() cleared the set
});

Debugging Checklist

• IntersectionObserver is not defined still throws. The setup file is loading after the module under test. In Vitest, confirm the path is in test.setupFiles and not test.globalSetup — the latter runs in a separate context that does not share globals.
• The callback never runs. Either observe() was never reached (log inside the mock's observe), or the test asserted before the microtask flushed. Add the missing await.
• The callback runs twice. Expected under React Strict Mode. If not in Strict Mode, the component is creating a new observer per render — see why an inline options object rebuilds the observer.
• A test passes alone and fails in the suite. Instances are leaking between files. Clear the static array in afterEach, and make sure the array lives on the mock class rather than in module scope shared across workers.
• The assertion depends on a number you invented. Move that test into the browser layer. This is not a debugging step so much as a design correction, but it is the most common root cause of an observer test that is green and wrong.
• toString() on the constructor does not say [native code] in your browser suite. The JSDOM setup file is being applied to the browser project too.

FAQ

Related

• Mocking IntersectionObserver in Jest and Vitest — the complete reusable mock, with teardown
• Simulating Viewport Intersection in Unit Tests — driving ratios and thresholds without a layout engine
• Testing ResizeObserver Callbacks with Playwright — the browser half, where box sizes are real
• Debugging Flaky Observer Tests in CI — why a suite that is green locally goes red on a slower machine
• Observer Lifecycle & Memory Management — the teardown contract these tests exist to protect

↑ Back to Core Observer Fundamentals & Browser APIs