vitest-environment-webgpu-node 2.0.1 → 3.0.1

package/README.md

@@ -3,13 +3,37 @@
 [![npm version][npm-badge]][npm-url]
 [![npm downloads][downloads-badge]][npm-url]
 [![Tests][tests-badge]][tests-url]
+[![Coverage][coverage-badge]][coverage-url]
 [![Discord][discord-badge]][discord-url]
 
-Real, headless WebGPU inside Vitest, with no browser. Native GPU testing is up to 2.4x faster
-than running the same tests in a browser — see the
-[blog post](https://ben3d.ca/blog/native-gpu-testing-for-vitest-and-jest) for details.
-Powered by Google's Dawn through the
-[`webgpu`](https://github.com/dawn-gpu/node-webgpu) npm package.
+Run real WebGPU tests in Vitest on Node, without a browser, Playwright or mocks. Headless GPU testing
+for CI: `navigator.gpu` is backed by Google's Dawn through the
+[`webgpu`](https://github.com/dawn-gpu/node-webgpu) npm package. Native GPU testing is up to 2.4x faster
+than running the same tests in a browser, see the
+[blog post](https://ben3d.ca/blog/native-gpu-testing-for-vitest-and-jest).
+
+```sh
+pnpm add -D vitest vitest-environment-webgpu-node
+```
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({ test: { environment: 'webgpu-node' } });
+```
+
+```ts
+// gpu.test.ts
+import { expect, it } from 'vitest';
+
+it('has a real GPU device', async () => {
+  const adapter = await navigator.gpu.requestAdapter();
+  const device = await adapter!.requestDevice();
+  const buffer = device.createBuffer({ size: 16, usage: GPUBufferUsage.COPY_DST });
+  expect(buffer.size).toBe(16);
+});
+```
 
 The environment puts `navigator.gpu` and every `GPU*` class and constant (`GPUBufferUsage`,
 `GPUShaderStage`, ...) on the global object before each test file and removes them afterwards.
@@ -18,13 +42,30 @@ Using Jest instead? See the equivalent
 [`jest-environment-webgpu-node`](https://github.com/bhouston/jest-gpu/tree/main/packages/jest-environment-webgpu-node)
 in [jest-gpu](https://github.com/bhouston/jest-gpu).
 
-## Install
+## Compared to alternatives
 
-```sh
-pnpm add -D vitest vitest-environment-webgpu-node
-```
+WebGPU has no mock equivalent of a canvas stub that runs shaders, so the realistic options are a browser or
+Dawn in Node.
+
+| Approach                          | Real rendering | Notes                                                                                                         |
+| --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- |
+| Hand-written `navigator.gpu` mock | No             | You can assert calls, not shader output or readbacks.                                                         |
+| Vitest browser mode or Playwright | Yes            | A real browser with WebGPU enabled: heavier to install and slower to start; right when you need browser APIs. |
+| vitest-environment-webgpu-node    | Yes            | Dawn in the Node process (Metal, Vulkan, D3D12 and others via `dawnOptions`). Not a browser.                  |
+
+## Supported versions and platforms
+
+- Vitest 4 and 5 (CI tests both). Vitest 3 is not supported.
+- Node 22 or later. CI runs Node 22 and 26 on `macos-latest` and `ubuntu-latest`.
+- Type checking needs TypeScript 6 or later (see [TypeScript types](#typescript-types)).
+- Linux without a GPU needs Mesa's software Vulkan driver, see [Linux and CI](#linux-and-ci). This repo's CI does
+  not run on Windows.
 
-Type checking needs TypeScript 6 or later (see [TypeScript types](#typescript-types)).
+## Useful for
+
+three.js `WebGPURenderer`, Babylon Lite, Vercel's vgpu and raw WebGPU compute or render code. The demos exercise
+those three; other WebGPU libraries such as TypeGPU or luma.gl use the same API but are not covered by this
+repo's tests. These are compatible use cases, not endorsements.
 
 ## Usage
 
@@ -77,7 +118,7 @@ sudo apt-get update && sudo apt-get install -y libegl1 libgles2 libgl1-mesa-dri
 export LIBGL_ALWAYS_SOFTWARE=1
 ```
 
-This repo's own [CI workflow](../../.github/workflows/ci.yml) does exactly this, so WebGPU tests run
+This repo's own [CI workflow](https://github.com/bhouston/vitest-gpu/blob/main/.github/workflows/ci.yml) does exactly this, so WebGPU tests run
 for real (not mocked) on `ubuntu-latest` on every PR. macOS runners use Dawn's Metal backend and need no
 extra setup.
 
@@ -100,12 +141,24 @@ await expect(canvas).toMatchScreenshot('scene.png');
 ```
 
 `readPixels()` returns `{ width, height, data }` RGBA8 pixels, ready for
-[`vitest-screenshot`](../vitest-screenshot). Readback supports `rgba8unorm`, `rgba8unorm-srgb`,
+[`vitest-screenshot`](https://github.com/bhouston/vitest-gpu/tree/main/packages/vitest-screenshot). Readback supports `rgba8unorm`, `rgba8unorm-srgb`,
 `bgra8unorm`, and `bgra8unorm-srgb`; other canvas formats remain valid for rendering but
 `readPixels()` rejects them with an unsupported-format error. `asElement()` returns the same object and
 defaults to `HTMLCanvasElement` when DOM types are available. You can also request a library-specific type
 explicitly with `canvas.asElement<HTMLCanvasElement>()`.
 
+## Image snapshots
+
+`await expect(canvas).toMatchScreenshot('scene.png')` comes from [`vitest-screenshot`](https://github.com/bhouston/vitest-gpu/tree/main/packages/vitest-screenshot).
+Call `extendMatchers()` from it once, then pass the canvas as in the example above.
+
+## See also
+
+- [`vitest-environment-webgl-node`](https://github.com/bhouston/vitest-gpu/tree/main/packages/vitest-environment-webgl-node) for headless WebGL.
+- [`vitest-screenshot`](https://github.com/bhouston/vitest-gpu/tree/main/packages/vitest-screenshot) for `toMatchScreenshot()`.
+- [`demo/`](https://github.com/bhouston/vitest-gpu/tree/main/demo/test/webgpu) for device, upload, readback, triangle, three.js, Babylon Lite and vgpu tests,
+  and the [repository README](https://github.com/bhouston/vitest-gpu#readme).
+
 ## Author
 
 Created by [Ben Houston](https://ben3d.ca) and sponsored by [Land of Assets](https://landofassets.com).
@@ -121,3 +174,9 @@ MIT
 [tests-url]: https://github.com/bhouston/vitest-gpu/actions/workflows/ci.yml
 [discord-badge]: https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white
 [discord-url]: https://discord.gg/fwupDN493R
+[coverage-badge]: https://codecov.io/gh/bhouston/vitest-gpu/branch/main/graph/badge.svg
+[coverage-url]: https://codecov.io/gh/bhouston/vitest-gpu
+
+## Resource cleanup
+
+Environment teardown destroys devices requested through its `navigator.gpu` and cancels pending callbacks scheduled through its animation-frame shim. Device requests that finish after teardown are destroyed and rejected. Devices created through another GPU instance remain the caller's responsibility. Keep disposing renderers, buffers, textures and devices during long-running files to release resources sooner.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAElG,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;;;;kBAyCc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAuB;QAAE,UAAU,CAAC,EAAE,iBAAiB,CAAA;KAAE;2BA8BvE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAElG,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;;;;kBA2Dc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAuB;QAAE,UAAU,CAAC,EAAE,iBAAiB,CAAA;KAAE;2BA4DvE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}

package/dist/index.js

@@ -1,17 +1,38 @@
 import { create, globals } from 'webgpu';
 import { HeadlessCanvas } from './canvas.js';
 export { createCanvas, HeadlessCanvas, HeadlessCanvasContext } from './canvas.js';
-/** Just enough DOM for libraries that make their own canvas and drive a frame loop. Only installed when missing. */
-const requestAnimationFrame = (callback) => setTimeout(() => callback(performance.now()), 16).unref();
+/** Each environment owns its frame callbacks; unref alone does not release them. */
 const domShims = () => {
+    const frames = new Set();
+    let disposed = false;
+    const requestAnimationFrame = (callback) => {
+        if (disposed)
+            return 0;
+        const frame = setTimeout(() => {
+            frames.delete(frame);
+            callback(performance.now());
+        }, 16).unref();
+        frames.add(frame);
+        return frame;
+    };
+    const cancelAnimationFrame = (frame) => {
+        frames.delete(frame);
+        clearTimeout(frame);
+    };
+    const dispose = () => {
+        disposed = true;
+        for (const frame of frames)
+            clearTimeout(frame);
+        frames.clear();
+    };
     const window = {
         devicePixelRatio: 1,
         requestAnimationFrame,
-        cancelAnimationFrame: clearTimeout,
+        cancelAnimationFrame,
         addEventListener() { },
         removeEventListener() { },
     };
-    return {
+    const shims = {
         HTMLCanvasElement: HeadlessCanvas,
         document: {
             createElement: (tag) => (tag === 'canvas' ? new HeadlessCanvas() : {}),
@@ -22,8 +43,9 @@ const domShims = () => {
         window,
         self: window,
         requestAnimationFrame,
-        cancelAnimationFrame: clearTimeout,
+        cancelAnimationFrame,
     };
+    return { shims, dispose };
 };
 const restore = (properties) => {
     for (const { target, key, descriptor } of properties.toReversed()) {
@@ -37,7 +59,17 @@ export default {
     name: 'webgpu-node',
     viteEnvironment: 'ssr',
     setup(global, { webgpuNode = {} }) {
-        const shims = { ...globals, ...domShims() };
+        const dom = domShims();
+        const shims = { ...globals, ...dom.shims };
+        const devices = new Set();
+        let disposed = false;
+        const dispose = () => {
+            disposed = true;
+            dom.dispose();
+            for (const device of devices)
+                device.destroy();
+            devices.clear();
+        };
         const modified = [];
         try {
             for (const key of Object.keys(shims)) {
@@ -56,20 +88,51 @@ export default {
             }
             const navigator = global.navigator;
             modified.push({ target: navigator, key: 'gpu', descriptor: Object.getOwnPropertyDescriptor(navigator, 'gpu') });
+            const gpu = create(webgpuNode.dawnOptions ?? []);
+            const requestAdapter = gpu.requestAdapter.bind(gpu);
+            gpu.requestAdapter = async (options) => {
+                if (disposed)
+                    throw new Error('WebGPU environment has been torn down');
+                const adapter = await requestAdapter(options);
+                if (adapter) {
+                    const requestDevice = adapter.requestDevice.bind(adapter);
+                    adapter.requestDevice = async (descriptor) => {
+                        if (disposed)
+                            throw new Error('WebGPU environment has been torn down');
+                        const device = await requestDevice(descriptor);
+                        if (disposed) {
+                            device.destroy();
+                            throw new Error('WebGPU environment has been torn down');
+                        }
+                        devices.add(device);
+                        return device;
+                    };
+                }
+                return adapter;
+            };
             Object.defineProperty(navigator, 'gpu', {
-                value: create(webgpuNode.dawnOptions ?? []),
+                value: gpu,
                 writable: false,
                 enumerable: false,
                 configurable: true,
             });
         }
         catch (error) {
+            dispose();
             restore(modified);
             throw error;
         }
         return {
             teardown(_global) {
-                restore(modified);
+                if (disposed)
+                    return;
+                try {
+                    dispose();
+                }
+                finally {
+                    restore(modified);
+                    modified.length = 0;
+                }
             },
         };
     },

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAkB,MAAM,aAAa,CAAC;AAQlG,oHAAoH;AACpH,MAAM,qBAAqB,GAAG,CAAC,QAAgC,EAAkB,EAAE,CACjF,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;AAE5D,MAAM,QAAQ,GAAG,GAA4B,EAAE;IAC7C,MAAM,MAAM,GAAG;QACb,gBAAgB,EAAE,CAAC;QACnB,qBAAqB;QACrB,oBAAoB,EAAE,YAAY;QAClC,gBAAgB,KAAI,CAAC;QACrB,mBAAmB,KAAI,CAAC;KACzB,CAAC;IACF,OAAO;QACL,iBAAiB,EAAE,cAAc;QACjC,QAAQ,EAAE;YACR,aAAa,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,eAAe,EAAE,CAAC,GAAW,EAAE,GAAW,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7F,gBAAgB,KAAI,CAAC;YACrB,mBAAmB,KAAI,CAAC;SACzB;QACD,MAAM;QACN,IAAI,EAAE,MAAM;QACZ,qBAAqB;QACrB,oBAAoB,EAAE,YAAY;KACnC,CAAC;AACJ,CAAC,CAAC;AAIF,MAAM,OAAO,GAAG,CAAC,UAA2B,EAAQ,EAAE;IACpD,KAAK,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,UAAU,CAAC,UAAU,EAAE,EAAE,CAAC;QAClE,IAAI,UAAU;YAAE,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;;YAC1D,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC,CAAC;AAEF,eAAe;IACb,IAAI,EAAE,aAAa;IACnB,eAAe,EAAE,KAAK;IACtB,KAAK,CAAC,MAA+B,EAAE,EAAE,UAAU,GAAG,EAAE,EAAsC;QAC5F,MAAM,KAAK,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,QAAQ,EAAE,EAA6B,CAAC;QACvE,MAAM,QAAQ,GAAoB,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrC,IAAI,GAAG,IAAI,MAAM;oBAAE,SAAS;gBAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;gBACjG,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;YACD,IAAI,MAAM,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;gBAC7B,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,MAAM;oBACd,GAAG,EAAE,WAAW;oBAChB,UAAU,EAAE,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,WAAW,CAAC;iBACjE,CAAC,CAAC;gBACH,MAAM,CAAC,SAAS,GAAG,EAAE,CAAC;YACxB,CAAC;YACD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAmB,CAAC;YAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,wBAAwB,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;YAChH,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,KAAK,EAAE;gBACtC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,WAAW,IAAI,EAAE,CAAC;gBAC3C,QAAQ,EAAE,KAAK;gBACf,UAAU,EAAE,KAAK;gBACjB,YAAY,EAAE,IAAI;aACnB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,QAAQ,CAAC,CAAC;YAClB,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO;YACL,QAAQ,CAAC,OAAiC;gBACxC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACpB,CAAC;SACF,CAAC;IACJ,CAAC;CACoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "vitest-environment-webgpu-node",
-  "version": "2.0.1",
-  "description": "Vitest environment that provides real headless WebGPU (Dawn via the webgpu package) in Node",
+  "version": "3.0.1",
+  "description": "Vitest environment for real headless WebGPU tests in Node (Dawn via the webgpu package): no browser, Playwright or mocks",
   "keywords": [
+    "ci",
+    "compute-shader",
     "dawn",
+    "gpu",
+    "gpu-testing",
     "headless",
+    "node",
     "testing",
+    "three.js",
     "vitest",
     "vitest-environment",
-    "webgpu"
+    "webgpu",
+    "webgpu-testing",
+    "wgsl"
   ],
   "homepage": "https://github.com/bhouston/vitest-gpu#readme",
   "bugs": {
@@ -27,8 +35,7 @@
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
     "src/**/*.ts",
-    "!src/**/*.test.ts",
-    "CHANGELOG.md"
+    "!src/**/*.test.ts"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -42,16 +49,12 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc",
-    "tsc": "tsc"
-  },
   "dependencies": {
     "webgpu": "^0.6.1"
   },
   "peerDependencies": {
     "typescript": ">=6",
-    "vitest": ">=3 <5"
+    "vitest": ">=4 <6"
   },
   "peerDependenciesMeta": {
     "typescript": {
@@ -59,6 +62,10 @@
     }
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "tsc": "tsc"
   }
-}
+}

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { Environment } from 'vitest/environments';
+import type { Environment } from 'vitest/runtime';
 import { create, globals } from 'webgpu';
 import { HeadlessCanvas } from './canvas.js';
 
@@ -10,19 +10,36 @@ export type WebgpuNodeOptions = {
   dawnOptions?: string[];
 };
 
-/** Just enough DOM for libraries that make their own canvas and drive a frame loop. Only installed when missing. */
-const requestAnimationFrame = (callback: (time: number) => void): NodeJS.Timeout =>
-  setTimeout(() => callback(performance.now()), 16).unref();
-
-const domShims = (): Record<string, unknown> => {
+/** Each environment owns its frame callbacks; unref alone does not release them. */
+const domShims = () => {
+  const frames = new Set<NodeJS.Timeout>();
+  let disposed = false;
+  const requestAnimationFrame = (callback: (time: number) => void): NodeJS.Timeout | number => {
+    if (disposed) return 0;
+    const frame = setTimeout(() => {
+      frames.delete(frame);
+      callback(performance.now());
+    }, 16).unref();
+    frames.add(frame);
+    return frame;
+  };
+  const cancelAnimationFrame = (frame: NodeJS.Timeout) => {
+    frames.delete(frame);
+    clearTimeout(frame);
+  };
+  const dispose = () => {
+    disposed = true;
+    for (const frame of frames) clearTimeout(frame);
+    frames.clear();
+  };
   const window = {
     devicePixelRatio: 1,
     requestAnimationFrame,
-    cancelAnimationFrame: clearTimeout,
+    cancelAnimationFrame,
     addEventListener() {},
     removeEventListener() {},
   };
-  return {
+  const shims = {
     HTMLCanvasElement: HeadlessCanvas,
     document: {
       createElement: (tag: string) => (tag === 'canvas' ? new HeadlessCanvas() : {}),
@@ -33,8 +50,9 @@ const domShims = (): Record<string, unknown> => {
     window,
     self: window,
     requestAnimationFrame,
-    cancelAnimationFrame: clearTimeout,
+    cancelAnimationFrame,
   };
+  return { shims, dispose };
 };
 
 type SavedProperty = { target: object; key: PropertyKey; descriptor?: PropertyDescriptor };
@@ -50,7 +68,16 @@ export default {
   name: 'webgpu-node',
   viteEnvironment: 'ssr',
   setup(global: Record<string, unknown>, { webgpuNode = {} }: { webgpuNode?: WebgpuNodeOptions }) {
-    const shims = { ...globals, ...domShims() } as Record<string, unknown>;
+    const dom = domShims();
+    const shims = { ...globals, ...dom.shims } as Record<string, unknown>;
+    const devices = new Set<GPUDevice>();
+    let disposed = false;
+    const dispose = () => {
+      disposed = true;
+      dom.dispose();
+      for (const device of devices) device.destroy();
+      devices.clear();
+    };
     const modified: SavedProperty[] = [];
     try {
       for (const key of Object.keys(shims)) {
@@ -68,19 +95,46 @@ export default {
       }
       const navigator = global.navigator as object;
       modified.push({ target: navigator, key: 'gpu', descriptor: Object.getOwnPropertyDescriptor(navigator, 'gpu') });
+      const gpu = create(webgpuNode.dawnOptions ?? []);
+      const requestAdapter = gpu.requestAdapter.bind(gpu);
+      gpu.requestAdapter = async (options) => {
+        if (disposed) throw new Error('WebGPU environment has been torn down');
+        const adapter = await requestAdapter(options);
+        if (adapter) {
+          const requestDevice = adapter.requestDevice.bind(adapter);
+          adapter.requestDevice = async (descriptor) => {
+            if (disposed) throw new Error('WebGPU environment has been torn down');
+            const device = await requestDevice(descriptor);
+            if (disposed) {
+              device.destroy();
+              throw new Error('WebGPU environment has been torn down');
+            }
+            devices.add(device);
+            return device;
+          };
+        }
+        return adapter;
+      };
       Object.defineProperty(navigator, 'gpu', {
-        value: create(webgpuNode.dawnOptions ?? []),
+        value: gpu,
         writable: false,
         enumerable: false,
         configurable: true,
       });
     } catch (error) {
+      dispose();
       restore(modified);
       throw error;
     }
     return {
       teardown(_global?: Record<string, unknown>) {
-        restore(modified);
+        if (disposed) return;
+        try {
+          dispose();
+        } finally {
+          restore(modified);
+          modified.length = 0;
+        }
       },
     };
   },

package/CHANGELOG.md

@@ -1,5 +0,0 @@
-## [vitest-environment-webgpu-node-v2.0.1](https://github.com/bhouston/vitest-gpu/compare/vitest-environment-webgpu-node-v2.0.0...vitest-environment-webgpu-node-v2.0.1) (2026-09-25)
-
-### Bug Fixes
-
-* drop deprecated transformMode from GPU environments ([28f736a](https://github.com/bhouston/vitest-gpu/commit/28f736ad629a2a3ca023839cadce460d0d5c6937)), closes [#54](https://github.com/bhouston/vitest-gpu/issues/54)