wgsl-test 0.2.5 → 0.2.6

package/README.md

@@ -1,10 +1,9 @@
 # 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 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
+- **Native WESL** (`@test`) - Unit test shader functions, assertions run on GPU
+- **TypeScript-driven** - Integration tests, visual regression, custom validation
 
 ## Installation
 
@@ -12,17 +11,42 @@ Write GPU shader tests as easily as regular unit tests. Test WGSL and WESL shade
 npm install wgsl-test
 ```
 
-Quick start in 3 steps:
+## Native WESL Testing
 
-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
+Write tests directly in WESL with the `@test` attribute. No boilerplate, assertions run on the GPU:
 
-## Testing Compute Shaders
+```wgsl
+// luminance_test.wesl
+import lygia::color::luminance::luminance;
+import wgsl_test::expectNear;
+
+@test fn luminanceOrange() {
+  expectNear(luminance(vec3f(1.0, 0.5, 0.0)), 0.5702);
+}
+
+@test fn luminanceWhite() {
+  expectNear(luminance(vec3f(1.0, 1.0, 1.0)), 1.0);
+}
+```
+
+Run with a minimal TypeScript wrapper:
+
+```typescript
+import { expectWesl, getGPUDevice } from "wgsl-test";
+
+test("luminance", async () => {
+  const device = await getGPUDevice();
+  await expectWesl({ device, moduleName: "luminance_test" });
+});
+```
 
-The default choice for unit testing shader functions. Flexible and explicit.
+Use `runWesl()` instead if you need to inspect individual test results.
 
-Use `testCompute()` to test compute shader logic. A `test::results` buffer is automatically provided:
+**[See API.md for assertion functions →](https://github.com/wgsl-tooling-wg/wesl-js/blob/main/tools/packages/wgsl-test/API.md#assertion-functions)**
+
+## Testing Compute Shaders
+
+For more control, use `testCompute()` directly. A `test::results` buffer is automatically provided:
 
 ```typescript
 import { testCompute, getGPUDevice } from "wgsl-test";
@@ -47,7 +71,7 @@ const result = await testCompute({ device, src, size: 2 });
 
 ## Testing Fragment Shaders
 
-For unit testing shader functions that only run in fragment shaders. Tests a single pixel output.
+Some functions only make sense in fragment shaders. 
 
 Use `testFragment()` to test fragment shader rendering. 
 
