testing

This is the canonical testing guide for @react-three/fiber. It is the single source of truth for how we test — for both human contributors and coding agents. If you are adding a test, fixing CI, or planning coverage work, start here.

pnpm test            # Tier 1: unit + mock suite with coverage (what CI runs)
pnpm test:watch      # Tier 1: watch mode, no coverage
pnpm test:gpu        # Tier 3: real WebGPU device, headless (needs Vulkan on Linux, see below)
pnpm run ci          # Full local gate: build → verify → typecheck → eslint → test → format

If you only remember one rule: a green pnpm test does not prove the WebGPU runtime works — pnpm test:gpu proves the part of it that runs headless, and Tier 2 the rest.

R3F spans pure JS, React reconciliation, and a GPU runtime that jsdom cannot execute. One test runner can't cover all of that, so we split by what each tier can actually prove.

The remaining CI gap: per-PR CI now guards the mock + pure-JS layer (Tier 1) and what a root draws on a real device (Tier 3). What needs a browser (<Canvas>, DOM events, Vite HMR) or a hardware GPU's behaviour is still caught at the Tier-2 pre-release gate, not on the PR that introduces it.

Design principle — push work down a tier. The cheapest, most reliable test is a Tier-1 test. Before writing a GPU test, ask: can this run against the WebGPUContext mock instead? Lifecycle, wiring, store resolution, and rebuild logic usually can. Genuinely GPU-dependent behavior (does it actually render? is the depth correct?) goes to Tier 3 if it can run on createRoot without a DOM, and to Tier 2 only if it cannot.

This is the suite you run constantly and the one CI blocks on. It runs against source files (not dist) via the aliases in vitest.config.ts, in a jsdom environment, with v8 coverage.

pnpm test                                         # full run + coverage (CI parity)
pnpm test:watch                                   # watch mode, no coverage
pnpm vitest packages/fiber/tests/events.test.tsx  # single file
pnpm vitest -t "interactivePriority"              # by test name

The frame scheduler is an external dependency (@pmndrs/scheduler) as of alpha.3 — its internals (phase graph, topo sort, fps rate limiter) are unit-tested upstream, not here. This repo tests the integration: that useFrame drives the scheduler correctly (phase ordering, render-phase takeover, fps throttling end-to-end, pause/resume). Don't re-test scheduler internals in R3F.

Anything that needs a real GPU device: actual rendering, node-material compilation, render-pipeline output, occlusion queries, real TSL HMR. Those are Tier 3 (headless) or Tier 2 (browser). Don't fake a passing assertion for them in jsdom — write the Tier-3 test, or leave an it.todo pointing at the Tier-2 check.

jsdom has no WebGL or WebGPU. We stub them so Tier 1 can run:

The WebGPUContext mock is the single biggest lever for CI coverage. Every behavior we can drive against it is a behavior that moves from "Tier-2 browser-only" into "Tier-1, guarded on every PR." Investing in the mock is preferred over deferring a hook to browser-only validation. Document clearly, in the test, which paths are mock-validated vs which still require Tier 2.

Status: strategy decided, harness not yet built (planned pnpm test:browser). Part of the checklist below now runs headless on every PR in Tier 3; the rest still needs a browser.

WebGPU is a first-class, baseline path in v10 — not an exotic add-on. The stable WebGPU surface ships in 10.0, so it must be validated against a real device before each release. Tier 2 is that gate.

Non-headless Playwright (headless: false, Chromium with WebGPU enabled) drives the example app on a machine with a real GPU + display. It is scripted and repeatable — it replaces ad-hoc "I clicked around and it looked fine" browser checks.

It is not a per-PR CI gate (it needs a physical GPU + display). Treat it as a pre-release gate: run it during a release pass and before each promotion (alpha → beta → RC → stable).

These are the real-GPU behaviors no jsdom/mock test can reach. Each should become a scripted Playwright check against the example app. Tier 3 notes say which part already runs headless on createRoot; the browser check still owes the <Canvas> half.

pnpm test:browser    # run the Playwright/WebGPU suite against the example app (planned)

Proposed layout: a separate Playwright project (e.g. e2e/ or packages/fiber/e2e/) with *.gpu.spec.ts files and its own config — kept out of the Vitest include glob so it never runs accidentally in jsdom CI. Until then, the checklist above is run manually on a GPU box.

R3F against a real WebGPU device, with no browser and no physical GPU. vitest-environment-webgpu-node backs navigator.gpu with Google's Dawn in the Node process and provides a headless canvas whose webgpu context renders into a real texture; the tests read that texture back. It runs on every PR as the Headless WebGPU tests job in .github/workflows/test.yml.

pnpm test:gpu                                           # the whole Tier-3 project
pnpm test:gpu packages/fiber/tests/gpu/render.gpu.test.tsx  # one file
UPDATE_SCREENSHOTS=1 pnpm test:gpu                      # rewrite screenshot baselines (see below)

