wgsl-test 0.2.5 → 0.2.6

package/dist/weslBundle.d.ts

@@ -0,0 +1,20 @@
+export interface WeslBundle {
+  /** npm package name sanitized to be a valid WESL identifier
+   * (@ removed, / ==> __, - ==> _) */
+  name: string;
+
+  /** WESL edition of the code e.g. unstable_2025_1 */
+  edition: string;
+
+  /** map of WESL/WGSL modules:
+   *    keys are file paths, relative to package root (e.g. "./lib.wgsl")
+   *    values are WESL/WGSL code strings
+   */
+  modules: Record<string, string>;
+
+  /** packages referenced by this package */
+  dependencies?: WeslBundle[];
+}
+
+export declare const weslBundle: WeslBundle;
+export default weslBundle;

package/dist/weslBundle.js

@@ -0,0 +1,12 @@
+export const weslBundle = {
+  name: "wgsl_test",
+  edition: "unstable_2025_1",
+  modules: {
+    "lib.wesl":
+      "import package::TestResult::testResult;\n\nconst relTol: f32 = 1e-3;\nconst absTol: f32 = 1e-6;\n\nfn expect(condition: bool) {\n  if (!condition && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectEq(actual: u32, expected: u32) {\n  testResult.actual = vec4f(f32(actual), 0.0, 0.0, 0.0);\n  testResult.expected = vec4f(f32(expected), 0.0, 0.0, 0.0);\n  if (actual != expected && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectWithin(actual: f32, expected: f32, relTol: f32, absTol: f32) {\n  testResult.actual = vec4f(actual, 0.0, 0.0, 0.0);\n  testResult.expected = vec4f(expected, 0.0, 0.0, 0.0);\n  let diff = abs(actual - expected);\n  let tolerance = max(absTol, relTol * max(abs(actual), abs(expected)));\n  if (diff > tolerance && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectNear(actual: f32, expected: f32) {\n  expectWithin(actual, expected, relTol, absTol);\n}\n\nfn expectWithinVec2(actual: vec2f, expected: vec2f, relTol: f32, absTol: f32) {\n  testResult.actual = vec4f(actual, 0.0, 0.0);\n  testResult.expected = vec4f(expected, 0.0, 0.0);\n  let diff = abs(actual - expected);\n  let tolerance = max(vec2f(absTol), relTol * max(abs(actual), abs(expected)));\n  if (any(diff > tolerance) && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectNearVec2(actual: vec2f, expected: vec2f) {\n  expectWithinVec2(actual, expected, relTol, absTol);\n}\n\nfn expectWithinVec3(actual: vec3f, expected: vec3f, relTol: f32, absTol: f32) {\n  testResult.actual = vec4f(actual, 0.0);\n  testResult.expected = vec4f(expected, 0.0);\n  let diff = abs(actual - expected);\n  let tolerance = max(vec3f(absTol), relTol * max(abs(actual), abs(expected)));\n  if (any(diff > tolerance) && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectNearVec3(actual: vec3f, expected: vec3f) {\n  expectWithinVec3(actual, expected, relTol, absTol);\n}\n\nfn expectWithinVec4(actual: vec4f, expected: vec4f, relTol: f32, absTol: f32) {\n  testResult.actual = actual;\n  testResult.expected = expected;\n  let diff = abs(actual - expected);\n  let tolerance = max(vec4f(absTol), relTol * max(abs(actual), abs(expected)));\n  if (any(diff > tolerance) && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectNearVec4(actual: vec4f, expected: vec4f) {\n  expectWithinVec4(actual, expected, relTol, absTol);\n}\n\n// ULP (Units in Last Place) comparison - measures how many representable floats apart\nfn ulpDiff(actual: f32, expected: f32) -> u32 {\n  let aBits = bitcast<i32>(actual);\n  let bBits = bitcast<i32>(expected);\n  return u32(abs(aBits - bBits));\n}\n\nfn expectUlp(actual: f32, expected: f32, maxUlp: u32) {\n  testResult.actual = vec4f(actual, 0.0, 0.0, 0.0);\n  testResult.expected = vec4f(expected, 0.0, 0.0, 0.0);\n  if (actual == expected) { return; }  // handles +0 == -0, exact match\n  let diff = ulpDiff(actual, expected);\n  if (diff > maxUlp && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectUlpVec2(actual: vec2f, expected: vec2f, maxUlp: u32) {\n  testResult.actual = vec4f(actual, 0.0, 0.0);\n  testResult.expected = vec4f(expected, 0.0, 0.0);\n  if (all(actual == expected)) { return; }\n  let d0 = ulpDiff(actual.x, expected.x);\n  let d1 = ulpDiff(actual.y, expected.y);\n  if ((d0 > maxUlp || d1 > maxUlp) && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectUlpVec3(actual: vec3f, expected: vec3f, maxUlp: u32) {\n  testResult.actual = vec4f(actual, 0.0);\n  testResult.expected = vec4f(expected, 0.0);\n  if (all(actual == expected)) { return; }\n  let d0 = ulpDiff(actual.x, expected.x);\n  let d1 = ulpDiff(actual.y, expected.y);\n  let d2 = ulpDiff(actual.z, expected.z);\n  if ((d0 > maxUlp || d1 > maxUlp || d2 > maxUlp) && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n\nfn expectUlpVec4(actual: vec4f, expected: vec4f, maxUlp: u32) {\n  testResult.actual = actual;\n  testResult.expected = expected;\n  if (all(actual == expected)) { return; }\n  let d0 = ulpDiff(actual.x, expected.x);\n  let d1 = ulpDiff(actual.y, expected.y);\n  let d2 = ulpDiff(actual.z, expected.z);\n  let d3 = ulpDiff(actual.w, expected.w);\n  if ((d0 > maxUlp || d1 > maxUlp || d2 > maxUlp || d3 > maxUlp) && testResult.failCount == 0u) {\n    testResult.passed = 0u;\n    testResult.failCount = 1u;\n  }\n}\n",
+    "TestResult.wesl":
+      "struct TestResult {\n  passed: u32,\n  failCount: u32,\n  actual: vec4f,\n  expected: vec4f,\n}\n\n@group(0) @binding(0) var<storage, read_write> testResult: TestResult;\n\nfn initTestResult() {\n  testResult.passed = 1u;\n  testResult.failCount = 0u;\n}\n",
+  },
+};
+
+export default weslBundle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wgsl-test",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "files": [
     "dist",
