wgsl-test 0.2.1

package/README.md

@@ -0,0 +1,111 @@
+# wgsl-test
+
+Write GPU shader tests as easily as regular unit tests. Test WGSL and WESL shaders with vitest or your favorite Node.js test framework.
+
+- **Test WGSL shaders** - Works with standard `.wgsl` files, no new syntax required
+- **Test WESL shaders** - Import and compose shader dependencies via WESL
+- **Visual regression testing** - Snapshot comparison catches rendering changes
+
+## Installation
+
+```bash
+npm install wgsl-test
+```
+
+Quick start in 3 steps:
+
+1. Write your shader function in WGSL or WESL as normal
+2. Use `testCompute()`, `testFragment()`, `testFragmentImage()`, or `expectFragmentImage()` to test your shader with inline source or from files
+3. Assert the results with your test framework
+
+## Testing Compute Shaders
+
+The default choice for unit testing shader functions. Flexible and explicit.
+
+Use `testCompute()` to test compute shader logic. A `test::results` buffer is automatically provided:
+
+```typescript
+import { testCompute, getGPUDevice } from "wgsl-test";
+
+const device = await getGPUDevice();
+
+const src = `
+  import package::hash::lowbias32;
+
+  @compute @workgroup_size(1)
+  fn main() {
+    test::results[0] = lowbias32(0u);
+    test::results[1] = lowbias32(42u);
+  }
+`;
+
+const result = await testCompute({ device, src, size: 2 });
+// result = [0, 388445122]
+```
+
+**[See API.md for complete API documentation →](https://github.com/wgsl-tooling-wg/wesl-js/blob/main/tools/packages/wgsl-test/API.md#testcompute)**
+
+## Testing Fragment Shaders
+
+For unit testing shader functions that only run in fragment shaders. Tests a single pixel output.
+
+Use `testFragment()` to test fragment shader rendering. 
+
+```rs
+/// shaders/foo.wesl
+fn bar(p: vec4f) -> vec4f {
+  return 2 * sqrt(p);
+}
+```
+
+```typescript
+const src = `
+  @fragment
+  fn fs_main(@builtin(position) pos:vec4f) -> @location(0) vec4f {
+    return foo::bar(pos * 2);
+  }
+`;
+
+const result = await testFragment({ device, src });
+// result = [2.828, 1.414, 0.0, 2.0]  // vec4f color at pixel (0,0)
+```
+
+**[See API.md for derivatives, input textures, uniforms, and more →](https://github.com/wgsl-tooling-wg/wesl-js/blob/main/tools/packages/wgsl-test/API.md#testfragment)**
+
+## Visual Regression Testing
+
+Higher level testing, good for regression. Tests don't provide much numeric descriptive value but catch visual changes automatically.
+
+Test complete rendered images:
+
+```typescript
+import { expectFragmentImage, imageMatcher } from "wgsl-test";
+
+imageMatcher(); // Setup once
+
+test("blur shader matches snapshot", async () => {
+  await expectFragmentImage(device, "effects/blur.wgsl", {
+    projectDir: import.meta.url,
+    size: [256, 256],
+  });
+  // Snapshot automatically compared against __image_snapshots__/effects-blur.png
+});
+```
+
+Snapshot comparison automatically detects rendering changes. Update snapshots with `vitest -u` when changes are intentional.
+
+**[See API.md for snapshot workflow and visual regression testing →](https://github.com/wgsl-tooling-wg/wesl-js/blob/main/tools/packages/wgsl-test/API.md#visual-regression-testing)**
+
+## API Documentation
+
+- **[API.md](https://github.com/wgsl-tooling-wg/wesl-js/blob/main/tools/packages/wgsl-test/API.md)** - Complete API reference with detailed examples
+- **[API.md#complete-test-example](https://github.com/wgsl-tooling-wg/wesl-js/blob/main/tools/packages/wgsl-test/API.md#complete-test-example)** - Full vitest test setup with beforeAll/afterAll
+- **[Examples](https://github.com/wgsl-tooling-wg/wesl-js/tree/main/tools/examples)** - Tiny standalone examples
+
+## Future 
+What would you like to see next in wgsl-test? 
+Test scaffolding for vertex shaders?
+Annotations to put simple tests in WESL directly?
+Something else?
+
+Please file an [issue](https://github.com/wgsl-tooling-wg/wesl-js/issues) or talk about your ideas on the tooling group [discord chat](https://discord.gg/5UhkaSu4dt).

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+import { DeviceCache, RenderUniforms, RenderUniforms as RenderUniforms$1, SamplerOptions, checkerboardTexture, colorBarsTexture, createSampler, createUniformsVirtualLib, edgePatternTexture, fullscreenTriangleVertex, gradientTexture, noiseTexture, radialGradientTexture, renderUniformBuffer, simpleRender, solidTexture, updateRenderUniforms, withErrorScopes } from "wesl-gpu";
+import { LinkParams, ModuleResolver, WeslBundle } from "wesl";
+import { WgslElementType, WgslElementType as WgslElementType$1 } from "thimbleberry";
+import { ImageData, ImageData as ImageData$1, MatchImageOptions } from "vitest-image-snapshot";
+
+//#region src/CompileShader.d.ts
+interface ShaderContext {
+  /** Dependency bundles for the shader. */
+  libs: WeslBundle[];
+  /** Resolver for lazy loading (when useSourceShaders is true). */
+  resolver?: ModuleResolver;
+  /** Package name for module resolution. */
+  packageName?: string;
+}
+interface ResolveContextParams {
+  /** WESL/WGSL shader source code. */
+  src: string;
+  /** Project directory for resolving dependencies. */
+  projectDir?: string;
+  /** Use source shaders instead of built bundles. Default: true. */
+  useSourceShaders?: boolean;
+}
+interface CompileShaderParams {
+  /** Project directory for resolving shader dependencies.
+   * Used to locate installed npm shader libraries.
+   * Optional: defaults to searching upward from cwd for package.json or wesl.toml. */
+  projectDir?: string;
+  /** GPU device to use for shader compilation. */
+  device: GPUDevice;
+  /** WESL/WGSL shader source code to compile. */
+  src: string;
+  /** Conditions for conditional compilation.
+   * Used to control `@if` directives in the shader. */
+  conditions?: LinkParams["conditions"];
+  /** Constants for shader compilation.
+   * Injects host-provided values via the `constants::` namespace. */
+  constants?: LinkParams["constants"];
+  /** Virtual libraries to include in the shader.
+   * Allows dynamic generation of shader code at runtime. */
+  virtualLibs?: LinkParams["virtualLibs"];
+  /** Use source shaders from current package instead of built bundles.
+   * Default: true for faster iteration during development.
+   * Set to false or use TEST_BUNDLES=true environment variable to test built bundles.
+   *
+   * Precedence: explicit parameter > TEST_BUNDLES env var > default (true)
+   */
+  useSourceShaders?: boolean;
+}
+/**
+ * Compiles a WESL shader source string into a GPUShaderModule with automatic dependency resolution.
+ *
+ * Parses the shader source to detect references to shader packages, then automatically
+ * includes the required npm package bundles. By default, loads source shaders from the
+ * current package for fast iteration without requiring rebuilds.
+ *
+ * @returns Compiled GPUShaderModule ready for use in render or compute pipelines
+ * @throws Error if shader compilation fails with compilation error details
+ */
+declare function compileShader(params: CompileShaderParams): Promise<GPUShaderModule>;
+/** Resolve project context for shader compilation: bundles, resolver, and package name. */
+declare function resolveShaderContext(params: ResolveContextParams): Promise<ShaderContext>;
+/** Create a project resolver for loading modules from the filesystem.
+ * Handles wesl.toml configuration and creates FileModuleResolver with correct baseDir.
+ *
+ * @param projectDir Project directory (defaults to cwd)
+ * @param packageName Package name for module resolution (optional)
+ * @returns FileModuleResolver configured for the project
+ */
+declare function createProjectResolver(projectDir?: string, packageName?: string): Promise<ModuleResolver>;
+//#endregion
+//#region src/ExampleImages.d.ts
+/** return a texture to the bundled lemur test image. */
+declare function lemurTexture(device: GPUDevice, size?: 256 | 512): Promise<GPUTexture>;
+/** Get the path to the bundled lemur test image. */
+declare function lemurImagePath(size?: 256 | 512): string;
+//#endregion
+//#region src/ImageHelpers.d.ts
+/** Load PNG file and create GPU texture. */
+declare function pngToTexture(device: GPUDevice, imagePath: string): Promise<GPUTexture>;
+//#endregion
+//#region src/TestComputeShader.d.ts
+interface ComputeTestParams {
+  /** WESL/WGSL source code for the compute shader to test.
+   * Either src or moduleName must be provided, but not both. */
+  src?: string;
+  /** Name of shader module to load from filesystem.
+   * Supports: bare name (sum.wgsl), path (algorithms/sum.wgsl), or module path (package::algorithms::sum).
+   * Either src or moduleName must be provided, but not both. */
+  moduleName?: string;
+  /** Project directory for resolving shader dependencies.
+   * Allows the shader to import from npm shader libraries.
+   * Optional: defaults to searching upward from cwd for package.json or wesl.toml.
+   * Typically use `import.meta.url`. */
+  projectDir?: string;
+  /** GPU device for running the tests.
+   * Typically use `getGPUDevice()` from wgsl-test. */
+  device: GPUDevice;
+  /** Format of the result buffer. Default: "u32" */
+  resultFormat?: WgslElementType$1;
+  /** Size of result buffer in elements. Default: 4 */
+  size?: number;
+  /** Flags for conditional compilation to test shader specialization.
+   * Useful for testing `@if` statements in the shader. */
+  conditions?: LinkParams["conditions"];
+  /** Constants for shader compilation.
+   * Injects host-provided values via the `constants::` namespace. */
+  constants?: LinkParams["constants"];
+  /** Use source shaders from current package instead of built bundles.
+   * Default: true for faster iteration during development. */
+  useSourceShaders?: boolean;
+  /** Number of workgroups to dispatch. Default: 1
+   * Can be a single number or [x, y, z] for multi-dimensional dispatch. */
+  dispatchWorkgroups?: number | [number, number, number];
+}
+/**
+ * Compiles and runs a compute shader on the GPU for testing.
+ *
+ * Provides a storage buffer available at `test::results` where the shader
+ * can write test output. After execution, the storage buffer is copied back
+ * to the CPU and returned for validation.
+ *
+ * Shader libraries mentioned in the source are automatically resolved from node_modules.
+ *
+ * @returns Array of numbers from the storage buffer (typically 4 elements for u32/f32 format)
+ */
+declare function testCompute(params: ComputeTestParams): Promise<number[]>;
+/**
+ * Runs a compiled compute shader and returns the result buffer.
+ *
+ * Creates a storage buffer at @group(0) @binding(0) where the shader can
+ * write output. The shader is invoked once, then the buffer is copied back
+ * to the CPU for reading.
+ *
+ * @param module - The compiled GPUShaderModule containing the compute shader
+ * @param resultFormat - Format for interpreting result buffer data (default: u32)
+ * @param size - Size of result buffer in bytes (default: 16)
+ * @param dispatchWorkgroups - Number of workgroups to dispatch (default: 1)
+ * @returns Array containing the shader's output from the storage buffer
+ */
+declare function runCompute(device: GPUDevice, module: GPUShaderModule, resultFormat?: WgslElementType$1, size?: number, dispatchWorkgroups?: number | [number, number, number]): Promise<number[]>;
+//#endregion
+//#region src/TestFragmentShader.d.ts
+interface FragmentTestParams {
+  /** WESL/WGSL source code for the fragment shader to test.
+   * Either src or moduleName must be provided, but not both. */
+  src?: string;
+  /** Name of shader module to load from filesystem.
+   * Supports: bare name (blur.wgsl), path (effects/blur.wgsl), or module path (package::effects::blur).
+   * Either src or moduleName must be provided, but not both. */
+  moduleName?: string;
+  /** Project directory for resolving shader dependencies.
+   * Allows the shader to import from npm shader libraries.
+   * Optional: defaults to searching upward from cwd for package.json or wesl.toml.
+   * Typically use `import.meta.url`. */
+  projectDir?: string;
+  /** GPU device for running the tests.
+   * Typically use `getGPUDevice()` from wgsl-test. */
+  device: GPUDevice;
+  /** Texture format for the output texture. Default: "rgba32float" */
+  textureFormat?: GPUTextureFormat;
+  /** Size of the output texture. Default: [1, 1] for simple color tests.
+   * Use [2, 2] for derivative tests (forms a complete 2x2 quad for dpdx/dpdy). */
+  size?: [width: number, height: number];
+  /** Flags for conditional compilation to test shader specialization.
+   * Useful for testing `@if` statements in the shader. */
+  conditions?: LinkParams["conditions"];
+  /** Constants for shader compilation.
+   * Injects host-provided values via the `constants::` namespace. */
+  constants?: LinkParams["constants"];
+  /** Uniform values for the shader (time, mouse).
+   * Resolution is auto-populated from the size parameter.
+   * Creates test::Uniforms struct available in the shader. */
+  uniforms?: RenderUniforms$1;
+  /** Input textures for the shader.
+   * Bindings: textures at [1..n], samplers at [n+1..n+m].
+   * Binding 0 is reserved for uniforms. */
+  textures?: GPUTexture[];
+  /** Samplers for the input textures.
+   * Must be length 1 (reused for all textures) or match textures.length exactly. */
+  samplers?: GPUSampler[];
+  /** Use source shaders from current package instead of built bundles.
+   * Default: true for faster iteration during development. */
+  useSourceShaders?: boolean;
+}
+interface FragmentImageTestParams extends Omit<FragmentTestParams, "src" | "moduleName" | "device"> {
+  /** Optional snapshot name override. If not provided, derived from shader name. */
+  snapshotName?: string;
+}
+/** Run a fragment shader test and validate image snapshot.
+ * @param device GPU device for rendering
+ * @param moduleName Shader name to load - supports:
+ *   - Bare name: "blur.wgsl" → resolves to shaders/blur.wgsl
+ *   - Relative path: "effects/blur.wgsl" → resolves to shaders/effects/blur.wgsl
+ *   - Module path: "package::effects::blur" → same resolution
+ * @param opts Test parameters (size defaults to 256×256 for snapshots)
+ */
+declare function expectFragmentImage(device: GPUDevice, moduleName: string, opts?: FragmentImageTestParams): Promise<void>;
+/**
+ * Renders a fragment shader and returns pixel (0,0) color values for validation.
+ *
+ * Useful for simple color tests where you only need to check a single pixel result.
+ *
+ * @returns Array of color component values from pixel (0,0)
+ */
+declare function testFragment(params: FragmentTestParams): Promise<number[]>;
+/**
+ * Renders a fragment shader and returns the complete rendered image.
+ *
+ * Useful for image snapshot testing or when you need to validate the entire output.
+ * For snapshot testing shader files, consider using `expectFragmentImage` instead.
+ *
+ * @returns ImageData containing the full rendered output
+ */
+declare function testFragmentImage(params: FragmentTestParams): Promise<ImageData$1>;
+//#endregion
+//#region src/WebGPUTestSetup.d.ts
+/** get or create shared GPU device for testing */
+declare function getGPUDevice(): Promise<GPUDevice>;
+/** destroy globally shared GPU test device */
+declare function destroySharedDevice(): void;
+//#endregion
+//#region src/index.d.ts
+declare module "vitest" {
+  interface Matchers<T = any> {
+    toMatchImage(nameOrOptions?: string | MatchImageOptions): Promise<void>;
+  }
+}
+//#endregion
+export { CompileShaderParams, ComputeTestParams, DeviceCache, FragmentImageTestParams, FragmentTestParams, type ImageData, type RenderUniforms, ResolveContextParams, type SamplerOptions, ShaderContext, type WgslElementType, checkerboardTexture, colorBarsTexture, compileShader, createProjectResolver, createSampler, createUniformsVirtualLib, destroySharedDevice, edgePatternTexture, expectFragmentImage, fullscreenTriangleVertex, getGPUDevice, gradientTexture, lemurImagePath, lemurTexture, noiseTexture, pngToTexture, radialGradientTexture, renderUniformBuffer, resolveShaderContext, runCompute, simpleRender, solidTexture, testCompute, testFragment, testFragmentImage, updateRenderUniforms, withErrorScopes };
+//# sourceMappingURL=index.d.ts.map