wgsl-test 0.2.1

package/src/TestFragmentShader.ts

@@ -0,0 +1,216 @@
+import { componentByteSize, numComponents, texelLoadType } from "thimbleberry";
+import type { ImageData } from "vitest-image-snapshot";
+import type { LinkParams } from "wesl";
+import { normalizeModuleName } from "wesl";
+import {
+  linkFragmentShader,
+  type RenderUniforms,
+  renderUniformBuffer,
+  simpleRender,
+} from "wesl-gpu";
+import { resolveShaderContext } from "./CompileShader.ts";
+import { resolveShaderSource } from "./ShaderModuleLoader.ts";
+
+export 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;
+
+  /** 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;
+}
+
+export 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)
+ */
+export async function expectFragmentImage(
+  device: GPUDevice,
+  moduleName: string,
+  opts: FragmentImageTestParams = {},
+): Promise<void> {
+  const { textureFormat = "rgba32float", size = [256, 256] } = opts;
+
+  // Render shader image using moduleName
+  const imageData = await testFragmentImage({
+    ...opts,
+    device,
+    moduleName,
+    textureFormat,
+    size,
+  });
+
+  const snapshotName =
+    opts.snapshotName ?? moduleNameToSnapshotName(moduleName);
+  const { imageMatcher } = await import("vitest-image-snapshot");
+  imageMatcher();
+  const { expect } = await import("vitest");
+  await expect(imageData).toMatchImage(snapshotName);
+}
+
+/**
+ * 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)
+ */
+export async function testFragment(
+  params: FragmentTestParams,
+): Promise<number[]> {
+  const { textureFormat = "rgba32float" } = params;
+  const data = await runFragment(params);
+  const count = numComponents(textureFormat);
+  return data.slice(0, count);
+}
+
+/**
+ * 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
+ */
+export async function testFragmentImage(
+  params: FragmentTestParams,
+): Promise<ImageData> {
+  const { textureFormat = "rgba32float", size = [1, 1] } = params;
+  const texData = await runFragment(params);
+  const data = imageToUint8(texData, textureFormat, size[0], size[1]);
+  return {
+    data: new Uint8ClampedArray(data),
+    width: size[0],
+    height: size[1],
+    colorSpace: "srgb" as const,
+  } as ImageData;
+}
+
+async function runFragment(params: FragmentTestParams): Promise<number[]> {
+  const { projectDir, device, src, moduleName, useSourceShaders } = params;
+  const { conditions = {}, constants } = params;
+  const { textureFormat = "rgba32float", size = [1, 1] } = params;
+  const { textures, samplers, uniforms = {} } = params;
+
+  // Resolve shader source from either src or moduleName
+  const fragmentSrc = await resolveShaderSource(src, moduleName, projectDir);
+
+  const ctx = await resolveShaderContext({
+    src: fragmentSrc,
+    projectDir,
+    useSourceShaders,
+  });
+
+  const module = await linkFragmentShader({
+    device,
+    fragmentSource: fragmentSrc,
+    bundles: ctx.libs,
+    resolver: ctx.resolver,
+    packageName: ctx.packageName,
+    conditions,
+    constants,
+  });
+
+  const uniformBuffer = renderUniformBuffer(device, size, uniforms);
+  return await simpleRender({
+    device,
+    module,
+    outputFormat: textureFormat,
+    size,
+    textures,
+    samplers,
+    uniformBuffer,
+  });
+}
+
+/** Convert texture data to RGBA Uint8ClampedArray for image comparison. */
+function imageToUint8(
+  data: ArrayLike<number>,
+  format: GPUTextureFormat,
+  width: number,
+  height: number,
+): Uint8ClampedArray {
+  const totalPixels = width * height;
+  const components = numComponents(format);
+  const byteSize = componentByteSize(format);
+  const texelType = texelLoadType(format);
+
+  if (byteSize === 1 && format.includes("unorm")) {
+    return data instanceof Uint8ClampedArray
+      ? data
+      : new Uint8ClampedArray(Array.from(data));
+  }
+
+  if (texelType === "f32") {
+    const uint8Data = new Uint8ClampedArray(totalPixels * 4);
+    for (let i = 0; i < totalPixels * components; i++) {
+      uint8Data[i] = Math.round(Math.max(0, Math.min(1, data[i])) * 255);
+    }
+    return uint8Data;
+  }
+
+  throw new Error(`Unsupported texture format for image export: ${format}`);
+}
+
+/** Convert module path to snapshot name (e.g., "package::effects::blur" → "effects-blur") */
+function moduleNameToSnapshotName(moduleName: string): string {
+  const normalized = normalizeModuleName(moduleName);
+  return normalized
+    .replace(/^package::/, "") // Strip "package::" prefix
+    .replaceAll("::", "-"); // Replace :: with -
+}

