From cc47dc7473c01659a1e9733e044423d172acb857 Mon Sep 17 00:00:00 2001 From: Xiaoji Chen Date: Sat, 22 Jun 2024 11:08:19 -0700 Subject: [PATCH] fix(test-utils): run layer tests in Node (#8968) --- docs/api-reference/test-utils/overview.md | 23 +++++++---------------- modules/test-utils/src/utils/setup-gl.ts | 4 ++-- test/node.ts | 1 + 3 files changed, 10 insertions(+), 18 deletions(-) diff --git a/docs/api-reference/test-utils/overview.md b/docs/api-reference/test-utils/overview.md index 44146060adb..d89ce9a80af 100644 --- a/docs/api-reference/test-utils/overview.md +++ b/docs/api-reference/test-utils/overview.md @@ -13,15 +13,11 @@ The deck.gl test utilities are published as a separate npm module that is only i ```bash npm install --save-dev @deck.gl/test-utils -``` - -or - -```bash +# or yarn add -D @deck.gl/test-utils ``` -You typically want the major and minor version of ` @deck.gl/test-utils` to match the version of `@deck.gl/core` that you are using. i.e. you want to use `5.2.x` and `5.2.y` together. Check and if necessary edit your `package.json` to make sure things align. +You typically want the major and minor version of ` @deck.gl/test-utils` to match the version of `@deck.gl/core` that you are using. i.e. you want to use `9.0.x` and `9.0.y` together. Check and if necessary edit your `package.json` to make sure things align. ## Layer Conformance Tests @@ -31,17 +27,12 @@ Layer conformance tests are designed to verify deck.gl that layers update their Note that internally in deck.gl, updates are handled by the deck.gl layer "lifecycle" and these tests are therefore also called "lifecycle tests". Lifecycle tests are less demanding of the WebGL2/WebGPU environment than rendering tests described below and are thus easily integrated in traditional Node.js unit test suites (e.g. based on `tape`, `jest` or similar unit test frameworks). -## Layer Rendering Tests - -Rendering tests are a key feature of deck.gl's test utils. Rendering tests involve rendering layers with known inputs and performing pixel-comparison between the results against "golden images". - -Currently, rendering tests requires running layers with predefined props and views in a controlled Chrome instance, reporting values back to Node.js. - +## Rendering Tests -## Testing Applications instead of Layers +Rendering tests involve creating a `Deck` instance with known props, capturing the pixel output of the canvas, and then comparing the result against a "golden image". Tools such as [puppeteer](https://pptr.dev/) and [Selenium](https://www.selenium.dev/) have extensive capabilities that allow programatical control of such a process. -The current test utilities are focused on testing of layers. This might seem to make them less suited for testing deck.gl code in applications. Still, there are techniques that can be used to get parts of the application's rendering stack tested. +One of the core features of this module is to validate layers through rendering tests. This is supported through [SnapshotTestRunner](./snapshot-test-runner.md), which works with probe.gl's [BrowserTestDriver](https://uber-web.github.io/probe.gl/docs/modules/test-utils/browser-test-driver) (which uses Puppeteer) out of the box but can also work with a custom testing stack with some plumbing. -Applications that render multiple layers can e.g. render them with mock application data, and compare the result against a golden image. +The current test utilities are focused on the testing of layers. To test the render output of an application that uses deck.gl, a common technique is to run a rendering test of the whole application using mock input. -> More direct support for application testing is under consideration. Future support might include rendering layers directly in Node.js under headless gl, enabling apps to be tested in CI environments, as well as support for "snapshotting" deck.gl output inside live applications and comparing against golden images. +Future work might include running rendering tests directly in Node.js using a Node implementation of WebGPU. diff --git a/modules/test-utils/src/utils/setup-gl.ts b/modules/test-utils/src/utils/setup-gl.ts index 47ff264f689..0f6c2934c9b 100644 --- a/modules/test-utils/src/utils/setup-gl.ts +++ b/modules/test-utils/src/utils/setup-gl.ts @@ -1,7 +1,7 @@ -import {createTestContext, webglDevice} from '@luma.gl/test-utils'; +import {createTestContext, webglDevice, NullDevice} from '@luma.gl/test-utils'; /** Test device */ -export const device = webglDevice; +export const device = webglDevice || new NullDevice({}); /** Test context */ export const gl = createTestContext({ diff --git a/test/node.ts b/test/node.ts index ce9f24fc72b..71422b7603a 100644 --- a/test/node.ts +++ b/test/node.ts @@ -39,3 +39,4 @@ _global.cancelAnimationFrame = t => clearTimeout(t); // device.canvasContext.canvas = canvas; import './modules/imports-spec'; +import './modules/layers/core-layers.spec';