GPU-native unit tests for TSL

[bhouston]

TSL/node unit tests today are mock-only — they check bookkeeping against fake renderers, never actual shader output. This adds a harness that runs real TSL expressions on the GPU and asserts on the results, with a QUnit-style API:

gpuTest( 'sRGB <-> linear round trip', ( { assert } ) => {

	const srgb = vec3( 0.5, 0.2, 0.8 );
	const roundTrip = sRGBTransferOETF( sRGBTransferEOTF( srgb ) );

	assert.closeAbs( roundTrip, srgb, 1e-4 );

} );

If things fail, it tells you why and what tests:

sRGB round trip: expected 0.500000, got 0.499994 (Δ0.000006, tolerance 0.0001)

gpuFuzzTest dispatches an assertion across many GPU-generated cases in one shot:

gpuFuzzTest( 'sRGB <-> linear round trip (fuzz, 256 random colors)', 256, ( { instanceIndex, assert } ) => {

	const srgb = vec3( hash( instanceIndex.add( 1 ) ), hash( instanceIndex.add( 1000 ) ), hash( instanceIndex.add( 2000 ) ) );
	const roundTrip = sRGBTransferOETF( sRGBTransferEOTF( srgb ) );

	assert.closeAbs( roundTrip, srgb, 1e-3 );

} );

256 independent cases, generated and checked entirely on the GPU, in one dispatch.

How it works

Each assert.*() call gets its own row in a pair of vec4 storage buffers (actual/expected), written by one compute invocation per row. A tiny internal node asks the real TSL builder what type the expression resolved to (getNodeType(builder)), so no type needs to be declared by hand — even through composed function calls. After the dispatch, the harness reads both buffers back and does the comparison, tolerancing, and per-component diffing on the CPU, where it's cheap to produce good error messages.

Scalars and vecN types are a single row. Matrix types (mat3/mat4) don't fit in one vec4, so they're represented as multiple "columns" — mat3 as 3 x vec3, mat4 as 4 x vec4 — each zero-padded and written/read as its own row, with per-component diff labels like col0.x on failure. gpuFuzzTest sites that assert on a matrix need to opt in via maxColumnsPerSite (3 or 4) since the column count is a resource budget, not just a convenience.

Both entry points run on WebGPU and WebGPURenderer's WebGL2 fallback backend by default (one QUnit test per backend, e.g. ... [webgpu], ... [webgl]) — narrow to one explicitly only for a node that's deliberately WebGPU-only. Each backend's availability is detected at runtime: if a backend fails to initialize in a given environment (no GPU, missing driver, etc.), its tests skip with a warning instead of failing the build — GitHub-hosted CI runners, for instance, can support one backend but not the other depending on the image.

Scope

• test/unit/addons/tsl/gpu-test-utils.js — the harness (gpuTest, gpuFuzzTest, Kind)
• test/unit/addons/tsl/GPUTest.tests.js — example tests
• test/unit/puppeteer.unit.js — prints failing test names/messages (previously only aggregate counts)
• Runs inside the existing npm run test-unit-addons Puppeteer/headless CI job — no new infrastructure
• Supports scalar, vec2–4, mat3 and mat4 types

Based on the GPU testing method used in threeify (render-and-readback shader tests, one row of a texture per test).

(BTW I have already found 8 TSL bugs, a few serious, using this framework, but I will submit them as separate PRs to allow for proper review of each one.)

CC: @sunag

[github-actions]

🖼️ E2E screenshot tests

✅ All examples render correctly again (run).

[mrdoob]

5c81184 should fix the E2E screenshot issue.

[bhouston]

BTW after this is merged, I have already 8 more PRs of bug fixes in TSL that this new functionality has found.

I will do them as separate PRs that each add the relevant unit tests and fix the uncovered bug at the same time. Otherwise I worry that it will not allow for a good review of each of the bugs.