@@ -12,24 +12,28 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./shaders": {
+      "import": "./dist/weslBundle.js"
     }
   },
   "dependencies": {
     "pngjs": "^7.0.0",
     "thimbleberry": "^0.2.10",
     "webgpu": "^0.3.8",
-    "wesl": "0.7.1",
-    "wesl-gpu": "0.1.4"
+    "wesl": "0.7.2",
+    "wesl-gpu": "0.1.5"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.0",
     "@webgpu/types": "^0.1.68",
     "dependent_package": "x",
+    "wesl-packager": "x",
     "wesl-tooling": "x"
   },
   "peerDependencies": {
     "vitest": "^4.0.16",
-    "vitest-image-snapshot": "^0.6.39"
+    "vitest-image-snapshot": "^0.6.40"
   },
   "peerDependenciesMeta": {
     "vitest": {
@@ -51,9 +55,10 @@
     "WGSL"
   ],
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && wesl-packager",
     "dev": "tsdown --watch",
     "test": "cross-env FORCE_COLOR=1 vitest",
+    "test:deno": "deno run -A --unstable-webgpu npm:vitest run",
     "test:once": "vitest run",
     "typecheck": "tsgo"
   },

package/src/CompileShader.ts

@@ -30,6 +30,9 @@ export interface ResolveContextParams {
 
   /** Use source shaders instead of built bundles. Default: true. */
   useSourceShaders?: boolean;
+
+  /** Virtual lib names to exclude from dependency resolution. */
+  virtualLibNames?: string[];
 }
 
 export interface CompileShaderParams {
@@ -56,6 +59,14 @@ export interface CompileShaderParams {
    * Allows dynamic generation of shader code at runtime. */
   virtualLibs?: LinkParams["virtualLibs"];
 
+  /** Additional WESL bundles to include.
+   * These are merged with auto-discovered dependencies. */
+  libs?: WeslBundle[];
+
+  /** Override the package name for module resolution.
+   * Used to ensure package:: references resolve correctly. */
+  packageName?: string;
+
   /** 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.
@@ -78,18 +89,22 @@ export interface CompileShaderParams {
 export async function compileShader(
   params: CompileShaderParams,
 ): Promise<GPUShaderModule> {
-  const { device, src, conditions, constants, virtualLibs } = params;
+  const { device, src, conditions, constants, virtualLibs, libs = [] } = params;
   const ctx = await resolveShaderContext({
     src,
     projectDir: params.projectDir,
     useSourceShaders: params.useSourceShaders,
+    virtualLibNames: virtualLibs ? Object.keys(virtualLibs) : [],
   });
 
+  // Filter out undefined values that can occur when auto-discovery finds packages
+  // that aren't resolvable (e.g., wgsl_test when running tests within wgsl-test itself)
+  const allLibs = [...ctx.libs, ...libs].filter(Boolean) as WeslBundle[];
   let linkParams: Pick<LinkParams, "resolver" | "libs" | "weslSrc">;
   if (ctx.resolver) {
-    linkParams = { resolver: ctx.resolver, libs: ctx.libs };
+    linkParams = { resolver: ctx.resolver, libs: allLibs };
   } else {
-    linkParams = { weslSrc: { main: src }, libs: ctx.libs };
+    linkParams = { weslSrc: { main: src }, libs: allLibs };
   }
 
   const linked = await link({
@@ -98,7 +113,7 @@ export async function compileShader(
     virtualLibs,
     conditions,
     constants,
-    packageName: ctx.packageName,
+    packageName: params.packageName ?? ctx.packageName,
   });
   const module = linked.createShaderModule(device);
 
@@ -111,6 +126,7 @@ export async function resolveShaderContext(
   params: ResolveContextParams,
 ): Promise<ShaderContext> {
   const { src, useSourceShaders = !process.env.TEST_BUNDLES } = params;
+  const { virtualLibNames = [] } = params;
   const projectDir = await resolveProjectDir(params.projectDir);
   const packageName = await getPackageName(projectDir);
 
@@ -119,6 +135,7 @@ export async function resolveShaderContext(
     projectDir,
     packageName,
     !useSourceShaders, // include current package when testing bundles
+    virtualLibNames,
   );
 
   const resolver = useSourceShaders
@@ -149,16 +166,16 @@ export async function createProjectResolver(
   return new FileModuleResolver(baseDir, packageName);
 }
 
-/** Create a lazy resolver that loads local shaders on-demand from the filesystem.
- * Laziness allows testing without rebuilding the current package after edits. */
-async function lazyFileResolver(
-  projectDir: string,
-  mainSrc: string,
-  packageName: string | undefined,
-): Promise<CompositeResolver> {
-  const mainResolver = new RecordResolver({ main: mainSrc }, { packageName });
-  const fileResolver = await createProjectResolver(projectDir, packageName);
-  return new CompositeResolver([mainResolver, fileResolver]);
+/** Verify shader compilation succeeded, throw on errors. */
+async function verifyCompilation(module: GPUShaderModule): Promise<void> {
+  const info = await module.getCompilationInfo();
+  const errors = info.messages.filter(msg => msg.type === "error");
+  if (errors.length > 0) {
+    const messages = errors
+      .map(e => `${e.lineNum}:${e.linePos} ${e.message}`)
+      .join("\n");
+    throw new Error(`Shader compilation failed:\n${messages}`);
+  }
 }
 
 /** Read package name from package.json, normalized for WGSL identifiers. */
@@ -172,14 +189,14 @@ async function getPackageName(projectDir: string): Promise<string | undefined> {
   }
 }
 
-/** Verify shader compilation succeeded, throw on errors. */
-async function verifyCompilation(module: GPUShaderModule): Promise<void> {
-  const info = await module.getCompilationInfo();
-  const errors = info.messages.filter(msg => msg.type === "error");
-  if (errors.length > 0) {
-    const messages = errors
-      .map(e => `${e.lineNum}:${e.linePos} ${e.message}`)
-      .join("\n");
-    throw new Error(`Shader compilation failed:\n${messages}`);
-  }
+/** Create a lazy resolver that loads local shaders on-demand from the filesystem.
+ * Laziness allows testing without rebuilding the current package after edits. */
+async function lazyFileResolver(
+  projectDir: string,
+  mainSrc: string,
+  packageName: string | undefined,
+): Promise<CompositeResolver> {
+  const mainResolver = new RecordResolver({ main: mainSrc }, { packageName });
+  const fileResolver = await createProjectResolver(projectDir, packageName);
+  return new CompositeResolver([mainResolver, fileResolver]);
 }

package/src/TestComputeShader.ts

@@ -2,9 +2,7 @@ import { copyBuffer, elementStride, type WgslElementType } from "thimbleberry";
 import type { LinkParams } from "wesl";
 import { withErrorScopes } from "wesl-gpu";
 import { compileShader } from "./CompileShader.ts";
-import { resolveShaderSource } from "./ShaderModuleLoader.ts";
-
-const defaultResultSize = 4; // 4 elements
+import { resolveShaderSource } from "./ShaderModuleLoader.ts"; // 4 elements
 
 export interface ComputeTestParams {
   /** WESL/WGSL source code for the compute shader to test.
@@ -49,6 +47,17 @@ export interface ComputeTestParams {
   dispatchWorkgroups?: number | [number, number, number];
 }
 
+export interface RunComputeParams {
+  device: GPUDevice;
+  module: GPUShaderModule;
+  resultFormat?: WgslElementType;
+  size?: number;
+  dispatchWorkgroups?: number | [number, number, number];
+  entryPoint?: string;
+}
+
+const defaultResultSize = 4;
+
 /**
  * Compiles and runs a compute shader on the GPU for testing.
  *
@@ -94,13 +103,13 @@ export async function testCompute(
     useSourceShaders,
   });
 
-  return await runCompute(
+  return await runCompute({
     device,
     module,
     resultFormat,
     size,
     dispatchWorkgroups,
-  );
+  });
 }
 
 /**
@@ -109,20 +118,11 @@ export async function testCompute(
  * 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
  */
-export async function runCompute(
-  device: GPUDevice,
-  module: GPUShaderModule,
-  resultFormat: WgslElementType = "u32",
-  size = defaultResultSize,
-  dispatchWorkgroups: number | [number, number, number] = 1,
-): Promise<number[]> {
+export async function runCompute(params: RunComputeParams): Promise<number[]> {
+  const { device, module, entryPoint } = params;
+  const { resultFormat = "u32", size = defaultResultSize } = params;
+  const { dispatchWorkgroups = 1 } = params;
   return await withErrorScopes(device, async () => {
     const bgLayout = device.createBindGroupLayout({
       entries: [
@@ -136,7 +136,7 @@ export async function runCompute(
 
     const pipeline = device.createComputePipeline({
       layout: device.createPipelineLayout({ bindGroupLayouts: [bgLayout] }),
-      compute: { module },
+      compute: { module, entryPoint },
     });
 
     const storageBuffer = createStorageBuffer(

package/src/TestDiscovery.ts

@@ -0,0 +1,50 @@
+import type { FnElem, StandardAttribute, WeslAST } from "wesl";
+
+export interface TestFunctionInfo {
+  name: string;
+  description?: string;
+  fn: FnElem;
+}
+
+/** Find all functions marked with @test attribute in a parsed WESL module. */
+export function findTestFunctions(ast: WeslAST): TestFunctionInfo[] {
+  return ast.moduleElem.contents
+    .filter((e): e is FnElem => e.kind === "fn")
+    .filter(hasTestAttribute)
+    .filter(fn => {
+      if (fn.params.length > 0) {
+        const name = fn.name.ident.originalName;
+        console.warn(
+          `@test function '${name}' has parameters and will be skipped`,
+        );
+        return false;
+      }
+      return true;
+    })
+    .map(fn => ({
+      name: fn.name.ident.originalName,
+      description: getTestDescription(fn),
+      fn,
+    }));
+}
+
+function hasTestAttribute(fn: FnElem): boolean {
+  return !!getTestAttribute(fn);
+}
+
+/** Extract description from @test(description) attribute. */
+function getTestDescription(fn: FnElem): string | undefined {
+  const testAttr = getTestAttribute(fn);
+  const param = testAttr?.params?.[0];
+  if (!param) return undefined;
+  // Extract the identifier text from the expression contents
+  const text = param.contents.find(c => c.kind === "ref");
+  return text?.kind === "ref" ? text.ident.originalName : undefined;
+}
+
+function getTestAttribute(fn: FnElem): StandardAttribute | undefined {
+  for (const e of fn.attributes ?? []) {
+    const attr = e.attribute;
+    if (attr.kind === "@attribute" && attr.name === "test") return attr;
+  }
+}

package/src/TestFragmentShader.ts

@@ -8,6 +8,7 @@ import {
 } from "wesl-gpu";
 import { resolveShaderContext } from "./CompileShader.ts";
 import { resolveShaderSource } from "./ShaderModuleLoader.ts";
+import { importImageSnapshot, importVitest } from "./VitestImport.ts";
 
 export interface FragmentTestParams extends WeslOptions, FragmentRenderParams {
   /** WESL/WGSL source code for the fragment shader to test.
@@ -62,9 +63,9 @@ export async function expectFragmentImage(
 
   const snapshotName =
     opts.snapshotName ?? moduleNameToSnapshotName(moduleName);
-  const { imageMatcher } = await import("vitest-image-snapshot");
+  const { imageMatcher } = await importImageSnapshot();
   imageMatcher();
-  const { expect } = await import("vitest");
+  const { expect } = await importVitest();
   await expect(imageData).toMatchImage(snapshotName);
 }
 
@@ -106,6 +107,14 @@ export async function testFragmentImage(
   } as ImageData;
 }
 
+/** 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 -
+}
+
 async function runFragment(params: FragmentTestParams): Promise<number[]> {
   const { projectDir, src, moduleName, useSourceShaders } = params;
 
@@ -113,10 +122,12 @@ async function runFragment(params: FragmentTestParams): Promise<number[]> {
   const fragmentSrc = await resolveShaderSource(src, moduleName, projectDir);
 
   // Resolve context (libs, resolver, packageName) from project
+  // Note: "test" virtualLib is provided by wesl-gpu for test::Uniforms
   const ctx = await resolveShaderContext({
     src: fragmentSrc,
     projectDir,
     useSourceShaders,
+    virtualLibNames: ["test"],
   });
 
   // Use shared runFragment with resolved source and context
@@ -157,11 +168,3 @@ function imageToUint8(
 
   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/TestVirtualLib.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+
+/** Size of TestResult struct in bytes.
+ * Layout: u32 passed (4) + u32 failCount (4) + padding (8) + vec4f actual (16) + vec4f expected (16) = 48 */
+export const testResultSize = 48;
+
+let cachedTestLibSrc: string | undefined;
+
+/** Virtual library for test:: namespace providing assertions and result reporting. */
+export function testVirtualLib(): string {
+  if (!cachedTestLibSrc) {
+    cachedTestLibSrc = readFileSync(
+      new URL("./test_lib.wesl", import.meta.url),
+      "utf-8",
+    );
+  }
+  return cachedTestLibSrc;
+}

package/src/TestWesl.ts

@@ -0,0 +1,183 @@
+import { type LinkParams, parseSrcModule, type WeslBundle } from "wesl";
+import { compileShader } from "./CompileShader.ts";
+import { resolveShaderSource } from "./ShaderModuleLoader.ts";
+import { type ComputeTestParams, runCompute } from "./TestComputeShader.ts";
+import { findTestFunctions, type TestFunctionInfo } from "./TestDiscovery.ts";
+import { testResultSize } from "./TestVirtualLib.ts";
+import { importVitest } from "./VitestImport.ts";
+
+/** Parameters for running @test functions in a WESL module. */
+export type RunWeslParams = Omit<
+  ComputeTestParams,
+  "resultFormat" | "size" | "dispatchWorkgroups"
+> & {
+  /** Run only the @test function with this name */
+  testName?: string;
+};
+
+/** Result from running a single @test function on the GPU. */
+export interface TestResult {
+  name: string;
+  passed: boolean;
+  actual: number[];
+  expected: number[];
+}
+
+/** Parameters for testWesl() which registers all @test functions with vitest. */
+export type TestWeslParams = Omit<RunWeslParams, "testName">;
+
+/** Internal params for executing one @test function as a compute shader. */
+interface RunSingleTestParams {
+  testFn: TestFunctionInfo;
+  shaderSrc: string;
+  projectDir?: string;
+  device: GPUDevice;
+  conditions?: LinkParams["conditions"];
+  constants?: LinkParams["constants"];
+  useSourceShaders?: boolean;
+}
+
+/** Parsed WESL source with its AST for test discovery. */
+interface ParsedTestModule {
+  shaderSrc: string;
+  ast: ReturnType<typeof parseSrcModule>;
+}
+
+// Auto-inject the wgsl-test shader library bundle
+let cachedWeslBundle: WeslBundle;
+
+/**
+ * Discovers @test functions in a WESL module and registers each as a vitest test.
+ * Use top-level await in your test file to call this function.
+ */
+export async function testWesl(params: TestWeslParams): Promise<void> {
+  const { test } = await importVitest();
+  const { ast } = await parseTestModule(params);
+  const testFns = findTestFunctions(ast);
+  for (const fn of testFns) {
+    const testLabel = fn.description ?? fn.name;
+    test(testLabel, async () => {
+      await expectWesl({ ...params, testName: fn.name });
+    });
+  }
+}
+
+/**
+ * Runs all @test functions and asserts they pass.
+ * Throws descriptive error on failure showing test name and actual/expected values.
+ */
+export async function expectWesl(params: RunWeslParams): Promise<void> {
+  const results = await runWesl(params);
+  const failures = results.filter(r => !r.passed);
+
+  if (failures.length > 0) {
+    const messages = failures.map(f => {
+      let msg = `  ${f.name}: FAILED`;
+      msg += `\n    actual:   [${f.actual.join(", ")}]`;
+      msg += `\n    expected: [${f.expected.join(", ")}]`;
+      return msg;
+    });
+    throw new Error(`WESL tests failed:\n${messages.join("\n")}`);
+  }
+}
+
+/**
+ * Runs all @test functions in a WESL module.
+ * Each test function is wrapped in a compute shader and dispatched.
+ * Returns results for all tests.
+ */
+export async function runWesl(params: RunWeslParams): Promise<TestResult[]> {
+  const { testName } = params;
+  const { shaderSrc, ast } = await parseTestModule(params);
+  let testFns = findTestFunctions(ast);
+  if (testName) {
+    testFns = testFns.filter(t => t.name === testName);
+  }
+  const results: TestResult[] = [];
+  for (const testFn of testFns) {
+    results.push(await runSingleTest({ testFn, shaderSrc, ...params }));
+  }
+  return results;
+}
+
+/** Load and parse a WESL module to extract @test functions. */
+async function parseTestModule(params: {
+  src?: string;
+  moduleName?: string;
+  projectDir?: string;
+}): Promise<ParsedTestModule> {
+  const { projectDir, src, moduleName } = params;
+  const shaderSrc = await resolveShaderSource(src, moduleName, projectDir);
+  const modPath = moduleName || "test";
+  const ast = parseSrcModule({
+    modulePath: modPath,
+    debugFilePath: modPath + ".wesl",
+    src: shaderSrc,
+  });
+  return { shaderSrc, ast };
+}
+
+/** Wrap a @test function in a compute shader, dispatch it, and return results. */
+async function runSingleTest(params: RunSingleTestParams): Promise<TestResult> {
+  const { testFn, shaderSrc, device, ...rest } = params;
+  // Generate wrapper that calls the test function
+  // Call initTestResult() function to initialize the result buffer
+  const wrapper = `
+import wgsl_test::TestResult::initTestResult;
+
+${shaderSrc}
+
+@compute @workgroup_size(1)
+fn _weslTestEntry() {
+  initTestResult();
+  ${testFn.name}();
+}
+`;
+  const weslTestBundle = await getWeslTestBundle();
+  const module = await compileShader({
+    ...rest,
+    device,
+    src: wrapper,
+    libs: [weslTestBundle],
+  });
+
+  const resultElems = testResultSize / 4; // 48 bytes / 4 bytes per u32 = 12
+  const gpuResult = await runCompute({
+    device,
+    module,
+    resultFormat: "u32",
+    size: resultElems,
+    entryPoint: "_weslTestEntry",
+  });
+  const testLabel = testFn.description ?? testFn.name;
+  return parseTestResult(testLabel, gpuResult);
+}
+
+/** Lazy-load and cache the wgsl-test shader library bundle. */
+async function getWeslTestBundle(): Promise<WeslBundle> {
+  if (cachedWeslBundle) return cachedWeslBundle;
+  // Use import.meta.url to resolve the path correctly regardless of cwd
+  const bundlePath = new URL("../dist/weslBundle.js", import.meta.url).href;
+  const mod = await import(bundlePath);
+  cachedWeslBundle = mod.default;
+  return cachedWeslBundle;
+}
+
+/** Decode TestResult struct from GPU buffer (passed flag + actual/expected vec4f). */
+function parseTestResult(name: string, gpuResult: number[]): TestResult {
+  // TestResult struct layout (with vec4f 16-byte alignment):
+  // [0] passed (u32)
+  // [1] failCount (u32)
+  // [2-3] padding (8 bytes to align vec4f)
+  // [4-7] actual (vec4f)
+  // [8-11] expected (vec4f)
+  const passed = gpuResult[0] === 1;
+
+  // Reinterpret u32 bits as f32 for actual/expected (always captured now)
+  const u32Array = new Uint32Array(gpuResult.slice(4, 12));
+  const f32Array = new Float32Array(u32Array.buffer);
+  const actual = Array.from(f32Array.slice(0, 4));
+  const expected = Array.from(f32Array.slice(4, 8));
+
+  return { name, passed, actual, expected };
+}

package/src/VitestImport.ts

@@ -0,0 +1,23 @@
+/** Dynamically import vitest with helpful error if not installed. */
+export async function importVitest(): Promise<typeof import("vitest")> {
+  try {
+    return await import("vitest");
+  } catch {
+    throw new Error(
+      "This function requires vitest. Use framework-agnostic APIs like testWesl() or testFragment() instead.",
+    );
+  }
+}
+
+/** Dynamically import vitest-image-snapshot with helpful error if not installed. */
+export async function importImageSnapshot(): Promise<
+  typeof import("vitest-image-snapshot")
+> {
+  try {
+    return await import("vitest-image-snapshot");
+  } catch {
+    throw new Error(
+      "This function requires vitest-image-snapshot. Use testFragmentImage() for framework-agnostic testing.",
+    );
+  }
+}