vitest-environment-webgl-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Houston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# vitest-environment-webgl-node
+
+Real, headless WebGL 1 and WebGL 2 inside Vitest, with no browser. Powered by
+[`@onirenaud/node-webgl`](https://github.com/RenaudRohlinger/node-webgl) (Chrome's ANGLE, statically linked).
+
+The environment installs `window`, `document`, `HTMLCanvasElement`, `Image`, `requestAnimationFrame`,
+the `WebGL*` classes and a file-reading `fetch()` before each test file, and removes them afterwards.
+`document.createElement('canvas').getContext('webgl2')` returns a GPU-backed context, so three.js,
+regl, pixi and plain WebGL code run unchanged.
+
+## Install
+
+```sh
+pnpm add -D vitest vitest-environment-webgl-node
+```
+
+## Usage
+
+```ts
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    environment: 'webgl-node',
+    environmentOptions: { webglNode: { backend: 'swiftshader', baseDir: 'assets' } },
+  },
+});
+```
+
+```ts
+import * as THREE from 'three';
+import { expect, it } from 'vitest';
+
+it('renders', () => {
+  const canvas = document.createElement('canvas');
+  const renderer = new THREE.WebGLRenderer({ canvas });
+  renderer.setSize(64, 64, false);
+  renderer.render(new THREE.Scene(), new THREE.PerspectiveCamera());
+  expect(canvas.getImageData().width).toBe(64);
+});
+```
+
+Options are those of node-webgl's `init()` (`backend`, `api`) and `installDOM()`
+(`baseDir`, `fetch`, `devicePixelRatio`, `innerWidth`, `innerHeight`, `frameInterval`).
+Pair with [`vitest-screenshot`](../vitest-screenshot) for pixel-diff assertions.
+
+Types for the installed globals: add `import 'vitest-environment-webgl-node/globals';` to a `.d.ts` file your tsconfig includes.
+
+On Linux CI install Mesa (`apt-get install libegl1 libgles2 libgl1-mesa-dri`) and set
+`LIBGL_ALWAYS_SOFTWARE=1`. macOS and Windows use prebuilt binaries.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { type InitOptions, type InstallDOMOptions } from '@onirenaud/node-webgl';
+import type { Environment } from 'vitest/environments';
+/** Set under `test.environmentOptions.webglNode` in your Vitest config. */
+export type WebglNodeOptions = InitOptions & InstallDOMOptions;
+declare const _default: Environment;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACnG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAAC;wBAE/C,WAAW"}

package/dist/index.js

@@ -0,0 +1,28 @@
+import { init, installDOM } from '@onirenaud/node-webgl';
+export default {
+    name: 'webgl-node',
+    viteEnvironment: 'ssr',
+    setup(global, { webglNode = {} }) {
+        const { backend, api, ...dom } = webglNode;
+        if (backend || api)
+            init({ backend, api });
+        const before = new Set(Object.getOwnPropertyNames(global));
+        installDOM(dom);
+        // node-webgl's window/document have no event methods; engines like Babylon.js register resize/blur listeners.
+        const { window, document } = global;
+        for (const target of [window, document]) {
+            if (!target)
+                continue;
+            target.addEventListener ??= () => { };
+            target.removeEventListener ??= () => { };
+        }
+        const added = Object.getOwnPropertyNames(global).filter((key) => !before.has(key));
+        return {
+            teardown(g) {
+                for (const key of added)
+                    delete g[key];
+            },
+        };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAA4C,MAAM,uBAAuB,CAAC;AAMnG,eAA4B;IAC1B,IAAI,EAAE,YAAY;IAClB,eAAe,EAAE,KAAK;IACtB,KAAK,CAAC,MAAyB,EAAE,EAAE,SAAS,GAAG,EAAE,EAAoC;QACnF,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,EAAE,GAAG,SAAS,CAAC;QAC3C,IAAI,OAAO,IAAI,GAAG;YAAE,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3D,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,8GAA8G;QAC9G,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAA4D,CAAC;QAC1F,KAAK,MAAM,MAAM,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,MAAM,CAAC,gBAAgB,KAAK,GAAG,EAAE,GAAE,CAAC,CAAC;YACrC,MAAM,CAAC,mBAAmB,KAAK,GAAG,EAAE,GAAE,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACnF,OAAO;YACL,QAAQ,CAAC,CAA0B;gBACjC,KAAK,MAAM,GAAG,IAAI,KAAK;oBAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;YACzC,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}

package/globals.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Types for the globals `vitest-environment-webgl-node` installs (node-webgl's `installDOM()`).
+ * Pull in with `import 'vitest-environment-webgl-node/globals';` from a `.d.ts` your tsconfig includes.
+ */
+import type {
+  Canvas,
+  Image as NodeImage,
+  ImageBitmap as NodeImageBitmap,
+  ImageData as NodeImageData,
+  WebGL2RenderingContext as NodeWebGL2RenderingContext,
+  WebGLRenderingContext as NodeWebGLRenderingContext,
+  createImageBitmap as nodeCreateImageBitmap,
+} from '@onirenaud/node-webgl';
+
+type Listener = (type: string, listener: (event: unknown) => void, options?: unknown) => void;
+
+interface ShimDocument {
+  createElement(tag: 'canvas'): Canvas;
+  createElement(tag: 'img'): NodeImage;
+  createElement(tag: string): unknown;
+  createElementNS(namespace: string, tag: 'canvas'): Canvas;
+  createElementNS(namespace: string, tag: string): unknown;
+  addEventListener: Listener;
+  removeEventListener: Listener;
+}
+
+interface ShimWindow {
+  innerWidth: number;
+  innerHeight: number;
+  devicePixelRatio: number;
+  addEventListener: Listener;
+  removeEventListener: Listener;
+}
+
+declare global {
+  var window: ShimWindow & typeof globalThis;
+  var self: ShimWindow & typeof globalThis;
+  var document: ShimDocument;
+  var innerWidth: number;
+  var innerHeight: number;
+  var devicePixelRatio: number;
+  var HTMLCanvasElement: typeof Canvas;
+  var OffscreenCanvas: typeof Canvas;
+  var HTMLImageElement: typeof NodeImage;
+  var Image: typeof NodeImage;
+  var ImageData: typeof NodeImageData;
+  var ImageBitmap: typeof NodeImageBitmap;
+  var createImageBitmap: typeof nodeCreateImageBitmap;
+  var WebGLRenderingContext: typeof NodeWebGLRenderingContext;
+  var WebGL2RenderingContext: typeof NodeWebGL2RenderingContext;
+  function requestAnimationFrame(callback: (time: number) => void): number;
+  function cancelAnimationFrame(handle: number): void;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "vitest-environment-webgl-node",
+  "version": "0.1.0",
+  "description": "Vitest environment that provides real headless WebGL 1/2 (ANGLE via @onirenaud/node-webgl) in Node",
+  "keywords": [
+    "headless",
+    "testing",
+    "three.js",
+    "vitest",
+    "vitest-environment",
+    "webgl",
+    "webgl2"
+  ],
+  "homepage": "https://github.com/bhouston/vitest-gpu#readme",
+  "bugs": {
+    "url": "https://github.com/bhouston/vitest-gpu/issues"
+  },
+  "license": "MIT",
+  "author": "Ben Houston <ben@ben3d.ca> (https://ben3d.ca)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhouston/vitest-gpu.git",
+    "directory": "packages/vitest-environment-webgl-node"
+  },
+  "files": [
+    "globals.d.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./globals": {
+      "types": "./globals.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "tsc": "tsc -b"
+  },
+  "dependencies": {
+    "@onirenaud/node-webgl": "^0.2.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=3 <5"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}