wesl-test

library0.6.46jsnpmunverified

GPU shader testing library for WGSL and WESL, version 0.6.46. Provides testCompute, testFragment, testFragmentImage, and expectFragmentImage to unit-test compute and fragment shaders directly from Node.js test frameworks like vitest. Supports visual regression testing via image snapshots. Designed to fill the gap in WebGPU testing tooling, akin to Jest snapshot testing for shaders. Ships TypeScript types. Peer dependencies on vitest ^3.2.4 and vitest-image-snapshot ^0.6.37. Active development with monthly releases.

testing

npm install wesl-test

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WESL-TEST

wesl-test

testingjavascriptv0.6.46

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

testCompute

✓ import { testCompute } from 'wesl-test'

✗ const testCompute = require('wesl-test')

ESM-only package. CJS require fails.

getGPUDevice

✓ import { getGPUDevice } from 'wesl-test'

✗ import { getGPUDevice } from 'wesl-test/getGPUDevice'

Do not use subpath imports; all exports are from the package root.

expectFragmentImage

✓ import { expectFragmentImage, imageMatcher } from 'wesl-test'

✗ import { expectFragmentImage } from 'wesl-test/snapshot'

Both expectFragmentImage and imageMatcher are top-level exports.

Imports getGPUDevice and testCompute, runs a simple compute shader with one workgroup, and logs the result buffer.

import { testCompute, getGPUDevice } from 'wesl-test'; const device = await getGPUDevice(); const src = ` @compute @workgroup_size(1) fn main() { test::results[0] = 42u; } `; const result = await testCompute({ device, src, size: 1 }); console.log(result); // [42]

Debug

Known issues

breakinggetGPUDevice() requires an active GPU adapter. Will throw if WebGPU is not available.

fix

Wrap in try-catch or check navigator.gpu before calling. Run tests only in environments with WebGPU.

affects: >=0.1.0

breakingtestCompute returns an array of numbers; the type is number[] not Uint32Array.

fix

Access results as numbers, or cast to Uint32Array if needed: new Uint32Array(result)

affects: >=0.5.0

deprecatedtestFragmentImage() deprecated in favor of expectFragmentImage() in v0.6.0.

fix

Migrate to expectFragmentImage and call imageMatcher() in setup.

affects: >=0.6.0

gotchaimageMatcher() must be called exactly once before any snapshot tests. Calling it more than once causes duplicate matcher registration.

fix

Call imageMatcher() in a global setup file or setupFiles in vitest config.

affects: >=0.6.0

Errors

Common errors & fixes

Cannot find module 'wesl-test' or its corresponding type declarations.

Package is ESM-only and vitest may be configured for CJS resolution.

fix

Add "type": "module" to your package.json or use vitest --config with esm resolution.

GPUDevice not found. getGPUDevice() must be called after browser or Node WebGPU initialization.

WebGPU adapter or device is not available (e.g., running in a non-WebGPU environment).

fix

Use getGPUDevice() inside a test or beforeAll, and ensure WebGPU is supported (Node with wgpu polyfill or browser with WebGPU).

Upgrade

Version history

0.6.46latest on npm

Audit

Dependencies

vitestrequiredRequired peer for test runner integration

vitest-image-snapshotoptionalRequired peer for image snapshot comparison

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/wgsl-tooling-wg/wesl-js ↗

packagewesl-test ↗

homepagehttps://github.com/wgsl-tooling-wg/wesl-js#readme ↗