@@ -102,10 +126,8 @@ Snapshot comparison automatically detects rendering changes. Update snapshots wi
 - **[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 
+## 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

@@ -1,5 +1,5 @@
 import { DeviceCache, FragmentRenderParams, RenderUniforms, SamplerOptions, WeslOptions, checkerboardTexture, colorBarsTexture, createSampler, createUniformsVirtualLib, edgePatternTexture, fullscreenTriangleVertex, gradientTexture, noiseTexture, radialGradientTexture, renderUniformBuffer, simpleRender, solidTexture, updateRenderUniforms, withErrorScopes } from "wesl-gpu";
-import { LinkParams, ModuleResolver, WeslBundle } from "wesl";
+import { FnElem, LinkParams, ModuleResolver, WeslAST, WeslBundle } from "wesl";
 import { WgslElementType, WgslElementType as WgslElementType$1 } from "thimbleberry";
 import { ImageData, ImageData as ImageData$1, MatchImageOptions } from "vitest-image-snapshot";
 
@@ -19,6 +19,8 @@ interface ResolveContextParams {
   projectDir?: string;
   /** Use source shaders instead of built bundles. Default: true. */
   useSourceShaders?: boolean;
+  /** Virtual lib names to exclude from dependency resolution. */
+  virtualLibNames?: string[];
 }
 interface CompileShaderParams {
   /** Project directory for resolving shader dependencies.
@@ -38,6 +40,12 @@ interface CompileShaderParams {
   /** Virtual libraries to include in the shader.
    * 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.
@@ -112,6 +120,14 @@ interface ComputeTestParams {
    * Can be a single number or [x, y, z] for multi-dimensional dispatch. */
   dispatchWorkgroups?: number | [number, number, number];
 }
+interface RunComputeParams {
+  device: GPUDevice;
+  module: GPUShaderModule;
+  resultFormat?: WgslElementType$1;
+  size?: number;
+  dispatchWorkgroups?: number | [number, number, number];
+  entryPoint?: string;
+}
 /**
  * Compiles and runs a compute shader on the GPU for testing.
  *
@@ -130,14 +146,17 @@ declare function testCompute(params: ComputeTestParams): Promise<number[]>;
  * 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[]>;
+declare function runCompute(params: RunComputeParams): Promise<number[]>;
+//#endregion
+//#region src/TestDiscovery.d.ts
+interface TestFunctionInfo {
+  name: string;
+  description?: string;
+  fn: FnElem;
+}
+/** Find all functions marked with @test attribute in a parsed WESL module. */
+declare function findTestFunctions(ast: WeslAST): TestFunctionInfo[];
 //#endregion
 //#region src/TestFragmentShader.d.ts
 interface FragmentTestParams extends WeslOptions, FragmentRenderParams {
@@ -188,9 +207,53 @@ declare function testFragment(params: FragmentTestParams): Promise<number[]>;
  */
 declare function testFragmentImage(params: FragmentTestParams): Promise<ImageData$1>;
 //#endregion
+//#region src/TestVirtualLib.d.ts
+/** Size of TestResult struct in bytes.
+ * Layout: u32 passed (4) + u32 failCount (4) + padding (8) + vec4f actual (16) + vec4f expected (16) = 48 */
+declare const testResultSize = 48;
+/** Virtual library for test:: namespace providing assertions and result reporting. */
+declare function testVirtualLib(): string;
+//#endregion
+//#region src/TestWesl.d.ts
+/** Parameters for running @test functions in a WESL module. */
+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. */
+interface TestResult {
+  name: string;
+  passed: boolean;
+  actual: number[];
+  expected: number[];
+}
+/** Parameters for testWesl() which registers all @test functions with vitest. */
+type TestWeslParams = Omit<RunWeslParams, "testName">;
+/**
+ * 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.
+ */
+declare function testWesl(params: TestWeslParams): Promise<void>;
+/**
+ * Runs all @test functions and asserts they pass.
+ * Throws descriptive error on failure showing test name and actual/expected values.
+ */
+declare function expectWesl(params: RunWeslParams): Promise<void>;
+/**
+ * Runs all @test functions in a WESL module.
+ * Each test function is wrapped in a compute shader and dispatched.
+ * Returns results for all tests.
+ */
+declare function runWesl(params: RunWeslParams): Promise<TestResult[]>;
+//#endregion
 //#region src/WebGPUTestSetup.d.ts
+declare const isDeno: boolean;
 /** get or create shared GPU device for testing */
 declare function getGPUDevice(): Promise<GPUDevice>;
+/** get or create shared GPU object for testing */
+declare function getGPU(): Promise<GPU>;
+/** get or create shared GPU adapter for testing */
+declare function getGPUAdapter(): Promise<GPUAdapter>;
 /** destroy globally shared GPU test device */
 declare function destroySharedDevice(): void;
 //#endregion
@@ -201,5 +264,5 @@ declare module "vitest" {
   }
 }
 //#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 };
+export { CompileShaderParams, ComputeTestParams, DeviceCache, FragmentImageTestParams, FragmentTestParams, type ImageData, type RenderUniforms, ResolveContextParams, RunComputeParams, RunWeslParams, type SamplerOptions, ShaderContext, TestFunctionInfo, TestResult, TestWeslParams, type WgslElementType, checkerboardTexture, colorBarsTexture, compileShader, createProjectResolver, createSampler, createUniformsVirtualLib, destroySharedDevice, edgePatternTexture, expectFragmentImage, expectWesl, findTestFunctions, fullscreenTriangleVertex, getGPU, getGPUAdapter, getGPUDevice, gradientTexture, isDeno, lemurImagePath, lemurTexture, noiseTexture, pngToTexture, radialGradientTexture, renderUniformBuffer, resolveShaderContext, runCompute, runWesl, simpleRender, solidTexture, testCompute, testFragment, testFragmentImage, testResultSize, testVirtualLib, testWesl, updateRenderUniforms, withErrorScopes };
 //# sourceMappingURL=index.d.ts.map