Testing
Three test layers: Catch2 for the engine, Rust unit/integration tests for Doppio, and headless UI flows that drive the real widget tree without a window. CI runs all three.
Layers#
| Layer | Framework | Command | Location |
|---|---|---|---|
| C++ engine | Catch2 v3 | ctest --output-on-failure | tests/, binary build/tests/CaffeineTest |
| Rust editor | cargo test | cd doppio && cargo test | doppio/crates/ui/src/windows/main/tests.rs, engine crate tests |
| Headless UI flows | doppio-headless | ./scripts/check-rust-ui.sh | doppio/tests/ui-flows/*.json |
C++ suite#
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
cd build && ctest --output-on-failure
Run one tag or test directly:
./build/tests/CaffeineTest "[ecs]"
./build/tests/CaffeineTest "World *" --success
Tests are tagged; [stress] marks the long-running cases that CI runs only on a
manual workflow_dispatch. The suite covers core types, allocators, containers, math,
ECS, jobs, assets, RHI, physics, audio, animation, scripting, terrain and the C ABI.
Rust editor suite#
cd doppio
cargo test
cargo test -p doppio-ui --features headless
The headless feature runs the committed flows through
every_shipped_flow_passes. The editor suite covers App messages, pane/docking
state, inspector edits, hierarchy search, viewport gestures, console filters, asset
wizard and the generator graphs.
Headless UI flows#
./scripts/doppio-headless.sh run doppio/tests/ui-flows --format text
Each flow starts from a deterministic fixture, acts with id:/text: targets and
asserts with expect. Screenshots, baselines and GIF/MP4 recording are available for
visual work. See Headless testing
and Test automation.
CI#
.github/workflows/test.yml runs on pushes to main, develop and feature/**, and
on pull requests to main/develop:
- configure and build with GCC 13;
./build/tests/CaffeineTest ~[stress] --success;./scripts/check-rust-ui.sh;- optionally
./build/tests/CaffeineTest "[stress]" --successon manual dispatch.
A change is ready when both the C++ suite and the Rust/headless checks pass. A user-visible editor change adds a flow; an engine behaviour change adds a Catch2 case.
Writing tests#
Catch2 conventions
- File per module:
tests/test_<module>.cpp. - Use
TEST_CASE("Behaviour", "[module]")andSECTIONfor variants. - Prefer deterministic data; no sleeps, real GPU windows or network.
- Tag slow cases
[stress]so the default CI run skips them.
Headless flow conventions
- Start from
entities,emptyor a generator fixture. - Use catalogue ids, not screen points, unless the point is the behaviour.
- Assert after each meaningful action and label the assertion.
- Keep screenshots as artifacts; use baselines only for visual regressions.