It needs Node 22+ (the repo's version). The suite takes a few seconds.

vitest-screenshot adds await expect(canvas).toMatchScreenshot('name.png', options). Baselines are PNGs in __screenshots__/ beside the test, and they are committed.

Prefer pixel assertions (expectColor) for behaviour; keep screenshots for "does the whole picture still look right".

The local full gate and the CI workflow must run the same checks in the same way, or they drift and "passes locally" stops meaning anything.

CI runs verify-treeshake and verify-types right after the build, matching the local order.

Rule for new checks: if you add a verification step, add it to both the ci script and the workflow — or, better, add it to the shared script the workflow calls.

The one exception is pnpm test:gpu: it is a separate CI job and stays out of pnpm run ci, because it needs a Vulkan driver (Linux) that not every contributor machine has. Run it yourself when you touch rendering, the renderer lifecycle or multi-canvas.

Coverage uses the v8 provider; reporters are text, text-summary, json, and html (configured in vitest.config.ts). Open coverage/index.html after pnpm test for the line-by-line view.

pnpm test runs with --coverage, and vitest.config.ts sets global coverage.thresholds (lines, functions, statements, branches). If any total falls below its threshold the run fails, so CI fails on a coverage drop.

The thresholds are a ratchet, not a target: each sits just under what the suite currently achieves, measured on the lower of the CI React legs (19.0.0 reads slightly below latest) and floored with ~0.5–1% headroom so neither leg flakes. When coverage goes up, raise them; never lower one to make a build pass. lines is the meaningful figure for R3F's own code — statements/branches read low because v8 also counts the bundled three.js code the suite touches.

The per-area targets below are not enforced by config; treat them as expectations, not gates.

These are the v10-changed surfaces with little or no dedicated coverage — the highest return per test:

Any per-file coverage numbers quoted in docs are point-in-time snapshots — re-run pnpm test for current numbers; don't trust a table after the code moves.

Separate from the test suite: these check the built dist, not source. What matters is what an app downloads, and that depends on transitive imports, chunk assignment and the bundler -- none of which a grep over dist can see. So verify-treeshake writes small consumer apps, bundles each with Vite (Rollup) and with esbuild, and checks the output.

pnpm build && pnpm verify-treeshake   # consumer bundles carry exactly the expected renderer(s)
pnpm verify-types                     # per-entry declarations: ThreeExports, JSX augmentation, hygiene, consumers
pnpm analyze-fiber                    # dry-run @react-three/fiber package contents
pnpm analyze-test                     # dry-run @react-three/test-renderer package contents

What verify-treeshake checks, per bundler:

R3F_TREESHAKE_DUMP=1 keeps every case's output under node_modules/.cache/r3f-verify-treeshake; R3F_TREESHAKE_VERBOSE=1 prints every check.

These belong in CI as well as locally — see the parity note above.

Changes not showing? Run pnpm stub to regenerate the dist/ → src/ development links.

Import errors in the IDE? Restart the TypeScript server or run pnpm typecheck.

"EPERM" / symlink errors on Windows? Enable Developer Mode for symlink support.

"Multiple instances of Three.js" warning? Common in Vitest/jsdom — safe to ignore; common variants are suppressed in setupTests.ts.

"Cannot find module" errors? Ensure pnpm install ran; if the error references dist, run pnpm stub.

verify-treeshake fails? You must pnpm build first (pnpm install re-stubs dist). A renderer in the eager output means something in src/core/ imports a value from three/three/webgpu, or a module that does (a three addon) is imported statically; see BUILD.md.

A test on the root entry fails inside three's WebGL backend? The root entry renders with WebGPURenderer, which in jsdom runs its WebGL2 fallback backend against the WebGL mock. setupTests.ts stubs what that backend needs and jsdom lacks (ImageBitmap; the mock's getSupportedExtensions), so a frame can render. Tests that exercise core behaviour (events, visibility, sizing, Suspense) rather than the renderer still import Canvas / createRoot from ../src/legacy, which renders through the WebGL mock directly; that keeps them independent of the WebGPU backend. Tests of WebGPU behaviour mock the renderer (see renderer-lifecycle.test.tsx) or use frameloop: 'never'.

Tests rendering on the root entry time out or find scene null? The root entry loads a renderer support with a dynamic import. setupTests.ts imports both supports so that import is cached and resolves inside act(); a test that builds a bare store with createStore must registerThree(...) itself (see webgpu/useRenderTarget.test.tsx).

pnpm test:gpu fails with no adapter, or navigator.gpu.requestAdapter() returns null? Dawn found no Vulkan driver. On Linux install mesa-vulkan-drivers (lavapipe); check /usr/share/vulkan/icd.d/ lists lvp_icd.json.

A Tier-3 test logs a WGSL error (... is a reserved keyword) and reads back transparent pixels? The shader failed to compile on the device; the jsdom mock never compiles shaders, so only Tier 3 sees this. A uniform's name becomes its WGSL identifier, so a useUniforms key such as shared breaks compilation.

A Tier-3 screenshot fails in CI but passes locally? Your machine rasterizes differently from lavapipe. Look at the uploaded gpu-screenshots artifact; raise the tolerance only if the diff is edge pixels, and regenerate the baseline on Linux with lavapipe if the picture legitimately changed.

Package too small in analyze-* dry-run? If it shows ~100–200 KB instead of the expected ~MB, dist/ is being excluded — ensure the package's files field includes dist.

Open work to bring local/CI testing fully into line with this guide. Trim items as they land.