From a14cecf68b5d1e62d9eb0b4d320e3368a297f4db Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Fri, 3 Jul 2026 09:44:46 +1000 Subject: [PATCH] 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. --- .../docs/ifcopenshell-python.rst | 1 + .../ifcopenshell-python/running_tests.rst | 84 ++++++++++++ src/ifcopenshell-python/docs/ifcviewer.rst | 16 +++ .../docs/ifcviewer/running_tests.rst | 128 ++++++++++++++++++ src/ifcopenshell-python/docs/index.rst | 1 + src/ifcviewer-web/tests/README.md | 45 ------ 6 files changed, 230 insertions(+), 45 deletions(-) create mode 100644 src/ifcopenshell-python/docs/ifcopenshell-python/running_tests.rst create mode 100644 src/ifcopenshell-python/docs/ifcviewer.rst create mode 100644 src/ifcopenshell-python/docs/ifcviewer/running_tests.rst delete mode 100644 src/ifcviewer-web/tests/README.md diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python.rst b/src/ifcopenshell-python/docs/ifcopenshell-python.rst index bbe503c64b..7831bf94eb 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell-python.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell-python.rst @@ -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 diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/running_tests.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/running_tests.rst new file mode 100644 index 0000000000..7692b3371f --- /dev/null +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/running_tests.rst @@ -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``. diff --git a/src/ifcopenshell-python/docs/ifcviewer.rst b/src/ifcopenshell-python/docs/ifcviewer.rst new file mode 100644 index 0000000000..8ec61b270d --- /dev/null +++ b/src/ifcopenshell-python/docs/ifcviewer.rst @@ -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 diff --git a/src/ifcopenshell-python/docs/ifcviewer/running_tests.rst b/src/ifcopenshell-python/docs/ifcviewer/running_tests.rst new file mode 100644 index 0000000000..9d231cbb66 --- /dev/null +++ b/src/ifcopenshell-python/docs/ifcviewer/running_tests.rst @@ -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. diff --git a/src/ifcopenshell-python/docs/index.rst b/src/ifcopenshell-python/docs/index.rst index a460b55f09..3f62c1af66 100644 --- a/src/ifcopenshell-python/docs/index.rst +++ b/src/ifcopenshell-python/docs/index.rst @@ -12,6 +12,7 @@ Let's learn IfcOpenShell! ifcopenshell ifcopenshell-python ifcconvert + ifcviewer bonsai bonsai-viewer diff --git a/src/ifcviewer-web/tests/README.md b/src/ifcviewer-web/tests/README.md deleted file mode 100644 index 8def5a3d8f..0000000000 --- a/src/ifcviewer-web/tests/README.md +++ /dev/null @@ -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.