mirror of
https://github.com/IfcOpenShell/IfcOpenShell.git
synced 2026-08-09 17:31:45 +00:00
Document viewer test commands
Add IfcOpenShell-Python and IfcViewer test-running documentation, including desktop CTest targets and web Playwright smoke tests. Move the web test README content into the Sphinx docs.\n\nGenerated with the assistance of an AI coding tool.
This commit is contained in:
Dion Moult
@@ -19,3 +19,4 @@ capabilities of the C++ core are available in Python.
|
||||
ifcopenshell-python/selector_syntax
|
||||
ifcopenshell-python/schema_querying
|
||||
ifcopenshell-python/validation
|
||||
ifcopenshell-python/running_tests
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
.. This file was generated with the assistance of an AI coding tool.
|
||||
|
||||
Running tests
|
||||
=============
|
||||
|
||||
IfcOpenShell-Python tests live in ``src/ifcopenshell-python/test`` and use
|
||||
``pytest``. From the repository root, enter the Python package directory before
|
||||
running the test suite:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd src/ifcopenshell-python
|
||||
|
||||
Install the test runner in the Python environment you are using for
|
||||
development:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install pytest
|
||||
|
||||
Full test suite
|
||||
---------------
|
||||
|
||||
Use the Makefile target for the default test suite:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make test
|
||||
|
||||
This runs:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pytest -p no:pytest-blender test --ignore=test/util/test_shape_builder.py
|
||||
|
||||
The ``pytest-blender`` plugin is disabled because these are IfcOpenShell-Python
|
||||
tests, not Bonsai Blender tests. The shape builder tests are split into a
|
||||
separate target because they require Blender's ``mathutils`` package.
|
||||
|
||||
Parallel tests
|
||||
--------------
|
||||
|
||||
For a faster local run, install ``pytest-xdist`` and use the parallel target:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install pytest-xdist
|
||||
make test-parallel
|
||||
|
||||
This automatically uses the available CPU count and runs the same tests as
|
||||
``make test``.
|
||||
|
||||
Shape builder tests
|
||||
-------------------
|
||||
|
||||
The shape builder tests require ``mathutils``. Run them separately:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install mathutils
|
||||
make test-mathutils
|
||||
|
||||
Running individual tests
|
||||
------------------------
|
||||
|
||||
You can run an individual file or test directly with ``pytest``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pytest -p no:pytest-blender test/test_file.py
|
||||
pytest -p no:pytest-blender test/util/test_unit.py
|
||||
pytest -p no:pytest-blender test/test_file.py::TestFile::test_creating_a_new_file
|
||||
|
||||
Coverage
|
||||
--------
|
||||
|
||||
To generate an HTML coverage report, install ``coverage`` and run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install coverage
|
||||
make coverage
|
||||
|
||||
The report is written to ``htmlcov``.
|
||||
@@ -0,0 +1,16 @@
|
||||
.. This file was generated with the assistance of an AI coding tool.
|
||||
|
||||
IfcViewer
|
||||
=========
|
||||
|
||||
IfcViewer is the WebGPU-based IFC viewer used by Bonsai Viewer and the
|
||||
standalone viewer targets. It includes shared loading, sidecar, streaming,
|
||||
selection, visibility, and viewport state code used by both desktop and web
|
||||
frontends.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
:caption: Contents:
|
||||
|
||||
ifcviewer/running_tests
|
||||
@@ -0,0 +1,128 @@
|
||||
.. This file was generated with the assistance of an AI coding tool.
|
||||
|
||||
Running tests
|
||||
=============
|
||||
|
||||
IfcViewer has two test layers:
|
||||
|
||||
1. **Desktop tests**: C++ unit tests for the shared viewer core and desktop
|
||||
support code.
|
||||
2. **Web tests**: headless-browser smoke tests for the Emscripten/WebGPU
|
||||
frontend.
|
||||
|
||||
The desktop tests are in ``src/ifcviewer/tests``. The web tests are in
|
||||
``src/ifcviewer-web/tests``.
|
||||
|
||||
Desktop tests
|
||||
-------------
|
||||
|
||||
The desktop tests are Catch2 executables registered with CTest. They cover
|
||||
pure viewer logic such as sidecar layout, streaming loaders, selection,
|
||||
visibility, instance composition, buffer-pool allocation, and viewport camera
|
||||
state.
|
||||
|
||||
Configure a desktop build with viewer tests enabled:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake -S cmake -B build-viewer-wgpu \
|
||||
-G Ninja \
|
||||
-DBUILD_BONSAIVIEWER=ON \
|
||||
-DBUILD_BONSAIVIEWER_TESTS=ON
|
||||
|
||||
Build and run all registered tests:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake --build build-viewer-wgpu
|
||||
ctest --test-dir build-viewer-wgpu --output-on-failure
|
||||
|
||||
To run only the IfcViewer tests, filter by test name:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ctest --test-dir build-viewer-wgpu -R "test_(sidecar|streaming|selection|visibility|buffer|viewport|federation|instance|chunk|lod)" --output-on-failure
|
||||
|
||||
You can also build or run a single test executable directly:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake --build build-viewer-wgpu --target test_sidecar_cache
|
||||
./build-viewer-wgpu/ifcviewer/tests/test_sidecar_cache
|
||||
|
||||
Common test targets include:
|
||||
|
||||
* ``test_sidecar_compress``
|
||||
* ``test_sidecar_cache``
|
||||
* ``test_streaming_loader``
|
||||
* ``test_instanced_geometry``
|
||||
* ``test_chunk_planner``
|
||||
* ``test_sidecar_layout``
|
||||
* ``test_instance_compose``
|
||||
* ``test_selection``
|
||||
* ``test_visibility``
|
||||
* ``test_buffer_pool``
|
||||
* ``test_viewport_camera``
|
||||
* ``test_federation``
|
||||
|
||||
Web tests
|
||||
---------
|
||||
|
||||
The web tests are Playwright smoke tests for the WebGPU/Emscripten build. They
|
||||
load the built page in Chrome, wait for WebGPU initialisation, and assert that
|
||||
the embedded sample renders non-blank, interactions change the framebuffer,
|
||||
and no uncaptured WebGPU errors are logged.
|
||||
|
||||
First build the web viewer from the repository root. This requires an
|
||||
Emscripten environment:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
source /path/to/emsdk_env.sh
|
||||
emcmake cmake -S src/ifcviewer-web -B build-web
|
||||
ninja -C build-web IfcViewerWeb
|
||||
|
||||
Install the web test dependencies once:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd src/ifcviewer-web/tests
|
||||
npm install
|
||||
|
||||
Run the web smoke tests:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
npm test
|
||||
|
||||
The Playwright configuration starts ``serve.mjs`` automatically. The server
|
||||
serves ``build-web`` on ``http://localhost:8124``. Override the build directory
|
||||
or port with environment variables:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
WEB_BUILD_DIR=/path/to/build-web PORT=9000 npm test
|
||||
|
||||
Chrome requirements
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The test configuration uses the system Chrome channel, so a system Chrome such
|
||||
as ``google-chrome-stable`` must be installed. You do not need to run
|
||||
``npx playwright install`` unless you change the Playwright browser channel.
|
||||
|
||||
Headless and CI runs
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
WebGPU in headless Linux environments can be sensitive to the GPU and browser
|
||||
configuration. The default configuration runs headed against the machine's real
|
||||
GPU. On a headless machine, use Xvfb:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
xvfb-run -a npm test
|
||||
|
||||
For a GPU-less runner, change ``headless`` to ``true`` in
|
||||
``playwright.config.mjs`` and provide a SwiftShader Vulkan ICD, for example via
|
||||
``VK_ICD_FILENAMES=/path/to/vk_swiftshader_icd.json`` together with a Chrome
|
||||
``--use-angle=swiftshader`` argument. This is slower than a real GPU but is
|
||||
enough for render-non-blank smoke checks.
|
||||
@@ -12,6 +12,7 @@ Let's learn IfcOpenShell!
|
||||
ifcopenshell
|
||||
ifcopenshell-python
|
||||
ifcconvert
|
||||
ifcviewer
|
||||
bonsai
|
||||
bonsai-viewer
|
||||
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
# Web smoke tests
|
||||
|
||||
Headless-browser smoke tests for the WebGPU/Emscripten ifcviewer build.
|
||||
They load the built page in a real Chrome, wait for wgpu init, and assert
|
||||
the embedded sample **renders non-blank**, an **orbit drag changes the
|
||||
framebuffer**, and **no uncaptured WebGPU errors** are logged. Every web
|
||||
bring-up bug so far (blank render, error-buffer cascade, an overlay
|
||||
swallowing mouse input) is this shape.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The web build must exist at `build-web/` (repo root):
|
||||
```sh
|
||||
source /path/to/emsdk_env.sh
|
||||
emcmake cmake -S src/ifcviewer-web -B build-web
|
||||
ninja -C build-web IfcViewerWeb
|
||||
```
|
||||
- Node + a system Chrome (`google-chrome-stable`). The config uses
|
||||
`channel: 'chrome'`, so you do **not** need `npx playwright install`.
|
||||
|
||||
## Run
|
||||
|
||||
```sh
|
||||
cd src/ifcviewer-web/tests
|
||||
npm install # one-time: pulls @playwright/test
|
||||
npm test
|
||||
```
|
||||
|
||||
`serve.mjs` statically serves `build-web` on :8124 (override with
|
||||
`WEB_BUILD_DIR=/path PORT=...`). Playwright starts it automatically.
|
||||
|
||||
## Headless / CI
|
||||
|
||||
WebGPU + headless on Linux is finicky, so the default config runs
|
||||
**headed** against the machine's real GPU. On a headless box:
|
||||
|
||||
```sh
|
||||
xvfb-run -a npm test
|
||||
```
|
||||
|
||||
For a GPU-less runner, flip `headless: true` in
|
||||
`playwright.config.mjs` and provide a SwiftShader Vulkan ICD
|
||||
(`VK_ICD_FILENAMES=.../vk_swiftshader_icd.json`) plus
|
||||
`--use-angle=swiftshader`. Browser WebGPU over SwiftShader is slow but
|
||||
adequate for a render-non-blank assertion.
|
||||
Reference in New Issue
Block a user