By name: gz-test description: Run unit, integration, performance, and benchmark tests for gz-sim, filter by name, and debug a single failing case. Trigger when the user asks to test, rerun a test, debug a flaky test, or check that a change didn't regress something.
Running gz-sim tests
gz-sim ships three kinds of tests, all wired through CTest:
| Kind | Source root | Target prefix |
|---|---|---|
| Unit (next to source) | src/**/<Name>_TEST.cc |
UNIT_<Name> |
| Integration | test/integration/<name>.cc |
INTEGRATION_<name> |
| Performance | test/performance/<name>.cc |
PERFORMANCE_<name> |
| Benchmark | test/benchmark/<name>.cc |
BENCHMARK_<name> |
| Plugins (helpers) | test/plugins/ |
built as test fixtures, not run directly |
Run everything
ctest --test-dir build --output-on-failure -j"$(nproc)"
CI requires this to be clean before merge.
Run a subset
# only integration tests
ctest --test-dir build -R '^INTEGRATION_' --output-on-failure
# one specific suite
ctest --test-dir build -R '^UNIT_EntityComponentManager$' -V
# exclude slow/flaky ones during local iteration
ctest --test-dir build -E 'PERFORMANCE_|BENCHMARK_'
Run with the gtest binary directly
This is the fastest way to debug a single failing case, because you get full gtest filter / repeat / shuffle flags:
./build/bin/INTEGRATION_diff_drive_system \
--gtest_filter='DiffDriveTest.*' \
--gtest_repeat=10 \
--gtest_shuffle
Headless / CI environments
Most GUI tests need a display. Wrap with xvfb:
xvfb-run -s '-screen 0 1280x1024x24' \
ctest --test-dir build -R '^INTEGRATION_' --output-on-failure
Debugging a single failure
- Build only that target:
cmake --build build -j$(nproc) --target INTEGRATION_foo. - Reproduce:
./build/bin/INTEGRATION_foo --gtest_filter=Bar.*. - For pointer issues run under ASan; for races use TSan (rebuild with
-DCMAKE_CXX_FLAGS="-fsanitize=thread"). - Under gdb:
gdb --args ./build/bin/INTEGRATION_foo --gtest_filter=Bar.NameOfCase - Check for SDF/world fixtures under
test/worlds/— many integration tests load a world from there.
Performance / benchmarks
./build/bin/BENCHMARK_each --benchmark_min_time=2 \
--benchmark_out=/tmp/each.json --benchmark_out_format=json
Avoid running benchmarks under load — they're noisy on shared machines.
Python tests
ctest --test-dir build -R '^PYTHON_'
These exercise the pybind11 bindings.
After a green run
Tell the user what you ran and which counts came back (e.g. "148 pass / 0 fail / 2 skipped"). Don't claim success without numbers.