package/src/WebGPUTestSetup.ts

@@ -0,0 +1,30 @@
+import * as webgpu from "webgpu";
+
+let sharedGpu: GPU | undefined;
+let sharedDevice: GPUDevice | undefined;
+
+/** get or create shared GPU device for testing */
+export async function getGPUDevice(): Promise<GPUDevice> {
+  if (!sharedDevice) {
+    const gpu = await setupWebGPU();
+    const adapter = await gpu.requestAdapter();
+    if (!adapter) throw new Error("Failed to get GPU adapter");
+    sharedDevice = await adapter.requestDevice();
+  }
+  return sharedDevice;
+}
+
+/** destroy globally shared GPU test device */
+export function destroySharedDevice(): void {
+  sharedDevice?.destroy();
+  sharedDevice = undefined;
+}
+
+/** initialize WebGPU for testing */
+async function setupWebGPU(): Promise<GPU> {
+  if (!sharedGpu) {
+    Object.assign(globalThis, webgpu.globals);
+    sharedGpu = webgpu.create([]);
+  }
+  return sharedGpu;
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+/* oxlint-disable no-unused-vars */
+export type { WgslElementType } from "thimbleberry";
+export type { ImageData } from "vitest-image-snapshot";
+
+// Re-export from wesl-gpu for convenience
+export type { RenderUniforms, SamplerOptions } from "wesl-gpu";
+export {
+  checkerboardTexture,
+  colorBarsTexture,
+  createSampler,
+  createUniformsVirtualLib,
+  DeviceCache,
+  edgePatternTexture,
+  fullscreenTriangleVertex,
+  gradientTexture,
+  noiseTexture,
+  radialGradientTexture,
+  renderUniformBuffer,
+  simpleRender,
+  solidTexture,
+  updateRenderUniforms,
+  withErrorScopes,
+} from "wesl-gpu";
+
+export * from "./CompileShader.ts";
+export * from "./ExampleImages.ts";
+export * from "./ImageHelpers.ts";
+export * from "./TestComputeShader.ts";
+export * from "./TestFragmentShader.ts";
+export * from "./WebGPUTestSetup.ts";
+
+// Re-export module augmentation from vitest-image-snapshot for packaged builds
+import type {} from "vitest";
+import type { MatchImageOptions } from "vitest-image-snapshot";
+
+declare module "vitest" {
+  // biome-ignore lint/correctness/noUnusedVariables: T must match Vitest's Matchers<T> signature
+  interface Matchers<T = any> {
+    toMatchImage(nameOrOptions?: string | MatchImageOptions): Promise<void>;
+  }
+}

package/src/test/ImageSnapshot.test.ts

@@ -0,0 +1,212 @@
+import { afterAll, beforeAll, expect, test } from "vitest";
+import { imageMatcher } from "vitest-image-snapshot";
+import { lemurTexture } from "../ExampleImages.ts";
+import {
+  checkerboardTexture,
+  colorBarsTexture,
+  createSampler,
+  destroySharedDevice,
+  edgePatternTexture,
+  expectFragmentImage,
+  getGPUDevice,
+  testFragmentImage,
+} from "../index.ts";
+
+imageMatcher();
+
+let device: GPUDevice;
+
+beforeAll(async () => {
+  device = await getGPUDevice();
+});
+
+afterAll(() => {
+  destroySharedDevice();
+});
+
+test("simple box blur", async () => {
+  const inputTex = checkerboardTexture(device, 128, 128, 16);
+  const sampler = createSampler(device);
+
+  const src = `
+    @group(0) @binding(1) var input_tex: texture_2d<f32>;
+    @group(0) @binding(2) var input_samp: sampler;
+
+    @fragment
+    fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+      let uv = pos.xy / 128.0;
+      let pixel_size = 1.0 / 128.0;
+
+      // 3x3 box blur
+      var color = vec4f(0.0);
+      for (var y = -1; y <= 1; y++) {
+        for (var x = -1; x <= 1; x++) {
+          let offset = vec2f(f32(x), f32(y)) * pixel_size;
+          color += textureSample(input_tex, input_samp, uv + offset);
+        }
+      }
+
+      return color / 9.0;
+    }
+  `;
+
+  const result = await testFragmentImage({
+    projectDir: import.meta.url,
+    device,
+    src,
+    size: [128, 128],
+    textures: [inputTex],
+    samplers: [sampler],
+  });
+
+  await expect(result).toMatchImage("box-blur");
+});
+
+test("simple edge detection", async () => {
+  const inputTex = edgePatternTexture(device, 128);
+  const sampler = createSampler(device);
+
+  const src = `
+    @group(0) @binding(1) var input_tex: texture_2d<f32>;
+    @group(0) @binding(2) var input_samp: sampler;
+
+    @fragment
+    fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+      let uv = pos.xy / 128.0;
+      let pixel_size = 1.0 / 128.0;
+
+      // Simple Sobel operator
+      let tl = textureSample(input_tex, input_samp, uv + vec2f(-pixel_size, -pixel_size)).rgb;
+      let tr = textureSample(input_tex, input_samp, uv + vec2f( pixel_size, -pixel_size)).rgb;
+      let bl = textureSample(input_tex, input_samp, uv + vec2f(-pixel_size,  pixel_size)).rgb;
+      let br = textureSample(input_tex, input_samp, uv + vec2f( pixel_size,  pixel_size)).rgb;
+
+      let gx = -tl + tr - bl + br;
+      let gy = -tl - tr + bl + br;
+      let mag = length(vec2f(dot(gx, vec3f(0.299, 0.587, 0.114)),
+                             dot(gy, vec3f(0.299, 0.587, 0.114))));
+
+      return vec4f(vec3f(mag), 1.0);
+    }
+  `;
+
+  const result = await testFragmentImage({
+    projectDir: import.meta.url,
+    device,
+    src,
+    size: [128, 128],
+    textures: [inputTex],
+    samplers: [sampler],
+  });
+
+  await expect(result).toMatchImage({
+    name: "edge-detection",
+    allowedPixelRatio: 0.01,
+  });
+});
+
+test("grayscale conversion", async () => {
+  const inputTex = colorBarsTexture(device, 128);
+  const sampler = createSampler(device);
+
+  const src = `
+    @group(0) @binding(1) var input_tex: texture_2d<f32>;
+    @group(0) @binding(2) var input_samp: sampler;
+
+    @fragment
+    fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+      let uv = pos.xy / 128.0;
+      let color = textureSample(input_tex, input_samp, uv);
+
+      // Perceptual grayscale
+      let gray = dot(color.rgb, vec3f(0.299, 0.587, 0.114));
+
+      return vec4f(vec3f(gray), 1.0);
+    }
+  `;
+
+  const result = await testFragmentImage({
+    projectDir: import.meta.url,
+    device,
+    src,
+    size: [128, 128],
+    textures: [inputTex],
+    samplers: [sampler],
+  });
+
+  await expect(result).toMatchImage("grayscale");
+});
+
+test("sharpen filter on photo sample", async () => {
+  const inputTex = await lemurTexture(device);
+  const sampler = createSampler(device);
+
+  const src = `
+    @group(0) @binding(1) var input_tex: texture_2d<f32>;
+    @group(0) @binding(2) var input_samp: sampler;
+
+    @fragment
+    fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+      let uv = pos.xy / 512.0;
+      let pixel_size = 1.0 / 512.0;
+
+      // Simple sharpen kernel
+      let center = textureSample(input_tex, input_samp, uv);
+      let top = textureSample(input_tex, input_samp, uv + vec2f(0.0, -pixel_size));
+      let bottom = textureSample(input_tex, input_samp, uv + vec2f(0.0, pixel_size));
+      let left = textureSample(input_tex, input_samp, uv + vec2f(-pixel_size, 0.0));
+      let right = textureSample(input_tex, input_samp, uv + vec2f(pixel_size, 0.0));
+
+      let sharpened = center * 5.0 - top - bottom - left - right;
+      return vec4f(clamp(sharpened.rgb, vec3f(0.0), vec3f(1.0)), 1.0);
+    }
+  `;
+
+  const result = await testFragmentImage({
+    projectDir: import.meta.url,
+    device,
+    src,
+    size: [512, 512],
+    textures: [inputTex],
+    samplers: [sampler],
+  });
+
+  await expect(result).toMatchImage("lemur-sharpen");
+});
+
+test("expectFragmentImage with bare name", async () => {
+  const testPkgDir = new URL("./fixtures/test_shader_pkg/", import.meta.url)
+    .href;
+  await expectFragmentImage(device, "solid_red", {
+    projectDir: testPkgDir,
+    size: [128, 128],
+  });
+});
+
+test("expectFragmentImage with relative path", async () => {
+  const testPkgDir = new URL("./fixtures/test_shader_pkg/", import.meta.url)
+    .href;
+  await expectFragmentImage(device, "effects/checkerboard.wgsl", {
+    projectDir: testPkgDir,
+    size: [128, 128],
+  });
+});
+
+test("expectFragmentImage with module path", async () => {
+  const testPkgDir = new URL("./fixtures/test_shader_pkg/", import.meta.url)
+    .href;
+  await expectFragmentImage(device, "package::solid_red", {
+    projectDir: testPkgDir,
+    size: [128, 128],
+  });
+});
+
+test("expectFragmentImage with custom snapshot name", async () => {
+  const testPkgDir = new URL("./fixtures/test_shader_pkg/", import.meta.url)
+    .href;
+  await expectFragmentImage(device, "solid_red.wgsl", {
+    projectDir: testPkgDir,
+    size: [64, 64],
+    snapshotName: "solid-red-small",
+  });
+});

package/src/test/PackageImport.test.ts

@@ -0,0 +1,110 @@
+import { afterAll, beforeAll, expect, test } from "vitest";
+import { testCompute } from "../TestComputeShader.ts";
+import { destroySharedDevice, getGPUDevice } from "../WebGPUTestSetup.ts";
+
+let device: GPUDevice;
+const testPkgDir = new URL("./fixtures/test_shader_pkg/", import.meta.url).href;
+
+beforeAll(async () => {
+  device = await getGPUDevice();
+});
+
+afterAll(() => {
+  destroySharedDevice();
+});
+
+async function runTest(src: string, options = {}) {
+  return await testCompute({
+    projectDir: testPkgDir,
+    device,
+    src,
+    ...options,
+  });
+}
+
+test("import from current package with default useSourceShaders", async () => {
+  const result = await runTest(
+    `import package::utils::helper;
+    @compute @workgroup_size(1)
+    fn main() {
+      test::results[0] = helper();
+    }`,
+  );
+  expect(result[0]).toBe(42);
+});
+
+test("import from bundled package with useSourceShaders: false", async () => {
+  const result = await runTest(
+    `import test_shader_pkg::utils::helper;
+    @compute @workgroup_size(1)
+    fn main() {
+      test::results[0] = helper();
+    }`,
+    { useSourceShaders: false },
+  );
+  expect(result[0]).toBe(43);
+});
+
+test("import using actual package name instead of 'package::'", async () => {
+  const result = await runTest(
+    `import test_shader_pkg::utils::helper;
+    @compute @workgroup_size(1)
+    fn main() {
+      test::results[0] = helper();
+    }`,
+  );
+  expect(result[0]).toBe(42);
+});
+
+test("import from .wgsl file when .wesl doesn't exist", async () => {
+  const result = await runTest(
+    `import package::legacy::legacyHelper;
+    @compute @workgroup_size(1)
+    fn main() {
+      test::results[0] = legacyHelper();
+    }`,
+  );
+  expect(result[0]).toBe(99);
+});
+
+/** Incremental module resolution per WESL spec:
+ * For "import foo::bar::zap", tries: foo.wesl::bar, then foo/bar.wesl::zap, then foo/bar/zap.wesl
+ * Item definitions are prioritized over filesystem structure
+ */
+
+test("import from deeply nested path", async () => {
+  const result = await runTest(
+    `import package::nested::deeper::func::deepHelper;
+    @compute @workgroup_size(1)
+    fn main() {
+      test::results[0] = deepHelper();
+    }`,
+  );
+  expect(result[0]).toBe(123);
+});
+
+test("resolve when intermediate module exists but lacks the item", async () => {
+  // foo/bar.wesl exists but lacks "zap" item
+  // Resolution continues to foo/bar/zap.wesl
+  const result = await runTest(
+    `import package::foo::bar::zap::zapValue;
+    @compute @workgroup_size(1)
+    fn main() {
+      test::results[0] = zapValue;
+    }`,
+  );
+  expect(result[0]).toBe(88);
+});
+
+test("item in module takes priority over submodule file", async () => {
+  // priority.wesl contains const sub = 777u
+  // Per spec: "item definitions prioritized over filesystem"
+  const result = await runTest(
+    `import package::priority::sub;
+    @compute @workgroup_size(1)
+    fn main() {
+      test::results[0] = sub;
+    }`,
+  );
+  expect(result[0]).toBe(777);
+});