This package contains tools and testing processes that enable the
<model-viewer> project to ensure high-fidelity 3D model rendering.
If you are looking for the <model-viewer> web component, please refer to the
<model-viewer> package and also the live docs and examples
on modelviewer.dev.
To get started, follow the instructions in the main README.md file.
In order to run npm run render-goldens, you must have imagemagick installed.
On macOS, you can install imagemagick with homebrew: brew install imagemagick
On Debian/Ubuntu/Pop!_OS you can install imagemagick with apt: sudo apt install imagemagick
The following commands are available when developing modelviewer.dev:
| Command | Description |
|---|---|
npm run build |
Build artifacts required to run testing and review tools |
npm run clean |
Deletes all build artifacts |
npm run test |
Run a render fidelity check comparing <model-viewer> to other renderers |
npm run render-goldens |
Render the "golden" images for all renderers |
For npm run test, we support these command line options:
| Command | Default | Description |
|---|---|---|
| -c, --config | Path to configuration json. | |
| -s, --scenario | Limit to specific scenarios. This now also allows you to specify multiple scenarios in the whitelist. You can use a full name or a partial name of scenarios and it will match against all that contain that scenario substring. | |
| -p, --port | 9040 | Port for web server. |
| -d, --dry-run | false | Lists which images would be rendered but doesn't render. Useful when trying to figure out which tests will run given that command line. |
| -q, --quiet | false | Hide the puppeteer controlled browser. This can allow you to work on the computer while it is running in the background. |
To run a subset of scenarios do something like this:
% npm run test -- --scenario=texture --quiet
NOTE: In the above example, the -- is required to separate the arguments to npm run test from the arguments to the script itself.
After running npm run test, you can look at the results by starting a local web server (e.g. npx http-server) in this folder, then opening test/results-viewer.html in a browser.
For npm run render-goldens, we support these command line options:
| Command | Default | Description |
|---|---|---|
| -c, --config | Path to configuration json. | |
| -s, --scenario | Limit to specific scenarios. This now also allows you to specify multiple scenarios in the whitelist. You can use a full name or a partial name of scenarios and it will match against all that contain that scenario substring. | |
| -p, --port | 9040 | Port for web server. |
| -m, --missing-only | false | Only render if an output image is missing. Very useful when adding new tests. |
| -d, --dry-run | false | Lists which images would be rendered but doesn't render. Useful when trying to figure out which tests will run given that command line. |
| -q, --quiet | false | Hide the puppeteer controlled browser. This can allow you to work on the computer while it is running in the background. |
To run a subset of renders or scenarios do something like this:
% npm run render-goldens -- --scenario=clearcoat -q
NOTE: In the above example, the -- is required to separate the arguments to npm run render-goldens from the arguments to the script itself.