mirror of
https://github.com/visgl/luma.gl.git
synced 2026-01-25 14:08:58 +00:00
110 lines
4.9 KiB
Markdown
110 lines
4.9 KiB
Markdown
# SnapshotTestRunner
|
|
|
|
Client-side utility for browser-based WebGL render tests.
|
|
|
|
This class is intended to be used with `BrowserTestDriver` from `@probe.gl/test-utils`. Together they support the following workflow:
|
|
|
|
- Launch a Puppeteer instance (headless or non-headless) to run a test application
|
|
- In the test application, create a canvas and `WebGLContext`.
|
|
- For each test case, render something to the `WebGLContext`, take a screenshot, and perform pixel-diffing with a pre-defined "golden image". Report the matching result.
|
|
- Proceed to the next test case until done.
|
|
|
|
## Example
|
|
|
|
In your node.js start script:
|
|
|
|
```typescript
|
|
// This is the script that runs in Node.js and starts the browser
|
|
const {BrowserTestDriver} = require('@probe.gl/test-utils');
|
|
new BrowserTestDriver().run({
|
|
server: {
|
|
// Bundles and serves the browser script
|
|
command: 'webpack-dev-server',
|
|
arguments: ['--env.render-test']
|
|
},
|
|
headless: true
|
|
});
|
|
```
|
|
|
|
In your script that is run on the browser:
|
|
|
|
```typescript
|
|
const {SnapshotTestRunner} = require('@luma.gl/test-utils');
|
|
const {Cube} = require('@luma.gl/engine');
|
|
|
|
const TEST_CASES = [
|
|
{
|
|
name: 'Render A Cube',
|
|
// `onRender` receives animation props from the AnimationLoop
|
|
onRender: ({gl, done}) => {
|
|
const model = new Cube(gl);
|
|
model.draw(...);
|
|
// ready for capture and diffing
|
|
done();
|
|
},
|
|
goldenImage: './test/render/golden-images/cube.png'
|
|
}
|
|
];
|
|
|
|
new TestRender({width: 800, height: 600})
|
|
.add(TEST_CASES)
|
|
.run({
|
|
onTestFail: window.browserTestDriver_fail
|
|
})
|
|
.then(window.browserTestDriver_finish);
|
|
```
|
|
|
|
## Methods
|
|
|
|
### constructor(props: Object)
|
|
|
|
```
|
|
new SnapshotTestRunner(props)
|
|
```
|
|
|
|
Create a SnapshotTestRunner instance. The `props` argument is forwarded to the [AnimationLoop](/docs/api-reference/engine/animation-loop) constructor.
|
|
|
|
### add(testCase: Array|Object)
|
|
|
|
Add one or a list of test cases. Each test case may contain the following fields:
|
|
|
|
- `name` (String) - name of the test case.
|
|
- `goldenImage` (String) - path to the golden image, relative to the root where the node script is executed.
|
|
- `timeout` (Number) - time to wait for this test case to resolve (by calling the `done` callback) before aborting, in milliseconds. If not provided, fallback to the shared option that is passed to `SnapshotTestRunner.run`.
|
|
- `imageDiffOptions` (Object) - image diffing options for this test case. See "Image Diff Options" section below.
|
|
- `onInitialize` (Function) - called once when the test case starts. Receives a single object that is the [AnimationLoop callback parameters](/docs/api-reference/engine/animation-loop#callback-parameters). If this callback returns an object or a promise, the content that it resolves to will be passed to `onRender` and `onFinalize` later.
|
|
- `onRender` (Function) - called every animation frame when the test case is running. Receives a single object that is the [AnimationLoop callback parameters](/docs/api-reference/engine/animation-loop#callback-parameters), plus the following:
|
|
- `done` (Function) - must be called when the test case is done rendering and ready for screen capture and comparison.
|
|
- `onFinalize` (Function) - called once when the test case is done to finalize all resources. Receives a single object that is the [AnimationLoop callback parameters](/docs/api-reference/engine/animation-loop#callback-parameters).
|
|
|
|
### run(options: Object)
|
|
|
|
Run all test cases.
|
|
|
|
Options:
|
|
|
|
- `timeout` (Number) - time to wait for each test case to resolve (by calling the `done` callback) before aborting, in milliseconds. Default `2000`.
|
|
- `imageDiffOptions` (Object) - image diffing options for all test cases. This will be overridden if a test case defines its own `imageDiffOptions`. See "Image Diff Options" section below.
|
|
- `onTestStart` (Function) - callback when a test starts. Receives the current test case. Default logs the test name to console.
|
|
- `onTestPass` (Function) - callback when a test passes. Receives the current test case and the diffing result. Default logs the pixel matching percentage to console.
|
|
- `onTestFail` (Function) - callback when a test fails, either because the matching rate is below threshold or a critical error. Receives the current test case. Default logs the error message or the pixel matching percentage to console.
|
|
|
|
Returns: a `Promise` that resolves when all test cases are done.
|
|
|
|
## Members
|
|
|
|
### isHeadless
|
|
|
|
Whether the test is being run in headless mode. In headless mode, Chromium uses software render which behaves slightly differently from non-headless. Image diffing tolerance may need to be adjusted accordingly.
|
|
|
|
## Image Diff Options
|
|
|
|
The test renderer and each test case may choose to override the default image diffing options. The following options from [captureAndDiffScreen](https://github.com/uber-web/probe.gl/blob/master/docs/api-reference/test-utils/browser-test-driver#browsertestdriver_captureanddiffscreenoptions--object) are supported:
|
|
|
|
- `tolerance`
|
|
- `threshold`
|
|
- `includeAA`
|
|
- `createDiffImage`
|
|
- `saveOnFail`
|
|
- `saveAs`
|