test_framework = doctest
Yes
No
No
Doctest is a new C++ testing framework but is by far the fastest both in compile times and runtime compared to other feature-rich alternatives.
To get started with the Doctest all you need is to set
the test_framework option in your “platformio.ini” (Project Configuration File)
to the doctest and implement your own main() function that
forces the Doctest to report successful test cases:
platformio.ini
[env:native]
platform = native
test_framework = doctest
test/test_dummy/test_main.cpp
#define DOCTEST_CONFIG_IMPLEMENT // REQUIRED: Enable custom main()
#include <doctest.h>
// TEST_CASE ...
// TEST_SUITE ...
int main(int argc, char **argv)
{
doctest::Context context;
// BEGIN:: PLATFORMIO REQUIRED OPTIONS
context.setOption("success", true); // Report successful tests
context.setOption("no-exitcode", true); // Do not return non-zero code on failed test case
// END:: PLATFORMIO REQUIRED OPTIONS
// YOUR CUSTOM DOCTEST OPTIONS
context.applyCommandLine(argc, argv);
return context.run();
}
Now, you can run tests using the pio test command. If you need a
full output from the Doctest, please use pio test --verbose
option.
Useful links
The Doctest can be configured in two ways: using identifiers
(macros) or doctest::Context.
The Doctest is designed to “just work” as much as possible. It also allows configuring how it is built with a set of identifiers.
See Doctest Configuration Guide for the available identifiers.
Example
[env:extra_doctest_identifiers]
platform = native
test_framework = doctest
build_flags =
-D DOCTEST_CONFIG_SUPER_FAST_ASSERTS
-D DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION
doctest::Context¶If you need more control and want to set options with code to the
execution context, then the custom implementation of main()
function will give you access to the doctest::Context.
See The “main()” entry point docs for details.
Example
int main(int argc, char **argv)
{
doctest::Context context;
// BEGIN:: PLATFORMIO REQUIRED OPTIONS
context.setOption("success", true); // Reports successful tests
context.setOption("no-exitcode", true); // Do not return non-zero code on failed test case
// END:: PLATFORMIO REQUIRED OPTIONS
// YOUR CUSTOM DOCTEST OPTIONS
context.setOption("abort-after", 5); // stop test execution after 5 failed assertions
context.setOption("order-by", "name"); // sort the test cases by their name
context.applyCommandLine(argc, argv);
return context.run();
}
The Doctest works quite nicely without any command-line options at all - but for more control a few of them are available. See Doctest CLI guide.
There are two options for how to pass extra arguments to the testing program:
Using PlatformIO Core CLI and pio test --program-arg option
Overriding test_testing_command with a custom command.
Example
Stop executing test cases after the first error and include successful
assertions in the output. We will use the -aa, --abort-after=<int>
and -s,--success=<bool> Doctest’s CLI option.
Using CLI and pio test --program-arg option:
> pio test --program-arg "--abort-after=1" --program-arg="-s"
# or short format
> pio test -a "-aa=1" -a "-s"
Overriding test_testing_command with custom command.
[env:myenv]
platform = native
test_testing_command =
${platformio.build_dir}/${this.__env__}/program
-aa=1
-s
If you would like to change the default PlatformIO’s Test Runner for the Doctest, please implement your Custom Testing Framework runner extending DoctestTestRunner class. See Custom Testing Framework for examples.