chore(test): vitest migration

.eslintignore

@@ -11,4 +11,6 @@ mapbox-gl.js
 .docusaurus
 examples/layer-browser/
 test/apps/
-bindings/
+bindings/
+# TODO: Remove once eslint-plugin-import supports vite 5.x (vitest brings vite 5.x, master uses 4.x)
+examples/vite.config.local.mjs

.eslintrc.cjs

@@ -94,6 +94,8 @@ module.exports = getESLintConfig({
           '**/test/**/*.ts',
           '**/scripts/**/*.js',
           '*.config.js',
+          '*.config.ts',
+          '*.workspace.ts',
           '*.config.local.js',
           '*.config.local.mjs'
         ],

.github/workflows/test.yml

@@ -35,17 +35,41 @@ jobs:
       - name: Build packages
         run: yarn build
 
-      - name: Run tests
-        run: |
-          yarn lint
-          yarn test ci
+      - name: Install Playwright browsers
+        run: npx playwright install chromium
+
+      - name: Lint
+        run: yarn lint
+
+      - name: Run Node tests
+        run: npx vitest run --project node --silent
 
-      - name: Coveralls
-        uses: coverallsapp/github-action@648a8eb78e6d50909eff900e4ec85cab4524a45b # v2.3.6
+      - name: Run Headless browser tests
+        run: npx vitest run --project headless --silent
+
+      - name: Run Render/Interaction tests
+        run: yarn test-render
+
+      - name: Upload render test failure images
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          fail-on-error: false
-
+          name: render-test-failures
+          path: |
+            test/render/golden-images/*-fail.png
+            test/render/golden-images/*-diff.png
+          if-no-files-found: ignore
+          retention-days: 7
+
+      - name: Run tape backward compatibility smoke test
+        run: yarn test-tape-compat
+
+      # TODO: Re-enable coverage once all tests run in a single vitest invocation
+      # - name: Coveralls
+      #   uses: coverallsapp/github-action@648a8eb78e6d50909eff900e4ec85cab4524a45b # v2.3.6
+      #   with:
+      #     github-token: ${{ secrets.GITHUB_TOKEN }}
+
   test-website:
     runs-on: ubuntu-22.04
     permissions:

.gitignore

@@ -4,6 +4,7 @@ dist/
 node_modules/
 coverage/
 test/**/*-failed.png
+test/**/__screenshots__/
 .nyc_output/
 .reify-cache/
 

.ocularrc.js

@@ -49,8 +49,10 @@ const config = {
   },
 
   entry: {
-    test: 'test/node.ts',
-    'test-browser': 'index.html',
+    // Tests now use vitest (yarn test, yarn test-headless, yarn test-render)
+    // Only tape-compat smoke test still uses ocular-test for backward compatibility testing
+    'tape-compat': 'test/smoke/tape-compat.ts',
+    // TODO: Migrate bench and size to vitest (Phase 7)
     bench: 'test/bench/index.js',
     'bench-browser': 'test/bench/browser.html',
     size: 'test/size/import-nothing.js'

CONTRIBUTING.md

@@ -18,6 +18,30 @@ yarn bootstrap
 yarn test
 ```
 
+## Running Tests
+
+deck.gl uses [Vitest](https://vitest.dev/) with browser mode for testing. Tests are organized into three projects:
+
+| Command | Description | Use Case |
+|---------|-------------|----------|
+| `yarn test` | Full test suite (node + headless browser + render tests) | CI validation |
+| `yarn test-fast` | Lint + node smoke tests only | Pre-commit hook (fast) |
+| `yarn test-headless` | Browser unit tests in headless Chromium | Quick browser test validation |
+| `yarn test-browser` | Browser tests in headed Chromium + render tests | Local debugging with visible browser |
+| `yarn test-ci` | Full suite with coverage | CI pipeline |
+
+### Test Projects
+
+- **node**: Fast smoke tests (`*.node.spec.ts`) - ~15 tests, runs in Node.js
+- **headless**: Full unit tests (~618 tests) - runs in headless Chromium via Playwright
+- **browser**: Same as headless but with visible browser window - useful for debugging but resource-intensive
+
+### Notes
+
+- The `test-browser` command runs in headed mode which consumes more resources. If tests timeout or fail to collect, use `test-headless` instead.
+- Pre-commit hooks run `test-fast` for quick validation. Full test suite runs in CI.
+- Render and interaction tests use golden image comparison and require the Playwright browser to be installed (`npx playwright install chromium`).
+
 See [additional instructions](#troubleshooting) for Windows, Linux and Apple M1.
 
 Run the website:

modules/test-utils/package.json

@@ -25,6 +25,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./vitest": {
+      "types": "./dist/vitest.d.ts",
+      "import": "./dist/vitest.js",
+      "require": "./dist/vitest.cjs"
     }
   },
   "files": [
@@ -39,7 +44,13 @@
     "@deck.gl/core": "~9.2.0",
     "@luma.gl/core": "~9.2.6",
     "@luma.gl/engine": "~9.2.6",
-    "@probe.gl/test-utils": "^4.1.1"
+    "@probe.gl/test-utils": "^4.1.1",
+    "vitest": "^2.1.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
   },
   "gitHead": "13ace64fc2cee08c133afc882fc307253489a4e4"
 }

modules/test-utils/src/generate-layer-tests.ts

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+// TODO: Refactor to use vitest's test.each() so each test case becomes a separate
+// vitest test. This would allow vitest to show individual test case names in output
+// instead of running all cases inside a single test() block. Currently test case
+// titles are only visible via console.log() in onBeforeUpdate callbacks.
+
 import {_count as count, Layer} from '@deck.gl/core';
 
 import type {DefaultProps} from '@deck.gl/core';

modules/test-utils/src/globals.d.ts

@@ -0,0 +1,42 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Type declarations for browser test driver functions injected by @probe.gl/test-utils
+
+interface BrowserTestDriverDiffOptions {
+  goldenImage: string;
+  region?: {x: number; y: number; width: number; height: number};
+  saveOnFail?: boolean;
+  saveAs?: string;
+  threshold?: number;
+  createDiffImage?: boolean;
+  tolerance?: number;
+  includeAA?: boolean;
+  includeEmpty?: boolean;
+  platform?: string;
+}
+
+interface BrowserTestDriverDiffResult {
+  headless: boolean;
+  match: string | number;
+  matchPercentage: string;
+  success: boolean;
+  error: Error | string | null;
+}
+
+interface BrowserTestDriverInputEvent {
+  type: string;
+  [key: string]: any;
+}
+
+declare global {
+  interface Window {
+    browserTestDriver_emulateInput(event: BrowserTestDriverInputEvent): Promise<void>;
+    browserTestDriver_captureAndDiffScreen(
+      options: BrowserTestDriverDiffOptions
+    ): Promise<BrowserTestDriverDiffResult>;
+  }
+}
+
+export {};

modules/test-utils/src/index.ts

@@ -7,12 +7,8 @@ export {toLowPrecision} from './utils/precision';
 export {gl, device} from './utils/setup-gl';
 
 // Utilities for update tests (lifecycle tests)
-export {
-  testLayer,
-  testLayerAsync,
-  testInitializeLayer,
-  testInitializeLayerAsync
-} from './lifecycle-test';
+// Uses ./tape which wraps ./lifecycle-test with @probe.gl/test-utils default
+export {testLayer, testLayerAsync, testInitializeLayer, testInitializeLayerAsync} from './tape';
 export {generateLayerTests} from './generate-layer-tests';
 
 // Basic utility for rendering multiple scenes (could go into "deck.gl/core")
@@ -23,6 +19,6 @@ export {SnapshotTestRunner} from './snapshot-test-runner';
 // A utility that emulates input events
 export {InteractionTestRunner} from './interaction-test-runner';
 
-export type {LayerTestCase} from './lifecycle-test';
+export type {LayerTestCase} from './tape';
 export type {SnapshotTestCase} from './snapshot-test-runner';
 export type {InteractionTestCase} from './interaction-test-runner';

modules/test-utils/src/interaction-test-runner.ts

@@ -47,7 +47,7 @@ export class InteractionTestRunner extends TestRunner<InteractionTestCase, {}> {
     });
 
     for (const event of testCase.events) {
-      if (event.wait) {
+      if ('wait' in event) {
         await sleep(event.wait);
       } else {
         await window.browserTestDriver_emulateInput(event);