@deck.gl/test-utils 9.0.0-beta.2 → 9.0.0-beta.3

package/src/interaction-test-runner.ts

@@ -19,48 +19,64 @@
 // THE SOFTWARE.
 
 /* global window */
-import TestRunner from './test-runner';
+import {TestRunner} from './test-runner';
+import type {Deck, Layer} from '@deck.gl/core';
 
-const DEFAULT_TEST_CASE = {
+type InteractionEvent =
+  | {
+      type: string;
+      [key: string]: any;
+    }
+  | {
+      wait: number;
+    };
+
+export type InteractionTestCase = {
+  name: string;
+  events: InteractionEvent[];
+  timeout?: number;
+  context?: any;
+  onBeforeEvents: (params: {deck: Deck}) => any;
+  onAfterEvents: (params: {deck: Deck; layers: Layer[]; context: any}) => void;
+};
+
+const DEFAULT_TEST_CASE: InteractionTestCase = {
   name: 'Unnamed interaction test',
   events: [],
   onBeforeEvents: ({deck}) => {},
   onAfterEvents: ({deck, layers, context}) => {}
 };
 
-function sleep(timeout) {
+function sleep(timeout: number): Promise<void> {
   return new Promise(resolve => window.setTimeout(resolve, timeout));
 }
 
-export default class InteractionTestRunner extends TestRunner {
+export class InteractionTestRunner extends TestRunner<InteractionTestCase, {}> {
   get defaultTestCase() {
     return DEFAULT_TEST_CASE;
   }
 
   // chain events
-  // TODO - switch to async/await
-  runTestCase(testCase, onDone) {
+  async runTestCase(testCase: InteractionTestCase) {
     testCase.context = testCase.onBeforeEvents({
-      deck: this.deck
+      deck: this.deck!
     });
 
-    let promise = Promise.resolve();
     for (const event of testCase.events) {
       if (event.wait) {
-        promise = promise.then(() => sleep(event.wait));
+        await sleep(event.wait);
       } else {
-        promise = promise.then(() => window.browserTestDriver_emulateInput(event));
+        await window.browserTestDriver_emulateInput(event);
       }
     }
-    return promise.then(onDone);
   }
 
-  assert(testCase) {
+  async assert(testCase) {
     testCase.onAfterEvents({
       deck: this.deck,
+      // @ts-expect-error Accessing protected layerManager
       layers: this.deck.layerManager.getLayers(),
       context: testCase.context
     });
-    this._next();
   }
 }

package/src/lifecycle-test.ts

@@ -23,19 +23,38 @@ import {LayerManager, MapView, DeckRenderer} from '@deck.gl/core';
 import {makeSpy} from '@probe.gl/test-utils';
 import {device} from './utils/setup-gl';
 
-const testViewport = new MapView().makeViewport({
+import type {Layer, CompositeLayer, Viewport} from '@deck.gl/core';
+import type {Timeline} from '@luma.gl/engine';
+import type {StatsManager} from '@luma.gl/core';
+
+const testViewport = new MapView({}).makeViewport({
   width: 100,
   height: 100,
   viewState: {longitude: 0, latitude: 0, zoom: 1}
-});
+}) as Viewport;
 
-function defaultOnError(error, title) {
+function defaultOnError(error: unknown, title: string): void {
   if (error) {
     throw error;
   }
 }
 
-function initializeLayerManager({layer, viewport = testViewport, onError = defaultOnError}) {
+type InitializeLayerTestOptions = {
+  /** The layer instance to test */
+  layer: Layer;
+  /** The initial viewport
+   * @default WebMercatorViewport
+   */
+  viewport?: Viewport;
+  /** Callback if any error is thrown */
+  onError?: (error: unknown, title: string) => void;
+};
+
+function initializeLayerManager({
+  layer,
+  viewport = testViewport,
+  onError = defaultOnError
+}: InitializeLayerTestOptions): LayerManager {
   const layerManager = new LayerManager(device, {viewport});
   layerManager.setProps({
     onError: error => onError(error, `initializing ${layer.id}`)
@@ -45,7 +64,34 @@ function initializeLayerManager({layer, viewport = testViewport, onError = defau
   return layerManager;
 }
 
-export function testInitializeLayer(opts) {
+/** Test that initializing a layer does not throw.
+ * Use `testInitializeLayerAsync` if the layer's initialization flow contains async operations.
+ */
+export function testInitializeLayer(
+  opts: InitializeLayerTestOptions & {
+    /** Automatically finalize the layer and release all resources after the test */
+    finalize?: true;
+  }
+): null;
+export function testInitializeLayer(
+  opts: InitializeLayerTestOptions & {
+    /** Automatically finalize the layer and release all resources after the test */
+    finalize: false;
+  }
+): {
+  /** Finalize the layer and release all resources */
+  finalize: () => void;
+};
+
+export function testInitializeLayer(
+  opts: InitializeLayerTestOptions & {
+    /** Automatically finalize the layer and release all resources after the test */
+    finalize?: boolean;
+  }
+): {
+  /** Finalize the layer and release all resources */
+  finalize: () => void;
+} | null {
   const layerManager = initializeLayerManager(opts);
   if (opts.finalize === false) {
     return {
@@ -56,11 +102,38 @@ export function testInitializeLayer(opts) {
   return null;
 }
 
-export async function testInitializeLayerAsync(opts) {
+/** Test that initializing a layer does not throw.
+ * Resolves when the layer's isLoaded flag becomes true.
+ */
+export function testInitializeLayerAsync(
+  opts: InitializeLayerTestOptions & {
+    /** Automatically finalize the layer and release all resources after the test */
+    finalize?: true;
+  }
+): Promise<null>;
+export function testInitializeLayerAsync(
+  opts: InitializeLayerTestOptions & {
+    /** Automatically finalize the layer and release all resources after the test */
+    finalize: false;
+  }
+): Promise<{
+  /** Finalize the layer and release all resources */
+  finalize: () => void;
+}>;
+
+export async function testInitializeLayerAsync(
+  opts: InitializeLayerTestOptions & {
+    /** Automatically finalize the layer and release all resources after the test */
+    finalize?: boolean;
+  }
+): Promise<{
+  /** Finalize the layer and release all resources */
+  finalize: () => void;
+} | null> {
   const layerManager = initializeLayerManager(opts);
   const deckRenderer = new DeckRenderer(device);
   while (!opts.layer.isLoaded) {
-    await update({layerManager, deckRenderer});
+    await update({layerManager, deckRenderer, oldResourceCounts: {}});
   }
   if (opts.finalize === false) {
     return {
@@ -71,7 +144,68 @@ export async function testInitializeLayerAsync(opts) {
   return null;
 }
 
-export function testLayer(opts) {
+// TODO - export from probe.gl
+type Spy = ReturnType<typeof makeSpy>;
+
+export type LayerClass<LayerT extends Layer> = {
+  new (...args): LayerT;
+  layerName: string;
+  defaultProps: Partial<LayerT['props']>;
+};
+
+export type LayerTestCase<LayerT extends Layer> = {
+  title: string;
+  viewport?: Viewport;
+  /** Reset the props of the test layer instance */
+  props?: Partial<LayerT['props']>;
+  /** Update the given props of the test layer instance */
+  updateProps?: Partial<LayerT['props']>;
+  /** List of layer method names to watch */
+  spies?: string[];
+
+  /** Called before layer updates */
+  onBeforeUpdate?: (params: {layer: Layer; testCase: LayerTestCase<LayerT>}) => void;
+
+  /** Called after layer is updated */
+  onAfterUpdate?: (params: {
+    testCase: LayerTestCase<LayerT>;
+    layer: LayerT;
+    oldState: any;
+    subLayers: Layer[];
+    subLayer: Layer | null;
+    spies: Record<string, Spy>;
+  }) => void;
+};
+
+type TestResources = {
+  layerManager: LayerManager;
+  deckRenderer: DeckRenderer;
+  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: {
+  /** 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;
+}): void {
   const {Layer, testCases = [], spies = [], onError = defaultOnError} = opts;
 
   const resources = setupLayerTests(`testing ${Layer.layerName}`, opts);
@@ -97,7 +231,29 @@ export function testLayer(opts) {
   }
 }
 
-export async function testLayerAsync(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;
 
   const resources = setupLayerTests(`testing ${Layer.layerName}`, opts);
@@ -129,19 +285,25 @@ export async function testLayerAsync(opts) {
 }
 
 function setupLayerTests(
-  testTitle,
-  {viewport = testViewport, timeline = null, onError = defaultOnError}
-) {
+  testTitle: string,
+  {
+    viewport = testViewport,
+    timeline,
+    onError = defaultOnError
+  }: {
+    viewport?: Viewport;
+    timeline?: Timeline;
+    onError?: (error: Error, title: string) => void;
+  }
+): TestResources {
   const oldResourceCounts = getResourceCounts();
 
   const layerManager = new LayerManager(device, {viewport, timeline});
   const deckRenderer = new DeckRenderer(device);
 
-  layerManager.context.animationProps = {
-    time: 0
-  };
-
   const props = {
+    layerFilter: null,
+    drawPickingColors: false,
     onError: error => onError(error, testTitle)
   };
   layerManager.setProps(props);
@@ -150,7 +312,11 @@ function setupLayerTests(
   return {layerManager, deckRenderer, oldResourceCounts};
 }
 
-function cleanupAfterLayerTests({layerManager, deckRenderer, oldResourceCounts}) {
+function cleanupAfterLayerTests({
+  layerManager,
+  deckRenderer,
+  oldResourceCounts
+}: TestResources): Error | null {
   layerManager.setLayers([]);
   layerManager.finalize();
   deckRenderer.finalize();
@@ -167,17 +333,17 @@ function cleanupAfterLayerTests({layerManager, deckRenderer, oldResourceCounts})
   return null;
 }
 
-function getResourceCounts() {
+function getResourceCounts(): Record<string, number> {
   /* global luma */
-  const resourceStats = luma.stats.get('Resource Counts');
+  const resourceStats = (luma.stats as StatsManager).get('Resource Counts');
   return {
     Texture2D: resourceStats.get('Texture2Ds Active').count,
     Buffer: resourceStats.get('Buffers Active').count
   };
 }
 
-function injectSpies(layer, spies) {
-  const spyMap = {};
+function injectSpies(layer: Layer, spies: string[]): Record<string, Spy> {
+  const spyMap: Record<string, Spy> = {};
   if (spies) {
     for (const functionName of spies) {
       spyMap[functionName] = makeSpy(Object.getPrototypeOf(layer), functionName);
@@ -186,13 +352,20 @@ function injectSpies(layer, spies) {
   return spyMap;
 }
 
-function runLayerTestPostUpdateCheck(testCase, newLayer, oldState, spyMap) {
+function runLayerTestPostUpdateCheck<LayerT extends Layer>(
+  testCase: LayerTestCase<LayerT>,
+  newLayer: LayerT,
+  oldState: any,
+  spyMap: Record<string, Spy>
+) {
   // assert on updated layer
   if (testCase.onAfterUpdate) {
     // layer manager should handle match subLayer and tranfer state and props
     // here we assume subLayer matches copy over the new props from a new subLayer
-    const subLayers = newLayer.isComposite ? newLayer.getSubLayers() : [];
-    const subLayer = subLayers.length && subLayers[0];
+    const subLayers = newLayer.isComposite
+      ? (newLayer as Layer as CompositeLayer).getSubLayers()
+      : [];
+    const subLayer = subLayers.length ? subLayers[0] : null;
 
     testCase.onAfterUpdate({
       testCase,
@@ -205,7 +378,15 @@ function runLayerTestPostUpdateCheck(testCase, newLayer, oldState, spyMap) {
   }
 }
 
-function runLayerTestUpdate(testCase, {layerManager, deckRenderer}, layer, spies) {
+function runLayerTestUpdate<LayerT extends Layer>(
+  testCase: LayerTestCase<LayerT>,
+  {layerManager, deckRenderer}: TestResources,
+  layer: LayerT,
+  spies: string[]
+): {
+  layer: LayerT;
+  spyMap: Record<string, Spy>;
+} {
   const {props, updateProps, onBeforeUpdate, viewport = layerManager.context.viewport} = testCase;
 
   if (onBeforeUpdate) {
@@ -214,7 +395,7 @@ function runLayerTestUpdate(testCase, {layerManager, deckRenderer}, layer, spies
 
   if (props) {
     // Test case can reset the props on every iteration
-    layer = new layer.constructor(props);
+    layer = new (layer.constructor as LayerClass<LayerT>)(props);
   } else if (updateProps) {
     // Test case can override with new props on every iteration
     layer = layer.clone(updateProps);
@@ -225,6 +406,9 @@ function runLayerTestUpdate(testCase, {layerManager, deckRenderer}, layer, spies
   const spyMap = injectSpies(layer, spies);
   const drawLayers = () => {
     deckRenderer.renderLayers({
+      pass: 'test',
+      views: {},
+      effects: [],
       viewports: [viewport],
       layers: layerManager.getLayers(),
       onViewportActive: layerManager.activateViewport
@@ -244,13 +428,16 @@ function runLayerTestUpdate(testCase, {layerManager, deckRenderer}, layer, spies
 }
 
 /* global setTimeout */
-function update({layerManager, deckRenderer}) {
+function update({layerManager, deckRenderer}: TestResources): Promise<void> {
   return new Promise(resolve => {
     const onAnimationFrame = () => {
       if (layerManager.needsUpdate()) {
         layerManager.updateLayers();
 
         deckRenderer.renderLayers({
+          pass: 'test',
+          views: {},
+          effects: [],
           viewports: [layerManager.context.viewport],
           layers: layerManager.getLayers(),
           onViewportActive: layerManager.activateViewport

package/src/snapshot-test-runner.ts

@@ -19,14 +19,45 @@
 // THE SOFTWARE.
 
 /* global window */
-import TestRunner from './test-runner';
+import {TestRunner} from './test-runner';
 import {getBoundingBoxInPage} from './utils/dom';
 
+import type {DeckProps, Deck, Layer} from '@deck.gl/core';
+
+// TODO - export from probe.gl
+type ImageDiffOptions = {
+  saveOnFail?: boolean;
+  saveAs?: string;
+  threshold?: number; // 0.99,
+  createDiffImage?: boolean; // false,
+  tolerance?: number; // 0.1,
+  includeAA?: boolean; // false,
+  includeEmpty?: boolean; // true
+};
+
+type DiffImageResult = {
+  headless: boolean;
+  match: string | number;
+  matchPercentage: string;
+  success: boolean;
+  error: Error | string | null;
+};
+
+export type SnapshotTestCase = {
+  name: string;
+  props: DeckProps;
+  goldenImage: string;
+  onBeforeRender?: (params: {deck: Deck; layers: Layer[]}) => void;
+  onAfterRender?: (params: {deck: Deck; layers: Layer[]; done: () => void}) => void;
+  timeout?: number;
+  imageDiffOptions?: ImageDiffOptions;
+};
+
 const DEFAULT_TEST_OPTIONS = {
   imageDiffOptions: {}
 };
 
-const DEFAULT_TEST_CASE = {
+const DEFAULT_TEST_CASE: SnapshotTestCase = {
   name: 'Unnamed snapshot test',
   props: {},
   onBeforeRender: ({deck, layers}) => {
@@ -40,77 +71,78 @@ const DEFAULT_TEST_CASE = {
   goldenImage: ''
 };
 
-export default class SnapshotTestRunner extends TestRunner {
-  constructor(props) {
-    super(props);
+export class SnapshotTestRunner extends TestRunner<
+  SnapshotTestCase,
+  DiffImageResult,
+  {imageDiffOptions: ImageDiffOptions}
+> {
+  private _isDiffing: boolean = false;
 
-    this.isDiffing = false;
+  constructor(props) {
+    super(props, DEFAULT_TEST_OPTIONS);
 
-    Object.assign(this.testOptions, DEFAULT_TEST_OPTIONS);
+    this._isDiffing = false;
   }
 
   get defaultTestCase() {
     return DEFAULT_TEST_CASE;
   }
 
-  initTestCase(testCase) {
+  initTestCase(testCase: SnapshotTestCase) {
     super.initTestCase(testCase);
     if (!testCase.goldenImage) {
       throw new Error(`Test case ${testCase.name} does not have golden image`);
     }
   }
 
-  runTestCase(testCase, onDone) {
-    const {deck} = this;
-
-    deck.setProps({
-      ...this.props,
-      ...testCase,
-      onBeforeRender: () => {
-        testCase.onBeforeRender({
-          deck,
-          layers: deck.props.layers
-        });
-      },
-      onAfterRender: () => {
-        testCase.onAfterRender({
-          deck,
-          layers: deck.props.layers,
-          done: onDone
-        });
-      }
-    });
-  }
+  runTestCase(testCase: SnapshotTestCase) {
+    const deck = this.deck!;
 
-  shouldRender() {
-    // wait for the current diffing to finish
-    return !this.isDiffing;
+    return new Promise<void>(resolve => {
+      deck.setProps({
+        ...this.props,
+        ...testCase,
+        onBeforeRender: () => {
+          testCase.onBeforeRender!({
+            deck,
+            // @ts-expect-error Accessing protected layerManager
+            layers: this.deck.layerManager.getLayers()
+          });
+        },
+        onAfterRender: () => {
+          testCase.onAfterRender!({
+            deck,
+            // @ts-expect-error Accessing protected layerManager
+            layers: this.deck.layerManager.getLayers(),
+            done: resolve
+          });
+        }
+      });
+    });
   }
 
-  assert(testCase) {
-    if (this.isDiffing) {
+  async assert(testCase: SnapshotTestCase) {
+    if (this._isDiffing) {
       // already performing diffing
       return;
     }
-    this.isDiffing = true;
+    this._isDiffing = true;
 
     const diffOptions = {
       ...this.testOptions.imageDiffOptions,
       ...testCase.imageDiffOptions,
       goldenImage: testCase.goldenImage,
-      region: getBoundingBoxInPage(this.deck.canvas)
+      region: getBoundingBoxInPage(this.deck!.getCanvas()!)
     };
     // Take screenshot and compare
-    window.browserTestDriver_captureAndDiffScreen(diffOptions).then(result => {
-      // invoke user callback
-      if (result.success) {
-        this._pass(result);
-      } else {
-        this._fail(result);
-      }
-
-      this.isDiffing = false;
-      this._next();
-    });
+    const result = await window.browserTestDriver_captureAndDiffScreen(diffOptions);
+    // invoke user callback
+    if (result.success) {
+      this.pass(result);
+    } else {
+      this.fail(result);
+    }
+
+    this._isDiffing = false;
   }
 }