raf-leak-check

Fail a test when a requestAnimationFrame callback survives cleanup. The error includes the stack where each pending frame was scheduled.

Try the interactive cleanup lab →

Open in StackBlitz

npm install --save-dev raf-leak-check

React + Vitest example

import { afterEach, beforeEach, test } from "vitest";
import { render } from "@testing-library/react";
import { trackAnimationFrames, type RafLeakCheck } from "raf-leak-check";

let rafCheck: RafLeakCheck;

beforeEach(() => {
  rafCheck = trackAnimationFrames(window);
});

afterEach(() => {
  try {
    rafCheck.assertNoPendingFrames();
  } finally {
    rafCheck.restore();
  }
});

test("stops its animation on unmount", () => {
  const view = render(<AnimatedCanvas />);
  view.unmount();
});

The package is test-runner agnostic. Pass any object that implements requestAnimationFrame and cancelAnimationFrame, including window from a browser or jsdom environment.

API

trackAnimationFrames(target, options?)

Instruments the target and returns:

• pending() — snapshot of callbacks that have not run or been cancelled.
• assertNoPendingFrames() — throws RafLeakError when callbacks remain.
• restore() — restores the original functions; safe to call more than once.

captureStacks defaults to true. Disable it only when measuring very hot test paths:

trackAnimationFrames(window, { captureStacks: false });

Scope

This package tracks only requestAnimationFrame. It does not mock time, execute frames, detect heap retention, or manage animation lifecycles.

License

MIT