Test ROS 2 packages and analyze results using colcon. Use when asked to run tests, check code coverage, view test results, debug test failures, or generate coverage reports. Supports single-package testing, full workspace tests, coverage collection, and result visualization.
Run ROS 2 tests efficiently and analyze results with comprehensive coverage reporting and interactive result visualization.
scripts/setup.bash available in workspace rootcolcon buildUse for rapid iteration when developing and testing a single package.
Source the ROS environment with venv updates:
source scripts/setup.bash --update-venv
Run tests for the package only:
python3 -m colcon test \
--event-handlers console_cohesion+ summary+ status+ \
--return-code-on-test-failure \
--packages-select <package_name>
For the full drqp_gazebo launch suite, opt out of the default smoke-only mode:
DRQP_GAZEBO_TEST_MODE=all python3 -m colcon test \
--event-handlers console_cohesion+ summary+ status+ \
--return-code-on-test-failure \
--packages-select drqp_gazebo \
--mixin coverage-pytest
Without DRQP_GAZEBO_TEST_MODE=all, drqp_gazebo runs only the smoke subset and skips non-smoke slow launch tests.
Check test results in console output (summary appears at end)
View detailed test logs in log/latest_test/<package_name>/
Typical execution time: 1-5 minutes depending on test count
Use when you need code coverage metrics alongside test execution.
Source the ROS environment with venv updates:
source scripts/setup.bash --update-venv
Run tests with coverage enabled:
python3 -m colcon test \
--event-handlers console_cohesion+ summary+ status+ \
--return-code-on-test-failure \
--packages-select <package_name> \
--mixin coverage-pytest
Coverage data is collected automatically:
build/<package_name>/coverage.info (LCOV format)build/<package_name>/.coverage (Coverage.py format)WARNING: Full test suite takes 10-20+ minutes. Only run when explicitly requested or before final integration.
Source the ROS environment with venv updates:
source scripts/setup.bash --update-venv
Run all tests with coverage:
python3 -m colcon test \
--event-handlers console_cohesion+ summary+ status+ \
--return-code-on-test-failure \
--mixin coverage-pytest
Wait for all packages to complete (monitor progress in console)
Use to save time when retesting after fixing failures.
Source the ROS environment:
source scripts/setup.bash --update-venv
Re-run only previously failed tests:
python3 -m colcon test \
--event-handlers console_cohesion+ summary+ status+ \
--return-code-on-test-failure \
--packages-select-test-failures
Check which tests now pass in the summary
Examine test output and failure details.
View test summary across workspace:
python3 -m colcon test-result --all
View verbose test results with error details:
python3 -m colcon test-result --verbose
Find detailed test logs:
ls -la log/latest_test/
Process LLVM coverage data and prepare for analysis.
Source the ROS environment:
source scripts/setup.bash
Process LLVM coverage for C++ packages:
./packages/cmake/llvm-cov-export-all.py ./build
Coverage data is exported to formats compatible with:
View coverage in VS Code:
build/**/*.infoExplore test results with interactive visualization.
Launch xunit-viewer server:
npx -y xunit-viewer -r build --server -o build/xunit-index.html \
-i Test.xml -i coverage.xml -i package.xml --watch
Open browser to http://localhost:3000
Browse test results, failures, and coverage interactively
Stop server with Ctrl+C
| Location | Contains | Format |
|---|---|---|
build/<package_name>/test_results/<package_name>/ | Test execution results | xunit.xml |
log/latest_test/<package_name>/ | Test execution logs | Text/JSON |
build/<package_name>/coverage.info | C++ coverage data | LCOV |
build/<package_name>/.coverage | Python coverage data | Coverage.py |
| Issue | Cause | Solution |
|---|---|---|
| "No tests found" | Package has no tests or wrong package name | Verify test/ directory exists in package |
| Tests fail with "module not found" | Python dependencies missing | Run source scripts/setup.bash --update-venv |
| "Command 'pytest' not found" | venv not updated | Run source scripts/setup.bash --update-venv |
| Coverage data not generated | Coverage not enabled in build | Rebuild with --mixin coverage-pytest during build |
| Xunit-viewer won't start | Node.js or npx not available | Install Node.js or use alternative viewer |
| Test results missing or incomplete | Build artifacts cleaned | Rebuild packages before testing |
| Tests timeout or hang | Test blocking on I/O or infinite loop | Check test logs in log/latest_test/ |
drqp_gazebo launch tests are skipped | Default smoke-only mode is active | Re-run with DRQP_GAZEBO_TEST_MODE=all to include the full Gazebo suite |
colcon test option details