bimplus-renderer 1.8.39 → 1.8.40-webifc1.0

package/README.md

@@ -79,7 +79,7 @@ goto your application folder which uses the renderer
   npm install
 
 ### Unit testing
-Run tests from the renderer root. Vitest is the only installed test runner; the
+Run tests from the renderer root. Vitest runs the unit and geometry DDT suites; the
 test files import Vitest APIs directly. Browser globals, fixtures, and
 test-only dependencies are initialized in `test/setup/vitestBrowser.setup.js`.
 
@@ -144,6 +144,75 @@ npm run test-vitest-modelviewer-chrome
 npm run test-vitest-modelviewer-chrome-long
 ```
 
+### Modelviewer image comparison (Playwright Test)
+
+The standalone Playwright suite loads each IFC into the real renderer, checks
+viewport diagnostics, fits a fixed perspective view without camera animation,
+and compares the 1000 x 700 viewport against a PNG baseline. It uses the same
+Vite shader/asset configuration and viewer helpers as the geometry DDT, without
+reading or changing `Results.db` or requiring the DDT server.
+
+```sh
+npx playwright install firefox chromium
+npm run test-modelviewer-ddt-visual
+npm run test-modelviewer-ddt-visual-long
+npx playwright test --project=chromium
+npx playwright test --project=chromium-long
+```
+
+The IFC datasets must be present locally (use `sync-modelviewer-ddt` or
+`sync-modelviewer-ddt-long` if needed). Only the selected dataset is required.
+To run only one model, use Playwright's title filter:
+
+```sh
+npm run test-modelviewer-ddt-visual -- --grep "BasicProject.ifc"
+```
+
+Missing baselines fail normal runs. To create only missing baselines without
+replacing existing images:
+
+```sh
+npm run test-modelviewer-ddt-visual-init
+npm run test-modelviewer-ddt-visual-long-init
+```
+
+To explicitly replace baselines after reviewing an intentional rendering change:
+
+```sh
+npm run test-modelviewer-ddt-visual -- --update-snapshots
+npm run test-modelviewer-ddt-visual-long -- --update-snapshots
+```
+
+Review the images before committing them under
+`modelviewer-data-driven-tests/playwright/snapshots/`. Baselines are separated
+by browser, dataset, and OS; generate and compare using the same OS and GPU
+environment. The included Windows Firefox baselines cover both datasets;
+other browser/OS combinations need their own initial baseline generation.
+The per-test timeout is 100 minutes and includes IFC loading; the separate
+15-second screenshot timeout starts only after loading and camera setup finish.
+An `A snapshot doesn't exist` error means a baseline is missing, not that
+loading timed out. Use the initialization command above in that case.
+Comparisons allow a per-pixel color
+threshold of 0.2 but no differing pixels above that threshold. Playwright waits for consecutive stable
+screenshots rather than using a fixed sleep. Failures produce expected, actual,
+and diff images under `test-results/modelviewer-visual/`; the HTML report is
+in `playwright-report/`, with JUnit output in
+`test-results/playwright-modelviewer-visual.xml`.
+
+The HTML reporter uses hashed filenames internally. Actual comparison images
+from failed comparisons are also copied directly to
+`playwright-report/data/named/`, using the baseline filename without the
+`-actual` suffix, for example `BasicProject-ifc.png`.
+The filename comes from the matching baseline, preserving the full name even
+when Playwright shortens the failure artifact's filename with a hash.
+There are no subfolders, expected images, diff images, or full-page failure
+screenshots in this folder.
+If multiple browsers, repeats, or retries produce the same filename, the last
+result in report order replaces the earlier copy; run one browser at a time
+to keep its images separate. The internal hashed files are retained so the
+HTML report's image viewer continues to work, including expected and diff
+images. Both sets of report images are regenerated on each run.
+
 Vitest writes JUnit output under `test-results/`. Firefox Istanbul coverage is
 written under `coverage/`, including `coverage/lcov.info` for CI artifact
 collection. Coverage instruments renderer source under `src/`, excluding