`test` - Test Packages

The test verb runs the tests for a set of packages. It is provided by the colcon-core package.

Command line arguments

These common arguments can be used:

:doc:`executor <../executor-arguments>` arguments
:doc:`event handler <../event-handler-arguments>` arguments
:doc:`discovery <../discovery-arguments>` arguments
:doc:`package selection <../package-selection-arguments>` arguments
:doc:`mixin <../mixin-arguments>` arguments

Additionally, the following specific command line arguments can be used:

\--build-base BUILD_BASE: The base path for all build directories. The default value is ./build. Each package uses a subdirectory in that base path as its package specific build directory.

\--install-base INSTALL_BASE: The base path for all install prefixes. The default value is ./install.

\--merge-install: Use the --install-base as the install prefix for all packages instead of a package specific subdirectory in the install base. See :ref:`here <build-verb_merge-install_arg>` for more information.

\--test-result-base TEST_RESULT_BASE: The base path for all CTest test results. The default value is the --build-base argument. Each package uses a subdirectory in that base path as its package specific test result directory. This will not determine the location of other artifacts produced by tests such as .xunit.xml files.

\--retest-until-fail N: Rerun tests up to N times if they pass.

\--retest-until-pass N: Rerun failing tests up to N times.

\--abort-on-error: Abort after the first package with any errors. Failing tests are not considered errors in this context.

\--return-code-on-test-failure: Use a non-zero return code to indicate any test failure.

CMake specific arguments

\--ctest-args [* [* ...]] [colcon-cmake]: Pass arbitrary arguments to CTest projects. Arguments matching other options must be prefixed by a space, e.g. --ctest-args " --help".

Python specific arguments

\--python-testing {pytest,setuppy_test}

Choose the Python testing framework to use. The default value is determined based on the packages tests_require option.

pytest: Use pytest to test Python packages.
setuppy_test: Use setup.py test to test Python packages.

\--pytest-args [* [* ...]]: Pass arbitrary arguments to Python packages using pytest. Arguments matching other options must be prefixed by a space, e.g. --pytest-args " --help".

\--pytest-with-coverage: Generate coverage information in the package specific build directory. By default, coverage information is only generated for Python packages that declare a test dependency on pytest-cov.