// 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.
Configure and build gz-sim from source using either CMake/Ninja directly or a colcon workspace. Trigger when the user asks to build, recompile, configure, or set up the gz-sim binary tree.
Concise reference for the gz-sim Entity-Component-System architecture — how Entities, Components, Systems, the ECM, the Server, and SimulationRunner fit together. Trigger when the user asks how gz-sim is organized, where to add code, or how the simulation loop runs.
Scaffold a new ECS component header under include/gz/sim/components/, wire its CMake listing, and (if needed) register it with ComponentFactory for serialization. Trigger when the user asks to add a new component or a per-entity data field.
Scaffold a new Nav 2 plugin (controller, planner, behavior, smoother, goal-checker, progress-checker, costmap layer, or BT node). Wires pluginlib registration, parameter declaration on the lifecycle node, and a minimal integration test. Trigger when the user asks to write or extend a Nav 2 plugin.
Scaffold a new ROS 2 package (ament_python or ament_cmake) inside a colcon workspace, restructured to follow this template's Clean Architecture layout. Trigger when the user asks to create a new ROS 2 package or to bootstrap a Clean-Architecture-compliant codebase.
Scaffold a new gz-sim system plugin under src/systems/<name>/ — header, source, CMake glue, plugin registration, and an integration test stub. Trigger when the user asks to create a new system, controller, or plugin that hooks into the simulation loop.
| 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. |
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 |
ctest --test-dir build --output-on-failure -j"$(nproc)"
CI requires this to be clean before merge.
# 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_'
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
Most GUI tests need a display. Wrap with xvfb:
xvfb-run -s '-screen 0 1280x1024x24' \
ctest --test-dir build -R '^INTEGRATION_' --output-on-failure
cmake --build build -j$(nproc) --target INTEGRATION_foo../build/bin/INTEGRATION_foo --gtest_filter=Bar.*.-DCMAKE_CXX_FLAGS="-fsanitize=thread").gdb --args ./build/bin/INTEGRATION_foo --gtest_filter=Bar.NameOfCase
test/worlds/ — many integration
tests load a world from there../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.
ctest --test-dir build -R '^PYTHON_'
These exercise the pybind11 bindings.
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.