@needle-tools/three-test-matrix

Shared infrastructure for browser compatibility tests that need to run code against several Three.js versions and renderer modes.

This is an ESM package for Node.js 18 and newer.

The package handles the repetitive parts of a Three.js matrix harness:

• resolve and cache Three.js npm tarballs
• include the current npm three latest by default
• create WebGL/WebGPU import maps for cached Three.js packages
• generate one browser page per Three.js version and renderer mode
• bundle worker test entries against a specific cached Three.js package
• cache glTF/GLB roots plus referenced buffers, textures, and progressive LOD files
• serve raw filesystem cache paths through Vite
• render a Markdown compatibility table from a JSON artifact

Assertions, fixtures, and expected support policy stay in the project using the harness.

Install

npm install --save-dev @needle-tools/three-test-matrix

Matrix Setup

Use prepareThreeMatrix when you want the standard cache, runtime, and page-generation flow:

import path from "node:path";
import {
  prepareThreeMatrix,
  rendererModes,
} from "@needle-tools/three-test-matrix";

const projectRoot = process.cwd();

const matrix = await prepareThreeMatrix({
  cwd: projectRoot,
  cacheRoot: path.join(projectRoot, ".cache", "three-test-matrix"),
  pagesRoot: path.join(projectRoot, ".cache", "three-pages"),
  rendererModes,
  createPage({ runtime, rendererMode }) {
    return renderCompatibilityPage({ runtime, rendererMode });
  },
});

console.log(matrix.versions);
console.log(matrix.pagesManifest.pages.length);

prepareThreeMatrix accepts explicit options for the common control points:

• versions: exact Three.js package versions to test
• fromRevision: latest patch version for every Three.js minor from that revision onward
• defaultVersions: fallback versions when neither versions nor fromRevision is provided
• includeLatest: append the current npm three latest, enabled by default
• cacheRoot: shared cache location
• threeCacheRoot: override only the Three.js package cache location
• rendererModes: renderer modes to generate
• refresh: re-download cached files
• includeLocalRuntime: include the locally installed three package, enabled by default

The lower-level helpers remain exported for custom harnesses: resolveRequestedVersions, cacheThreeVersions, createLocalThreeRuntime, createCachedThreeRuntime, createThreeImportMap, writeThreeMatrixPages, buildWorkerBundle, cacheModelGraph, and renderRendererMatrixMarkdown.

Cache Location

If cacheRoot is not provided, the default cache is shared on the machine:

$(npm config get cache)/_three-test-matrix

Scripts can expose their own command-line flags with parseMatrixArgs:

import {
  parseMatrixArgs,
  prepareThreeMatrix,
} from "@needle-tools/three-test-matrix";

const args = parseMatrixArgs(process.argv.slice(2));

await prepareThreeMatrix({
  cacheRoot: args.cacheRoot,
  versions: args.versions,
  fromRevision: args.fromRevision,
  refresh: args.refresh,
  createPage,
  pagesRoot,
});

Then run the script with explicit flags:

node test/cache-three-pages.mjs --cache-root .cache/three-test-matrix --versions 0.169.0,0.184.0 --refresh

Renderer Modes

The built-in renderer modes are:

• webgl
• webgpu-force-webgl2
• webgpu

createThreeImportMap(runtime, rendererMode) maps three, three/addons/, three/examples/jsm/, three/webgpu, and three/nodes to the selected cached package.

For browser runners, the package exports explicit defaults for WebGPU-capable matrix runs:

import { webgpuDefaults } from "@needle-tools/three-test-matrix";

export default defineConfig({
  use: {
    ...webgpuDefaults.playwright,
    baseURL: "http://127.0.0.1:5199",
  },
});

Vitest browser projects can use the Vitest-shaped defaults:

import webgpuBrowserDefaults from "@needle-tools/three-test-matrix/vitest";

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      ...webgpuBrowserDefaults,
    },
  },
});

The package includes a headed Chrome renderer self-test:

npm run test:browser

That test creates real Three.js renderers for every default milestone. It asserts webgpu-force-webgl2 initializes on a WebGL backend and webgpu initializes on a WebGPU backend when the browser and Three.js version support it.

Vite

Generated pages often point at files in the shared cache. Add the raw filesystem plugin to serve those files through Vite:

import { defineConfig } from "vite";
import { rawFsServePlugin } from "@needle-tools/three-test-matrix/vite";

export default defineConfig({
  plugins: [
    rawFsServePlugin({
      cacheRoots: [".cache/three-test-matrix"],
      headers: {
        "Cross-Origin-Embedder-Policy": "require-corp",
        "Cross-Origin-Opener-Policy": "same-origin",
      },
    }),
  ],
});

Publishing

Types are generated from the JavaScript sources and JSDoc comments:

npm run build

Check the package contents before publishing:

npm run publish:dry

prepack runs the type build automatically, so npm publish includes fresh dist/*.d.ts output.

Run the package type-shape check with the ESM-only ATTW profile:

npm run test:attw