@deck.gl/test-utils 9.3.0-alpha.3 → 9.3.0-alpha.5

package/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 {};

package/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';
+// Re-export from tape.ts which provides default spy factory for backward compat
+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, ResetSpy, SpyFactory} from './tape';
 export type {SnapshotTestCase} from './snapshot-test-runner';
 export type {InteractionTestCase} from './interaction-test-runner';

package/src/lifecycle-test.ts

@@ -4,7 +4,6 @@
 
 import {LayerManager, MapView, DeckRenderer} from '@deck.gl/core';
 
-import {makeSpy} from '@probe.gl/test-utils';
 import {device} from './utils/setup-gl';
 
 import type {Layer, CompositeLayer, Viewport} from '@deck.gl/core';
@@ -128,8 +127,25 @@ export async function testInitializeLayerAsync(
   return null;
 }
 
-// TODO - export from probe.gl
-type Spy = ReturnType<typeof makeSpy>;
+/** Spy object compatible with both vitest and probe.gl */
+export type Spy = {
+  /** Restore the original method (vitest) */
+  mockRestore?: () => void;
+  /** Restore the original method (probe.gl) */
+  restore?: () => void;
+  /** Call history (vitest) */
+  mock?: {calls: unknown[][]};
+  /** Call history (probe.gl) */
+  calls?: unknown[][];
+  /** Whether the spy was called (probe.gl) */
+  called?: boolean;
+};
+
+/** Factory function to create a spy on an object method */
+export type SpyFactory = (obj: object, method: string) => Spy;
+
+/** Function to reset/cleanup a spy after each test case */
+export type ResetSpy = (spy: Spy) => void;
 
 export type LayerClass<LayerT extends Layer> = {
   new (...args): LayerT;
@@ -167,11 +183,7 @@ type TestResources = {
   oldResourceCounts: Record<string, number>;
 };
 
-/**
- * Initialize and updates a layer over a sequence of scenarios (test cases).
- * Use `testLayerAsync` if the layer's update flow contains async operations.
- */
-export function testLayer<LayerT extends Layer>(opts: {
+export type TestLayerOptions<LayerT extends Layer> = {
   /** The layer class to test against */
   Layer: LayerClass<LayerT>;
   /** The initial viewport
@@ -189,8 +201,18 @@ export function testLayer<LayerT extends Layer>(opts: {
   spies?: string[];
   /** Callback if any error is thrown */
   onError?: (error: Error, title: string) => void;
-}): void {
-  const {Layer, testCases = [], spies = [], onError = defaultOnError} = opts;
+  /** Factory function to create spies */
+  createSpy: SpyFactory;
+  /** Function to reset/cleanup a spy after each test case */
+  resetSpy: ResetSpy;
+};
+
+/**
+ * Initialize and updates a layer over a sequence of scenarios (test cases).
+ * Use `testLayerAsync` if the layer's update flow contains async operations.
+ */
+export function testLayer<LayerT extends Layer>(opts: TestLayerOptions<LayerT>): void {
+  const {Layer, testCases = [], spies = [], onError = defaultOnError, createSpy, resetSpy} = opts;
 
   const resources = setupLayerTests(`testing ${Layer.layerName}`, opts);
 
@@ -200,12 +222,18 @@ export function testLayer<LayerT extends Layer>(opts: {
     // Save old state before update
     const oldState = {...layer.state};
 
-    const {layer: newLayer, spyMap} = runLayerTestUpdate(testCase, resources, layer, spies);
+    const {layer: newLayer, spyMap} = runLayerTestUpdate(
+      testCase,
+      resources,
+      layer,
+      spies,
+      createSpy
+    );
 
     runLayerTestPostUpdateCheck(testCase, newLayer, oldState, spyMap);
 
-    // Remove spies
-    Object.keys(spyMap).forEach(k => spyMap[k].reset());
+    // Reset spies between test cases
+    Object.keys(spyMap).forEach(k => resetSpy(spyMap[k]));
     layer = newLayer;
   }
 
@@ -219,26 +247,10 @@ export function testLayer<LayerT extends Layer>(opts: {
  * Initialize and updates a layer over a sequence of scenarios (test cases).
  * Each test case is awaited until the layer's isLoaded flag is true.
  */
-export async function testLayerAsync<LayerT extends Layer>(opts: {
-  /** The layer class to test against */
-  Layer: LayerClass<LayerT>;
-  /** The initial viewport
-   * @default WebMercatorViewport
-   */
-  viewport?: Viewport;
-  /**
-   * If provided, used to controls time progression. Useful for testing transitions and animations.
-   */
-  timeline?: Timeline;
-  testCases?: LayerTestCase<LayerT>[];
-  /**
-   * List of layer method names to watch
-   */
-  spies?: string[];
-  /** Callback if any error is thrown */
-  onError?: (error: Error, title: string) => void;
-}): Promise<void> {
-  const {Layer, testCases = [], spies = [], onError = defaultOnError} = opts;
+export async function testLayerAsync<LayerT extends Layer>(
+  opts: TestLayerOptions<LayerT>
+): Promise<void> {
+  const {Layer, testCases = [], spies = [], onError = defaultOnError, createSpy, resetSpy} = opts;
 
   const resources = setupLayerTests(`testing ${Layer.layerName}`, opts);
 
@@ -248,7 +260,13 @@ export async function testLayerAsync<LayerT extends Layer>(opts: {
     // Save old state before update
     const oldState = {...layer.state};
 
-    const {layer: newLayer, spyMap} = runLayerTestUpdate(testCase, resources, layer, spies);
+    const {layer: newLayer, spyMap} = runLayerTestUpdate(
+      testCase,
+      resources,
+      layer,
+      spies,
+      createSpy
+    );
 
     runLayerTestPostUpdateCheck(testCase, newLayer, oldState, spyMap);
 
@@ -257,12 +275,13 @@ export async function testLayerAsync<LayerT extends Layer>(opts: {
       runLayerTestPostUpdateCheck(testCase, newLayer, oldState, spyMap);
     }
 
-    // Remove spies
-    Object.keys(spyMap).forEach(k => spyMap[k].reset());
+    // Reset spies between test cases
+    Object.keys(spyMap).forEach(k => resetSpy(spyMap[k]));
     layer = newLayer;
   }
 
-  const error = cleanupAfterLayerTests(resources);
+  // Use async cleanup to allow pending luma.gl async operations to complete
+  const error = await cleanupAfterLayerTestsAsync(resources);
   if (error) {
     onError(error, `${Layer.layerName} should delete all resources`);
   }
@@ -305,16 +324,31 @@ function cleanupAfterLayerTests({
   layerManager.finalize();
   deckRenderer.finalize();
 
-  const resourceCounts = getResourceCounts();
+  return getResourceCountDelta(oldResourceCounts);
+}
 
-  for (const resourceName in resourceCounts) {
-    if (resourceCounts[resourceName] !== oldResourceCounts[resourceName]) {
-      return new Error(
-        `${resourceCounts[resourceName] - oldResourceCounts[resourceName]} ${resourceName}s`
-      );
-    }
-  }
-  return null;
+/**
+ * Async cleanup that waits for pending async operations before finalizing resources.
+ * This prevents unhandled rejections from luma.gl's async shader error reporting
+ * which may try to access destroyed WebGL resources if cleanup happens too early.
+ */
+async function cleanupAfterLayerTestsAsync({
+  layerManager,
+  deckRenderer,
+  oldResourceCounts
+}: TestResources): Promise<Error | null> {
+  layerManager.setLayers([]);
+
+  // Wait for any pending async operations (e.g., luma.gl's deferred shader compilation
+  // error handling) to complete before destroying resources. This prevents
+  // "getProgramInfoLog" errors when async error reporting tries to access
+  // already-destroyed WebGL programs.
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  layerManager.finalize();
+  deckRenderer.finalize();
+
+  return getResourceCountDelta(oldResourceCounts);
 }
 
 function getResourceCounts(): Record<string, number> {
@@ -326,11 +360,24 @@ function getResourceCounts(): Record<string, number> {
   };
 }
 
-function injectSpies(layer: Layer, spies: string[]): Record<string, Spy> {
+function getResourceCountDelta(oldResourceCounts: Record<string, number>): Error | null {
+  const resourceCounts = getResourceCounts();
+
+  for (const resourceName in resourceCounts) {
+    if (resourceCounts[resourceName] !== oldResourceCounts[resourceName]) {
+      return new Error(
+        `${resourceCounts[resourceName] - oldResourceCounts[resourceName]} ${resourceName}s`
+      );
+    }
+  }
+  return null;
+}
+
+function injectSpies(layer: Layer, spies: string[], spyFactory: SpyFactory): Record<string, Spy> {
   const spyMap: Record<string, Spy> = {};
   if (spies) {
     for (const functionName of spies) {
-      spyMap[functionName] = makeSpy(Object.getPrototypeOf(layer), functionName);
+      spyMap[functionName] = spyFactory(Object.getPrototypeOf(layer), functionName);
     }
   }
   return spyMap;
@@ -366,7 +413,8 @@ function runLayerTestUpdate<LayerT extends Layer>(
   testCase: LayerTestCase<LayerT>,
   {layerManager, deckRenderer}: TestResources,
   layer: LayerT,
-  spies: string[]
+  spies: string[],
+  spyFactory: SpyFactory
 ): {
   layer: LayerT;
   spyMap: Record<string, Spy>;
@@ -387,7 +435,7 @@ function runLayerTestUpdate<LayerT extends Layer>(
 
   // Create a map of spies that the test case can inspect
   spies = testCase.spies || spies;
-  const spyMap = injectSpies(layer, spies);
+  const spyMap = injectSpies(layer, spies, spyFactory);
   const drawLayers = () => {
     deckRenderer.renderLayers({
       pass: 'test',

package/src/tape.ts

@@ -0,0 +1,85 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Tape entry point - wraps lifecycle-test and adds @probe.gl/test-utils as the default spy factory
+// For vitest users, use @deck.gl/test-utils/vitest which doesn't import probe.gl
+
+import {makeSpy} from '@probe.gl/test-utils';
+import {
+  testLayer as testLayerCore,
+  testLayerAsync as testLayerAsyncCore,
+  testInitializeLayer,
+  testInitializeLayerAsync
+} from './lifecycle-test';
+import type {Layer} from '@deck.gl/core';
+import type {
+  LayerClass,
+  LayerTestCase,
+  ResetSpy,
+  SpyFactory,
+  TestLayerOptions
+} from './lifecycle-test';
+
+export {testInitializeLayer, testInitializeLayerAsync};
+export type {LayerClass, LayerTestCase, ResetSpy, SpyFactory};
+
+let _hasWarnedCreateSpy = false;
+let _hasWarnedResetSpy = false;
+
+function getDefaultSpyFactory(): SpyFactory {
+  if (!_hasWarnedCreateSpy) {
+    _hasWarnedCreateSpy = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[@deck.gl/test-utils] Implicit @probe.gl/test-utils usage is deprecated. ' +
+        'Pass createSpy option: createSpy: (obj, method) => vi.spyOn(obj, method) for vitest, ' +
+        'or createSpy: makeSpy for probe.gl.'
+    );
+  }
+  return makeSpy;
+}
+
+/** Default reset for probe.gl spies - clears call tracking but keeps spy active */
+function getDefaultResetSpy(): ResetSpy {
+  if (!_hasWarnedResetSpy) {
+    _hasWarnedResetSpy = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[@deck.gl/test-utils] Implicit spy reset is deprecated. ' +
+        'Pass resetSpy option: resetSpy: (spy) => spy.mockRestore() for vitest, ' +
+        'or resetSpy: (spy) => spy.reset() for probe.gl.'
+    );
+  }
+  return spy => (spy as ReturnType<typeof makeSpy>).reset();
+}
+
+/**
+ * Initialize and updates a layer over a sequence of scenarios (test cases).
+ * Use `testLayerAsync` if the layer's update flow contains async operations.
+ */
+export function testLayer<LayerT extends Layer>(
+  opts: Omit<TestLayerOptions<LayerT>, 'createSpy' | 'resetSpy'> & {
+    createSpy?: SpyFactory;
+    resetSpy?: ResetSpy;
+  }
+): void {
+  const createSpy = opts.createSpy || getDefaultSpyFactory();
+  const resetSpy = opts.resetSpy || getDefaultResetSpy();
+  testLayerCore({...opts, createSpy, resetSpy});
+}
+
+/**
+ * Initialize and updates a layer over a sequence of scenarios (test cases).
+ * Each test case is awaited until the layer's isLoaded flag is true.
+ */
+export async function testLayerAsync<LayerT extends Layer>(
+  opts: Omit<TestLayerOptions<LayerT>, 'createSpy' | 'resetSpy'> & {
+    createSpy?: SpyFactory;
+    resetSpy?: ResetSpy;
+  }
+): Promise<void> {
+  const createSpy = opts.createSpy || getDefaultSpyFactory();
+  const resetSpy = opts.resetSpy || getDefaultResetSpy();
+  await testLayerAsyncCore({...opts, createSpy, resetSpy});
+}

package/src/test-runner.ts

@@ -163,7 +163,7 @@ export abstract class TestRunner<TestCaseT extends TestCase, ResultT, ExtraOptio
     const task = this.runTestCase(testCase);
     const timeoutTask = new Promise((_, reject) => {
       setTimeout(() => {
-        reject('Timeout');
+        reject(`Timeout after ${timeout}ms`);
       }, timeout);
     });
 
@@ -171,8 +171,8 @@ export abstract class TestRunner<TestCaseT extends TestCase, ResultT, ExtraOptio
       await Promise.race([task, timeoutTask]);
       await this.assert(testCase);
     } catch (err: unknown) {
-      if (err === 'Timeout') {
-        this.fail({error: 'Timeout'});
+      if (typeof err === 'string' && err.startsWith('Timeout')) {
+        this.fail({error: err});
       }
     }
   }

package/src/utils/setup-gl.ts

@@ -2,10 +2,9 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {CanvasContextProps} from '@luma.gl/core';
-import {WebGLDevice} from '@luma.gl/webgl';
 import {webglDevice, NullDevice} from '@luma.gl/test-utils';
 
+// Use pre-created device from @luma.gl/test-utils, fall back to NullDevice in Node
 export const device = webglDevice || new NullDevice({});
 export const gl = webglDevice?.gl || 1;
 

package/src/vitest.ts

@@ -0,0 +1,49 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Vitest-specific entry point with vi.spyOn default
+// Use: import { testLayer } from '@deck.gl/test-utils/vitest'
+
+import {vi} from 'vitest';
+import {testLayer as testLayerCore, testLayerAsync as testLayerAsyncCore} from './lifecycle-test';
+import type {Layer} from '@deck.gl/core';
+import type {ResetSpy, SpyFactory, TestLayerOptions} from './lifecycle-test';
+
+/** Default spy factory using vi.spyOn */
+const defaultSpyFactory: SpyFactory = (obj, method) => vi.spyOn(obj, method as never);
+
+/** Default reset for vitest spies - restores original implementation */
+const defaultResetSpy: ResetSpy = spy => spy.mockRestore?.();
+
+export function testLayer<LayerT extends Layer>(
+  opts: Omit<TestLayerOptions<LayerT>, 'createSpy' | 'resetSpy'> & {
+    createSpy?: SpyFactory;
+    resetSpy?: ResetSpy;
+  }
+) {
+  const createSpy = opts.createSpy || defaultSpyFactory;
+  const resetSpy = opts.resetSpy || defaultResetSpy;
+  return testLayerCore({...opts, createSpy, resetSpy});
+}
+
+export function testLayerAsync<LayerT extends Layer>(
+  opts: Omit<TestLayerOptions<LayerT>, 'createSpy' | 'resetSpy'> & {
+    createSpy?: SpyFactory;
+    resetSpy?: ResetSpy;
+  }
+) {
+  const createSpy = opts.createSpy || defaultSpyFactory;
+  const resetSpy = opts.resetSpy || defaultResetSpy;
+  return testLayerAsyncCore({...opts, createSpy, resetSpy});
+}
+
+// Re-export non-spy utilities
+export {testInitializeLayer, testInitializeLayerAsync} from './lifecycle-test';
+export {getLayerUniforms} from './utils/layer';
+export {toLowPrecision} from './utils/precision';
+export {gl, device} from './utils/setup-gl';
+export {generateLayerTests} from './generate-layer-tests';
+
+// Types
+export type {LayerTestCase, ResetSpy, SpyFactory, TestLayerOptions} from './lifecycle-test';