Caffeine

Testing

Stable Engine Doppio Last verified: Source: tests/CMakeLists.txt

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#

LayerFrameworkCommandLocation
C++ engineCatch2 v3ctest --output-on-failuretests/, binary build/tests/CaffeineTest
Rust editorcargo testcd doppio && cargo testdoppio/crates/ui/src/windows/main/tests.rs, engine crate tests
Headless UI flowsdoppio-headless./scripts/check-rust-ui.shdoppio/tests/ui-flows/*.json

C++ suite#

bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
cd build && ctest --output-on-failure

Run one tag or test directly:

bash
./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#

bash
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#

bash
./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:

  1. configure and build with GCC 13;
  2. ./build/tests/CaffeineTest ~[stress] --success;
  3. ./scripts/check-rust-ui.sh;
  4. optionally ./build/tests/CaffeineTest "[stress]" --success on 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]") and SECTION for 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, empty or 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.