Skip to main content

Overview

@luma.gl/test-utils contains GPU-aware helpers for testing luma.gl applications and comparing rendered output. It is intended for test code, not application bundles.

When to use it​

Use this package when a test needs a configured luma.gl device, deterministic animation-loop execution, framebuffer readback, or image snapshot comparison. Use ordinary Vitest assertions for CPU-only logic that does not require a device.

Quick start​

import {SnapshotTestRunner} from '@luma.gl/test-utils';

const runner = new SnapshotTestRunner({
  width: 800,
  height: 600,
  onTest: async ({device, renderPass}) => {
    model.draw(renderPass);
  }
});

await runner.run();

See SnapshotTestRunner for its complete configuration and lifecycle.

Test environments​

EnvironmentUse it for
NodePure data, layout, shader assembly, and validation tests that do not create a browser GPU device.
BrowserInteractive WebGPU or WebGL 2 behavior with a real canvas and browser diagnostics.
Headless browserRepeatable rendering and image comparison in automation.

The repository-level commands are documented in the Testing guide.

Snapshot workflow​

  1. Render a deterministic frame at a fixed viewport and device-pixel ratio.
  2. Read the requested attachment only after command submission completes.
  3. Compare against a reviewed reference image with an explicit tolerance.
  4. Record backend, feature level, and adapter details when results are backend-sensitive.

Limits and compatibility​

Image snapshots can vary across GPU vendors and browser implementations. Prefer semantic assertions for algorithms and reserve pixel comparisons for stable presentation behavior. WebGPU-only tests must report that requirement rather than silently falling back to WebGL 2.