pw_unit_test#
GoogleTest for embedded
Stable
#include "mylib.h"
#include "pw_unit_test/framework.h"
namespace {
TEST(MyTestSuite, MyTestCase) {
pw::InlineString<32> expected = "(╯°□°)╯︵ ┻━┻";
pw::InlineString<32> actual = mylib::flip_table();
EXPECT_STREQ(expected.c_str(), actual.c_str());
}
}
load("@pigweed//pw_unit_test:pw_cc_test.bzl", "pw_cc_test")
cc_library(
name = "mylib",
srcs = ["mylib.cc"],
hdrs = ["mylib.h"],
includes = ["."],
deps = ["@pigweed//pw_string"],
)
pw_cc_test(
name = "mylib_test",
srcs = ["mylib_test.cc"],
deps = [
"@pigweed//pw_unit_test",
":mylib",
],
)
#include "mylib.h"
#include "pw_string/string.h"
namespace mylib {
pw::InlineString<32> flip_table() {
pw::InlineString<32> textmoji = "(╯°□°)╯︵ ┻━┻";
return textmoji;
}
}
#include "pw_string/string.h"
namespace mylib {
pw::InlineString<32> flip_table();
}
pw_unit_test
provides a GoogleTest-compatible unit testing framework for
Pigweed-based projects. The default backend is a lightweight subset of
GoogleTest that uses embedded-friendly primitives.
Quickstart#
Set up your build system#
Load the pw_cc_test rule and create a target
that depends on @pigweed//pw_unit_test
as well as the code you want
to test:
load("@pigweed//pw_unit_test:pw_cc_test.bzl", "pw_cc_test")
cc_library(
name = "mylib",
srcs = ["mylib.cc"],
hdrs = ["mylib.h"],
includes = ["."],
deps = ["..."],
)
pw_cc_test(
name = "mylib_test",
srcs = ["mylib_test.cc"],
deps = [
"@pigweed//pw_unit_test",
":mylib",
],
)
This assumes that your Bazel WORKSPACE
has a repository named @pigweed
that points to the upstream Pigweed repository.
See also Bazel API reference.
Import $dir_pw_unit_test/test.gni
and create a pw_test
rule that
depends on the code you want to test:
import("$dir_pw_unit_test/test.gni")
pw_source_set("mylib") {
sources = [ "mylib.cc" ]
}
pw_test("mylib_test") {
sources = [ "mylib_test.cc" ]
deps = [ ":mylib" ]
}
See GN reference for more information.
pw_unit_test
generates a simple main
function for running tests on
host. See Create a custom main function to learn how to
create your own main
function for running on-device tests.
Write tests#
Create test suites and test cases:
#include "mylib.h"
#include "pw_unit_test/framework.h"
namespace {
TEST(MyTestSuite, MyTestCase) {
pw::InlineString<32> expected = "(╯°□°)╯︵ ┻━┻";
pw::InlineString<32> actual = app::flip_table();
EXPECT_STREQ(expected.c_str(), actual.c_str());
}
}
pw_unit_test
provides a standard set of TEST
, EXPECT
, ASSERT
and FAIL
macros. The default backend, pw_unit_test:light
, offers an
embedded-friendly implementation which prioritizes small code size.
Alternativley, users can opt into a larger set of assertion macros, matchers,
and more detailed error messages by using the pw_unit_test:googletest
backend. See Choose a backend.
See GoogleTest Primer for the basics of using GoogleTest.
Run tests#
$ bazel test //src:mylib_test
Run the generated test binary:
$ ./out/.../mylib_test
Guides#
Choose a backend#
The default backend, pw_unit_test:light
, is a lightweight subset of
GoogleTest that uses embedded-friendly primitives. It’s also highly portable
because it offloads the responsibility of test reporting and output to the
underlying system, communicating its results through a common interface. This
lets you write unit tests once and run them under many different environments.
If the subset of GoogleTest that
pw_unit_test:light
supports doesn’t meet your needs, you can access the
full upstream GoogleTest API through pw_unit_test:googletest
. See
Use upstream GoogleTest.
Create a custom main
function#
For simple unit tests that run on host the workflow outlined in
Quickstart is all you need. Pigweed’s build templates
generate a simple main
function to run the tests with.
To do more complex testing, such as on-device testing:
Create your own
main
function:#include "pw_unit_test/framework.h" // pw_unit_test:light requires an event handler to be configured. #include "pw_unit_test/simple_printing_event_handler.h" void WriteString(std::string_view string, bool newline) { printf("%s", string.data()); if (newline) { printf("\n"); } } int main() { // Make the binary compatible with pw_unit_test:googletest. Has no effect // when using pw_unit_test:light. testing::InitGoogleTest(); // Set up the event handler for pw_unit_test:light. pw::unit_test::SimplePrintingEventHandler handler(WriteString); pw::unit_test::RegisterEventHandler(&handler); return RUN_ALL_TESTS(); }
See Create event handlers for more information about handling events.
Set the build argument that instructs your build system to use your custom
main
function:Bazel:
pw_unit_test_main
Create event handlers#
The pw::unit_test::EventHandler
class defines the interface through which
pw_unit_test:light
communicates the results of its test runs. If you’re
using a custom main function you need to
register an event handler to receive test output from the framework.
Predefined event handlers#
Pigweed provides some standard event handlers to simplify the process of
getting started with pw_unit_test:light
. All event handlers provide for
GoogleTest-style output using the shared
pw::unit_test::GoogleTestStyleEventHandler
base. Example
output:
[==========] Running all tests.
[ RUN ] Status.Default
[ OK ] Status.Default
[ RUN ] Status.ConstructWithStatusCode
[ OK ] Status.ConstructWithStatusCode
[ RUN ] Status.AssignFromStatusCode
[ OK ] Status.AssignFromStatusCode
[ RUN ] Status.CompareToStatusCode
[ OK ] Status.CompareToStatusCode
[ RUN ] Status.Ok_OkIsTrue
[ OK ] Status.Ok_OkIsTrue
[ RUN ] Status.NotOk_OkIsFalse
[ OK ] Status.NotOk_OkIsFalse
[ RUN ] Status.KnownString
[ OK ] Status.KnownString
[ RUN ] Status.UnknownString
[ OK ] Status.UnknownString
[==========] Done running all tests.
[ PASSED ] 8 test(s).
Run a subset of test suites#
Note
This feature is only supported in C++17.
To run only a subset of registered test suites, use the
pw::unit_test::SetTestSuitesToRun
function. See
//pw_unit_test/light_public_overrides/pw_unit_test/framework_backend.h.
This is useful when you’ve got a lot of test suites bundled up into a single test binary and you only need to run some of them.
Skip tests in Bazel#
Use target_compatible_with
in Bazel to skip tests. The following test is
skipped when using upstream GoogleTest:
load("//pw_unit_test:pw_cc_test.bzl", "pw_cc_test")
pw_cc_test(
name = "no_upstream_test",
srcs = ["no_upstream_test.cc"],
target_compatible_with = select({
"//pw_unit_test:light_setting": [],
"//conditions:default": ["@platforms//:incompatible"],
}),
}
Run tests in static libraries#
To run tests in a static library, use the
PW_UNIT_TEST_LINK_FILE_CONTAINING_TEST
macro.
Linkers usually ignore tests through static libraries (i.e. .a
files)
because test registration relies on the test instance’s static constructor
adding itself to a global list of tests. When linking against a static library,
static constructors in an object file are ignored unless at least one entity
in that object file is linked.
Use upstream GoogleTest#
To use the upstream GoogleTest backend (pw_unit_test:googletest
) instead
of the default backend:
Clone the GoogleTest repository into your project. See GoogleTest.
Combine GoogleTestHandlerAdapter with a predefined event handler to enable your
main
function to work with upstream GoogleTest without modification.#include "pw_unit_test/framework.h" #include "pw_unit_test/logging_event_handler.h" int main() { testing::InitGoogleTest(); pw::unit_test::LoggingEventHandler logger; pw::unit_test::RegisterEventHandler(&logger); return RUN_ALL_TESTS(); }
If your tests needs GoogleTest functionality not included in the default
pw_unit_test:light
backend, include the upstream GoogleTest headers (e.g.gtest/gtest.h
) directly and guard your target definition to avoid compiling withpw_unit_test:light
(the default backend).
Run tests over serial#
To accelerate automated unit test bringup for devices with plain-text logging,
pw_unit_test
provides a serial-based test runner in Python that triggers a
device flash and evaluates whether the test passed or failed based on the
produced output.
To set up a serial test runner in Python:
Implement a
SerialTestingDevice
class for your device. See //pw_unit_test/py/pw_unit_test/serial_test_runner.py.Configure your device code to wait to run unit tests until
DEFAULT_TEST_START_CHARACTER
is sent over the serial connection.
Run tests over RPC#
pw_unit_test
provides an RPC service which runs unit tests on demand and
streams the results back to the client. The service is defined in
//pw_unit_test/pw_unit_test_proto/unit_test.proto.
The RPC service is primarily intended for use with the default
pw_unit_test:light
backend. It has some support for the upstream GoogleTest
backend (pw_unit_test:googletest
), however some features (such as test suite
filtering) are missing.
To set up RPC-based unit tests in your application:
Depend on the relevant target for your build system:
Bazel:
@pigweed//pw_unit_test:rpc_service
GN:
$dir_pw_unit_test:rpc_service
Create a
pw::unit_test::UnitTestService
instance.Register the instance with your RPC server.
#include "pw_rpc/server.h" #include "pw_unit_test/unit_test_service.h" pw::rpc::Channel channels[] = { pw::rpc::Channel::Create<1>(&my_output), }; pw::rpc::Server server(channels); pw::unit_test::UnitTestService unit_test_service; void RegisterServices() { server.RegisterService(unit_test_services); }
See pw_rpc for more guidance around setting up RPC.
Run tests that have been flashed to a device by calling
pw_unit_test.rpc.run_tests()
in Python. The argument should be an RPC client services object that has the unit testing RPC service enabled. By default, the results output via logging. The return value is aTestRecord
dataclass instance containing the results of the test run.import serial from pw_hdlc import rpc from pw_unit_test.rpc import run_tests PROTO = Path( os.environ['PW_ROOT'], 'pw_unit_test/pw_unit_test_proto/unit_test.proto' ) serial_device = serial.Serial(device, baud) with rpc.SerialReader(serial_device) as reader: with rpc.HdlcRpcClient( reader, PROTO, rpc.default_channels(serial_device.write) ) as client: run_tests(client.rpcs())
C++ API reference#
pw_unit_test:light
API compatibility#
pw_unit_test:light
offers a number of primitives for test declaration,
assertion, event handlers, and configuration.
Note
The googletest_test_matchers
target which provides Pigweed-specific
StatusIs
, IsOkAndHolds
, ASSERT_OK
, and ASSERT_OK_AND_ASSIGN
isn’t part of the pw_unit_test:light
backend. These matchers are only
usable when including the full upstream GoogleTest backend.
Missing features include:
GoogleMock and matchers (e.g.
EXPECT_THAT
).Death tests (e.g.
EXPECT_DEATH
).EXPECT_DEATH_IF_SUPPORTED
does nothing but silently passes.Value-parameterized tests.
Stream messages (e.g.
EXPECT_TRUE(...) << "My message"
) will compile, but no message will be logged.
See Use upstream GoogleTest for guidance on using the
upstream GoogleTest backend (pw_unit_test:googletest
) instead of
pw_unit_test:light
.
Test declaration#
Note that TEST_F
may allocate fixtures separately from the stack.
Large variables should be stored in test fixture fields,
rather than stack variables. This allows the test framework to statically ensure
that enough space is available to store these variables.
-
TEST(test_suite_name, test_name)#
Defines a test given the suite name and test case name.
If
TEST
is conflicting with other code, setGTEST_DONT_DEFINE_TEST
to 1 and useGTEST_TEST
instead.- Parameters:
test_suite_name – [in] The name of the test suite or collection of tests.
test_name – [in] The name of the test case.
-
GTEST_TEST(test_suite_name, test_name)#
Alias for
TEST
.
-
TEST_F(test_fixture, test_name)#
Defines a test case using a test fixture.
- Parameters:
test_fixture – [in] The name of the test fixture class to use.
test_name – [in] The name of the test case.
-
FRIEND_TEST(test_suite_name, test_name)#
Defines a test case from a test suite as a friend class of an implementation class.
Warning
Use of
FRIEND_TEST
is discouraged, because it induces coupling between testing and implementation code. Consider this a last resort only.- Parameters:
test_suite_name – [in] The name of the test suite to befriend.
test_name – [in] The name of the test case to befriend.
Test control#
-
FAIL()#
Generates a fatal failure with a generic message.
If this generic name is clashing with other code, set
GTEST_DONT_DEFINE_FAIL
to 1 and useGTEST_FAIL
instead.
-
GTEST_FAIL()#
Alias of
FAIL
.
-
SUCCEED()#
Generates success with a generic message.
If this generic name is conflicting with other code, set
GTEST_DONT_DEFINE_SUCCEED
to 1 and useGTEST_SUCCEED
instead.
-
GTEST_SUCCEED()#
Alias of
SUCCEED
.
-
GTEST_SKIP()#
Skips test at runtime. Skips are neither successful nor failed. They abort the current function.
-
ADD_FAILURE()#
Generates a non-fatal failure with a generic message.
-
RUN_ALL_TESTS()#
The
pw_unit_test
framework entrypoint. Runs every registered test case and dispatches the results through the event handler.- Pre:
An event handler has been registered before calling
RUN_ALL_TESTS
.- Returns:
A status of 0 if all tests passed, or non-zero if there were any failures. This is compatible with GoogleTest.
-
GTEST_HAS_DEATH_TEST#
Death tests are not supported. The
*_DEATH_IF_SUPPORTED
macros do nothing.
-
EXPECT_DEATH_IF_SUPPORTED(statement, regex)#
See
GTEST_HAS_DEATH_TEST
.
-
ASSERT_DEATH_IF_SUPPORTED(statement, regex)#
See
GTEST_HAS_DEATH_TEST
.
Expectations#
When a test fails an expectation, the framework marks the test as a failure and then continues executing the test. They’re useful when you want to verify multiple dimensions of the same feature and see all the errors at the same time.
-
EXPECT_TRUE(expr)#
Verifies that
expr
evaluates to true.- Parameters:
expr – [in] The expression to evaluate.
-
EXPECT_FALSE(expr)#
Verifies that
expr
evaluates to false.- Parameters:
expr – [in] The expression to evaluate.
-
EXPECT_EQ(lhs, rhs)#
Verifies that
lhs == rhs
.Does pointer equality on pointers. If used on two C strings,
EXPECT_EQ
tests if they are in the same memory location, not if they have the same value. UseEXPECT_STREQ
to compare C strings (e.g.const char*
) by value.When comparing a pointer to
NULL
useEXPECT_EQ(ptr, nullptr)
instead ofEXPECT_EQ(ptr, NULL)
.- Parameters:
lhs – [in] The left side of the equality comparison.
rhs – [in] The right side of the equality comparison.
-
EXPECT_NE(lhs, rhs)#
Verifies that
lhs != rhs
.Does pointer equality on pointers. If used on two C strings, it tests if they are in different memory locations, not if they have different values. Use
EXPECT_STRNE
to compare C strings (e.g.const char*
) by value.When comparing a pointer to
NULL
, useEXPECT_NE(ptr, nullptr)
instead ofEXPECT_NE(ptr, NULL)
.- Parameters:
lhs – [in] The left side of the inequality comparison.
rhs – [in] The right side of the inequality comparison.
-
EXPECT_GT(lhs, rhs)#
Verifies that
lhs > rhs
.- Parameters:
lhs – [in] The left side of the comparison.
rhs – [in] The right side of the comparison.
-
EXPECT_GE(lhs, rhs)#
Verifies that
lhs >= rhs
.- Parameters:
lhs – [in] The left side of the comparison.
rhs – [in] The right side of the comparison.
-
EXPECT_LT(lhs, rhs)#
Verifies that
lhs < rhs
.- Parameters:
lhs – [in] The left side of the comparison.
rhs – [in] The right side of the comparison.
-
EXPECT_LE(lhs, rhs)#
Verifies that
lhs <= rhs
.- Parameters:
lhs – [in] The left side of the comparison.
rhs – [in] The right side of the comparison.
-
EXPECT_NEAR(lhs, rhs, epsilon)#
Verifies that the difference between
lhs
andrhs
does not exceed the absolute error boundepsilon
.- Parameters:
lhs – [in] The left side of the comparison.
rhs – [in] The right side of the comparison.
epsilon – [in] The maximum difference between
lhs
andrhs
.
-
EXPECT_FLOAT_EQ(lhs, rhs)#
Verifies that the two float values
rhs
andlhs
are approximately equal, to within 4 units in the last place (ULPs) from each other.- Parameters:
lhs – [in] The left side of the equality comparison.
rhs – [in] The right side of the equality comparison.
-
EXPECT_DOUBLE_EQ(lhs, rhs)#
Verifies that the two double values
rhs
andlhs
are approximately equal, to within 4 units in the last place (ULPs) from each other.- Parameters:
lhs – [in] The left side of the equality comparison.
rhs – [in] The right side of the equality comparison.
-
EXPECT_STREQ(lhs, rhs)#
Verifies that the two C strings
lhs
andrhs
have the same contents.- Parameters:
lhs – [in] The left side of the equality comparison.
[] – rhs The right side of the equality comparison.
-
EXPECT_STRNE(lhs, rhs)#
Verifies that the two C strings
lhs
andrhs
have different content.- Parameters:
lhs – [in] The left side of the inequality comparison.
rhs – [in] The right side of the inequality comparison.
Assertions#
Assertions work the same as expectations except they stop the execution of the test as soon as a failed condition is met.
-
ASSERT_TRUE(expr)#
See
EXPECT_TRUE
.
-
ASSERT_FALSE(expr)#
See
EXPECT_FALSE
.
-
ASSERT_EQ(lhs, rhs)#
See
EXPECT_EQ
.
-
ASSERT_NE(lhs, rhs)#
See
EXPECT_NE
.
-
ASSERT_GT(lhs, rhs)#
See
EXPECT_GT
.
-
ASSERT_GE(lhs, rhs)#
See
EXPECT_GE
.
-
ASSERT_LT(lhs, rhs)#
See
EXPECT_LT
.
-
ASSERT_LE(lhs, rhs)#
See
EXPECT_LE
.
-
ASSERT_NEAR(lhs, rhs, epsilon)#
See
EXPECT_NEAR
.
-
ASSERT_FLOAT_EQ(lhs, rhs)#
See
EXPECT_FLOAT_EQ
.
-
ASSERT_DOUBLE_EQ(lhs, rhs)#
See
EXPECT_DOUBLE_EQ
.
-
ASSERT_STREQ(lhs, rhs)#
See
EXPECT_STREQ
.
-
ASSERT_STRNE(lhs, rhs)#
See
EXPECT_STRNE
.
Event handlers#
-
void pw::unit_test::RegisterEventHandler(EventHandler *event_handler)#
Sets the event handler for a test run. Must be called before
RUN_ALL_TESTS()
to receive test output. Setevent_handler
to null to disable event handling.Warning
This method is not thread-safe.
-
class EventHandler#
Collects and processes the results of a unit test run. Its interface is called by the unit test framework as tests are executed and various test events occur.
A program wanting to process test events must define a class implementing the
pw::unit_test::EventHandler
interface and register it with the framework. WhenRUN_ALL_TESTS()
is called,pw_unit_test
notifies the handler of various events which occur in the test process. For example, consider a file containing the following test definitions:TEST(MyTestSuite, MyFirstCase) { EXPECT_TRUE(true); } TEST(MyTestSuite, MySecondCase) { EXPECT_TRUE(false); }
There’s one test suite consisting of two test cases. When
pw_unit_test
starts running the first test case (MyFirstCase
), it dispatches aTestCaseStart
event to the event handler. It then runs the body of the test, sequentially checking each expectation within. After each expectation, aTestCaseExpect
event is sent to the event handler with the expectation’s result. In this case, there’s only one, which passes successfully. Finally, after the test is finished, aTestCaseEnd
event is dispatched with the overall result of the test case.pw_unit_test
then runsMySecondCase
in the same way.Subclassed by pw::unit_test::GoogleTestStyleEventHandler, pw::unit_test::LoggingEventHandler, pw::unit_test::MultiEventHandler< kNumHandlers >, pw::unit_test::TestRecordEventHandler
Public Functions
-
virtual void TestProgramStart(const ProgramSummary &program_summary) = 0#
Called before any test activity starts.
-
virtual void EnvironmentsSetUpEnd() = 0#
Called after environment setup for each iteration of tests ends.
-
virtual void TestSuiteStart(const TestSuite &test_suite) = 0#
Called before the test suite starts.
-
virtual void TestSuiteEnd(const TestSuite &test_suite) = 0#
Called after the test suite ends.
-
virtual void EnvironmentsTearDownEnd() = 0#
Called after environment teardown for each iteration of tests ends.
-
virtual void TestProgramEnd(const ProgramSummary &program_summary) = 0#
Called after all test activities have ended.
-
virtual void RunAllTestsStart() = 0#
Called before all tests are run.
-
virtual void RunAllTestsEnd(const RunTestsSummary &run_tests_summary) = 0#
Called after all tests are run.
-
virtual void TestCaseStart(const TestCase &test_case) = 0#
Called when a new test case is started.
-
virtual void TestCaseEnd(const TestCase &test_case, TestResult result) = 0#
Called when a test case completes. The overall result of the test case is provided.
-
inline virtual void TestCaseDisabled(const TestCase&)#
Called when a disabled test case is encountered.
-
virtual void TestCaseExpect(const TestCase &test_case, const TestExpectation &expectation) = 0#
Called after each expect or assert statement within a test case with the result.
-
virtual void TestProgramStart(const ProgramSummary &program_summary) = 0#
-
class GoogleTestHandlerAdapter : public testing::EmptyTestEventListener#
Adapts a custom
main()
function to work with upstream GoogleTest without modification. Custommain()
functions are used for complex testing scenarios, such as on-device testing. Must be paired with a predefined event handler, such aspw::unit_test::GoogleTestStyleEventHandler
. Seepw::unit_test::EventHandler
for an explanation of each event.
-
class GoogleTestStyleEventHandler : public pw::unit_test::EventHandler#
Provides GoogleTest-style output for
pw_unit_test:light
events. Must be extended to define how to output the results. Seepw::unit_test::EventHandler
for an explanation of each event andpw::unit_test::SimplePrintingEventHandler
for an example of a concrete implementation of this interface.Subclassed by pw::unit_test::PrintfEventHandler, pw::unit_test::SimplePrintingEventHandler
-
class SimplePrintingEventHandler : public pw::unit_test::GoogleTestStyleEventHandler#
Predefined event handler implementation that produces human-readable GoogleTest-style test output and sends it to a sink that you define. See
pw::unit_test::EventHandler
for explanations of emitted events.Example:
#include "pw_unit_test/framework.h" // pw_unit_test:light requires an event handler to be configured. #include "pw_unit_test/simple_printing_event_handler.h" void WriteString(std::string_view string, bool newline) { printf("%s", string.data()); if (newline) { printf("\n"); } } int main() { // The following line has no effect with pw_unit_test_light, but makes // this test compatible with upstream GoogleTest. testing::InitGoogleTest(); // Since we are using pw_unit_test:light, set up an event handler. pw::unit_test::SimplePrintingEventHandler handler(WriteString); pw::unit_test::RegisterEventHandler(&handler); return RUN_ALL_TESTS(); }
Example output:
>>> Running MyTestSuite.TestCase1 [SUCCESS] 128 <= 129 [FAILURE] 'a' == 'b' at ../path/to/my/file_test.cc:4831 <<< Test MyTestSuite.TestCase1 failed
-
class LoggingEventHandler : public pw::unit_test::EventHandler#
Predefined event handler implementation that produces human-readable GoogleTest-style test output and logs it via
pw_log
. Seepw::unit_test::EventHandler
for explanations of emitted events.
-
class PrintfEventHandler : public pw::unit_test::GoogleTestStyleEventHandler#
Predefined event handler implementation that produces human-readable GoogleTest-style test output and logs it via
std::printf
. Seepw::unit_test::EventHandler
for explanations of emitted events.
-
template<size_t kNumHandlers>
class MultiEventHandler : public pw::unit_test::EventHandler# Event handler adapter that allows for multiple event handlers to be registered and used during test runs.
-
class TestRecordEventHandler : public pw::unit_test::EventHandler#
Predefined event handler implementation that outputs a test record (or summary) in Chromium JSON Test Results Format. To use it, register the event handler, call the
RUN_ALL_TESTS
macro, then extract the test record json as a string using theGetTestRecordJsonString
method. If you only want to extract the failing tests, set thefailing_results_only
parameter to true. Seepw::unit_test::EventHandler
for explanations of emitted events.Warning
This event handler uses dynamic allocation (
new
/delete
/std::string
) to generate the test record json.
Configuration#
-
PW_UNIT_TEST_CONFIG_EVENT_BUFFER_SIZE#
The size of the event buffer that the
UnitTestService
contains. This buffer is used to encode events. By default this is set to 128 bytes.
-
PW_UNIT_TEST_CONFIG_MEMORY_POOL_SIZE#
The size of the memory pool to use for test fixture instances. By default this is set to 16K.
Helpers#
-
PW_UNIT_TEST_LINK_FILE_CONTAINING_TEST(suite, name)#
Ensures tests in a static library are linked and executed. Provide the test suite name and test name for one test in the file linked into a static library. Any test in the file may be used, but it’s recommended to use the first for consistency. The test must be in a static library that’s a dependency of this target. Referring to a test that does not exist causes a linker error.
The linker usually ignores tests linked through a static library because test registration relies on the test instance’s static constructor adding itself to a global list of tests. When linking against a static library, static constructors in an object file will be ignored unless at least one entity in that object file is linked.
This macro works by passing the internal
TestInfo
instance to a constructor defined in a source file. This guarantees that theTestInfo
instance is referenced, so the linker will link it and the other tests in that file.
Python API reference#
pw_unit_test.serial_test_runner
#
Facilitates automating unit tests on devices with serial ports.
This library assumes that the on-device test runner emits the test results
as plain-text over a serial port, and that tests are triggered by a pre-defined
input (DEFAULT_TEST_START_CHARACTER
) over the same serial port that results
are emitted from.
- class pw_unit_test.serial_test_runner.SerialTestingDevice#
A device that supports automated testing via parsing serial output.
- abstract baud_rate() int #
Returns the baud rate to use when connecting to this device.
- Raises:
DeviceNotFound – This device is no longer available.
- abstract load_binary(binary: Path) bool #
Flashes the specified binary to this device.
- Raises:
DeviceNotFound – This device is no longer available.
FlashingFailure – The binary could not be flashed.
- Returns:
True if the binary was loaded successfully.
- abstract serial_port() str #
Returns the name of the com port this device is enumerated on.
- Raises:
DeviceNotFound – This device is no longer available.
- pw_unit_test.serial_test_runner.run_device_test(
- device: ~pw_unit_test.serial_test_runner.SerialTestingDevice,
- binary: ~pathlib.Path,
- test_timeout: float,
- logger: ~logging.Logger = <Logger serial_test_runner (WARNING)>,
Runs tests on a device.
When a unit test run fails, results are logged as an error.
- Parameters:
device – The device to run tests on.
binary – The binary containing tests to flash on the device.
test_timeout – If the device stops producing output longer than this timeout, the test is considered stuck and is aborted.
- Returns:
True if all tests passed.
pw_unit_test.rpc
#
Utilities for running unit tests over pw_rpc.
- class pw_unit_test.rpc.EventHandler#
- abstract run_all_tests_end(passed_tests: int, failed_tests: int) None #
Called after the test run is complete.
- abstract run_all_tests_start() None #
Called before all tests are run.
- abstract test_case_disabled(test_case: TestCase) None #
Called when a disabled test case is encountered.
- abstract test_case_end(test_case: TestCase, result: TestCaseResult) None #
Called when a test case completes with its overall result.
- abstract test_case_expect(test_case: TestCase, expectation: TestExpectation) None #
Called after each expect or assert statement within a test case.
- abstract test_case_start(test_case: TestCase) None #
Called when a new test case is started.
- class pw_unit_test.rpc.TestRecord(
- passing_tests: tuple[TestCase, ...],
- failing_tests: tuple[TestCase, ...],
- disabled_tests: tuple[TestCase, ...],
Records test results.
- __init__(
- passing_tests: tuple[TestCase, ...],
- failing_tests: tuple[TestCase, ...],
- disabled_tests: tuple[TestCase, ...],
- pw_unit_test.rpc.run_tests(
- rpcs: ~pw_rpc.client.Services,
- report_passed_expectations: bool = False,
- test_suites: ~typing.Iterable[str] = (),
- event_handlers: ~typing.Iterable[~pw_unit_test.rpc.EventHandler] = (<pw_unit_test.rpc.LoggingEventHandler object>,
- ),
- timeout_s: ~pw_rpc.callback_client.call.UseDefault | float | None = UseDefault.VALUE,
Runs unit tests on a device over pw_rpc.
Calls each of the provided event handlers as test events occur, and returns
True
if all tests pass.
Build helper libraries#
The following helper libraries can simplify setup and are supported in all build systems.
- simple_printing_event_handler
When running tests, output test results as plain text over
pw_sys_io
.
- simple_printing_main
Implements a
main()
function that simply runs tests using thesimple_printing_event_handler
.
- logging_event_handler
When running tests, log test results as plain text using pw_log. Make sure your target has set a
pw_log
backend.
- logging_main
Implements a
main()
function that simply runs tests using thelogging_event_handler
.
Bazel API reference#
See also Build helper libraries.
pw_cc_test
#
pw_cc_test
is a wrapper for cc_test that provides some defaults, such as
a dependency on @pigweed//pw_unit_test:main
. It supports and passes through
all the arguments recognized by cc_test
.
Bazel build arguments#
- pw_unit_test_backend <target>#
The GoogleTest implementation to use for Pigweed unit tests. This library provides
gtest/gtest.h
and related headers. Defaults to@pigweed//pw_unit_test:light
, which implements a subset of GoogleTest.Type: string (Bazel target label)
Usage: toolchain-controlled only
- pw_unit_test_main <target>#
Implementation of a main function for
pw_cc_test
unit test binaries.Type: string (Bazel target label)
Usage: toolchain-controlled only
GN reference#
See also Build helper libraries.
pw_test
#
pw_test
defines a single unit test suite.
Targets#
- <target_name>
The test suite within a single binary. The test code is linked against the target set in the build arg
pw_unit_test_MAIN
.
- <target_name>.run
If
pw_unit_test_AUTOMATIC_RUNNER
is set, this target runs the test as part of the build.
- <target_name>.lib
The test sources without
pw_unit_test_MAIN
.
Arguments#
All GN executable arguments are accepted and forwarded to the underlying
pw_executable
.
- enable_if#
Boolean indicating whether the test should be built. If false, replaces the test with an empty target. Default true.
- source_gen_deps#
List of target labels that generate source files used by this test. The labels must meet the constraints of GN’s get_target_outputs, namely they must have been previously defined in the current file. This argument is required if a test uses generated source files and
enable_if
can evaluate to false.
- test_main#
Target label to add to the tests’s dependencies to provide the
main()
function. Defaults topw_unit_test_MAIN
. Set to""
ifmain()
is implemented in the test’ssources
.
- test_automatic_runner_args#
Array of args to pass to automatic test runner. Defaults to
pw_unit_test_AUTOMATIC_RUNNER_ARGS
.
- envvars#
Array of
key=value
strings representing environment variables to set when invoking the automatic test runner.
Example#
import("$dir_pw_unit_test/test.gni")
pw_test("large_test") {
sources = [ "large_test.cc" ]
enable_if = device_has_1m_flash
}
pw_test_group
#
pw_test_group
defines a collection of tests or other test groups.
Targets#
- <target_name>
The test group itself.
- <target_name>.run
If
pw_unit_test_AUTOMATIC_RUNNER
is set, this target runs all of the tests in the group and all of its group dependencies individually. See Run tests over serial.
- <target_name>.lib
The sources of all of the tests in this group and their dependencies.
- <target_name>.bundle
All of the tests in the group and its dependencies bundled into a single binary.
- <target_name>.bundle.run
Automatic runner for the test bundle.
Arguments#
- tests#
List of the
pw_test
targets in the group.
- group_deps#
List of other
pw_test_group
targets on which this one depends.
- enable_if#
Boolean indicating whether the group target should be created. If false, an empty GN group is created instead. Default true.
Example#
import("$dir_pw_unit_test/test.gni")
pw_test_group("tests") {
tests = [
":bar_test",
":foo_test",
]
}
pw_test("foo_test") {
# ...
}
pw_test("bar_test") {
# ...
}
pw_facade_test
#
Pigweed facade test templates allow individual unit tests to build under the current device target configuration while overriding specific build arguments. This allows these tests to replace a facade’s backend for the purpose of testing the facade layer.
Facade tests are disabled by default. To build and run facade tests, set the GN
arg pw_unit_test_FACADE_TESTS_ENABLED
to true
.
Warning
Facade tests are costly because each facade test will trigger a re-build of every dependency of the test. While this sounds excessive, it’s the only technically correct way to handle this type of test.
Warning
Some facade test configurations may not be compatible with your target. Be careful when running a facade test on a system that heavily depends on the facade being tested.
GN build arguments#
- pw_unit_test_BACKEND <source_set>#
The GoogleTest implementation to use for Pigweed unit tests. This library provides
gtest/gtest.h
and related headers. Defaults topw_unit_test:light
, which implements a subset of GoogleTest.Type: string (GN path to a source set)
Usage: toolchain-controlled only
- pw_unit_test_MAIN <source_set>#
Implementation of a main function for
pw_test
unit test binaries. See Create a custom main function.Type: string (GN path to a source set)
Usage: toolchain-controlled only
- pw_unit_test_AUTOMATIC_RUNNER <executable>#
Path to a test runner to automatically run unit tests after they are built. See Run tests over serial.
If set, a
pw_test
target’s<target_name>.run
action invokes the test runner specified by this argument, passing the path to the unit test to run. If this is unset, thepw_test
target’s<target_name>.run
step will do nothing.Targets that don’t support parallelized execution of tests (e.g. an on-device test runner that must flash a device and run the test in serial) should set
pw_unit_test_POOL_DEPTH
to1
.Type: string (name of an executable on
PATH
, or a path to an executable)Usage: toolchain-controlled only
- pw_unit_test_AUTOMATIC_RUNNER_ARGS <args>#
An optional list of strings to pass as args to the test runner specified by
pw_unit_test_AUTOMATIC_RUNNER
.Type: list of strings (args to pass to
pw_unit_test_AUTOMATIC_RUNNER
)Usage: toolchain-controlled only
- pw_unit_test_AUTOMATIC_RUNNER_TIMEOUT <timeout_seconds>#
An optional timeout to apply when running the automatic runner. Timeout is in seconds. Defaults to empty which means no timeout.
Type: string (number of seconds to wait before killing test runner)
Usage: toolchain-controlled only
- pw_unit_test_POOL_DEPTH <pool_depth>#
The maximum number of unit tests that may be run concurrently for the current toolchain. Setting this to 0 disables usage of a pool, allowing unlimited parallelization.
Note: A single target with two toolchain configurations (e.g.
release
anddebug
) uses two separate test runner pools by default. Setpw_unit_test_POOL_TOOLCHAIN
to the same toolchain for both targets to merge the pools and force serialization.Type: integer
Usage: toolchain-controlled only
- pw_unit_test_POOL_TOOLCHAIN <toolchain>#
The toolchain to use when referring to the
pw_unit_test
runner pool. When this is disabled, the current toolchain is used. This means that every toolchain will use its own pool definition. If two toolchains should share the same pool, this argument should be by one of the toolchains to the GN path of the other toolchain.Type: string (GN path to a toolchain)
Usage: toolchain-controlled only
- pw_unit_test_EXECUTABLE_TARGET_TYPE <template name>#
The name of the GN target type used to build
pw_unit_test
executables.Type: string (name of a GN template)
Usage: toolchain-controlled only
- pw_unit_test_EXECUTABLE_TARGET_TYPE_FILE <gni file path>#
The path to the
.gni
file that definespw_unit_test_EXECUTABLE_TARGET_TYPE
.If
pw_unit_test_EXECUTABLE_TARGET_TYPE
is not the default ofpw_executable
, this.gni
file is imported to provide the template definition.Type: string (path to a .gni file)
Usage: toolchain-controlled only
- pw_unit_test_FACADE_TESTS_ENABLED <boolean>#
Controls whether to build and run facade tests. Facade tests add considerably to build time, so they are disabled by default.
- pw_unit_test_TESTONLY <boolean>#
Controls the
testonly
variable inpw_test
,pw_test_group
, and miscellaneous testing targets. This is useful if your test libraries (e.g. GoogleTest) used by pw_unit_test have thetestonly
flag set. False by default for backwards compatibility.
CMake reference#
See also Build helper libraries.
pw_add_test
#
pw_add_test
declares a single unit test suite.
Tip
Upstream Pigweed tests can be disabled in downstream projects by setting
pw_unit_test_ENABLE_PW_ADD_TEST
to OFF
before adding the pigweed
directory to an existing cmake build.
set(pw_unit_test_ENABLE_PW_ADD_TEST OFF)
add_subdirectory(path/to/pigweed pigweed)
set(pw_unit_test_ENABLE_PW_ADD_TEST ON)
See also: Use Pigweed from an existing CMake project.
Targets#
- {NAME}
Depends on
${NAME}.run
ifpw_unit_test_AUTOMATIC_RUNNER
is set, else it depends on${NAME}.bin
.
- {NAME}.lib
Contains the provided test sources as a library target, which can then be linked into a test executable.
- {NAME}.bin
A standalone executable which contains only the test sources specified in the
pw_unit_test
template.
- {NAME}.run
Runs the unit test executable after building it if
pw_unit_test_AUTOMATIC_RUNNER
is set, else it fails to build.
Required arguments#
- NAME#
Name to use for the produced test targets specified above.
Optional arguments#
- SOURCES#
Source files for this library.
- HEADERS#
Header files for this library.
- PRIVATE_DEPS#
Private
pw_target_link_targets
arguments.
- PRIVATE_INCLUDES#
Public
target_include_directories
argument.
- PRIVATE_DEFINES#
Private
target_compile_definitions
arguments.
- PRIVATE_COMPILE_OPTIONS#
Private
target_compile_options
arguments.
- PRIVATE_LINK_OPTIONS#
Private
target_link_options
arguments.
Example#
include($ENV{PW_ROOT}/pw_unit_test/test.cmake)
pw_add_test(my_module.foo_test
SOURCES
foo_test.cc
PRIVATE_DEPS
my_module.foo
)
pw_add_test_group
#
pw_add_test_group
defines a collection of tests or other test groups.
Targets#
- {NAME}
Depends on
${NAME}.run
ifpw_unit_test_AUTOMATIC_RUNNER
is set, else it depends on${NAME}.bin
.
- {NAME}.bundle
Depends on
${NAME}.bundle.run
ifpw_unit_test_AUTOMATIC_RUNNER
is set, else it depends on${NAME}.bundle.bin
.
- {NAME}.lib
Depends on
${NAME}.bundle.lib
.
- {NAME}.bin
Depends on the provided
TESTS
’s<test_dep>.bin
targets.
- {NAME}.run
Depends on the provided
TESTS
’s<test_dep>.run
targets ifpw_unit_test_AUTOMATIC_RUNNER
is set, else it fails to build.
- {NAME}.bundle.lib
Contains the provided tests bundled as a library target, which can then be linked into a test executable.
- {NAME}.bundle.bin
Standalone executable which contains the bundled tests.
- {NAME}.bundle.run
Runs the
{NAME}.bundle.bin
test bundle executable after building it ifpw_unit_test_AUTOMATIC_RUNNER
is set, else it fails to build.
Required arguments#
- NAME#
The name of the executable target to be created.
- TESTS#
pw_add_test
targets andpw_add_test_group
bundles to be included in this test bundle.
Example#
include($ENV{PW_ROOT}/pw_unit_test/test.cmake)
pw_add_test_group(tests
TESTS
bar_test
foo_test
)
pw_add_test(foo_test
# ...
)
pw_add_test(bar_test
# ...
)
CMake build arguments#
- pw_unit_test_BACKEND <target>#
The GoogleTest implementation to use for Pigweed unit tests. This library provides
gtest/gtest.h
and related headers. Defaults topw_unit_test.light
, which implements a subset of GoogleTest.Type: string (CMake target name)
Usage: toolchain-controlled only
- pw_unit_test_AUTOMATIC_RUNNER <executable>#
Path to a test runner to automatically run unit tests after they’re built.
If set, a
pw_test
target’s${NAME}
and${NAME}.run
targets will invoke the test runner specified by this argument, passing the path to the unit test to run. If this is unset, thepw_test
target’s${NAME}
will only build the unit test(s) and${NAME}.run
will fail to build.Type: string (name of an executable on the PATH, or path to an executable)
Usage: toolchain-controlled only
- pw_unit_test_AUTOMATIC_RUNNER_ARGS <args>#
An optional list of strings to pass as args to the test runner specified by
pw_unit_test_AUTOMATIC_RUNNER
.Type: list of strings (args to pass to pw_unit_test_AUTOMATIC_RUNNER)
Usage: toolchain-controlled only
- pw_unit_test_AUTOMATIC_RUNNER_TIMEOUT_SECONDS <timeout_seconds>#
An optional timeout to apply when running the automatic runner. Timeout is in seconds. Defaults to empty which means no timeout.
Type: string (number of seconds to wait before killing test runner)
Usage: toolchain-controlled only
- pw_unit_test_ADD_EXECUTABLE_FUNCTION <function name>#
The name of the CMake function used to build
pw_unit_test
executables. The provided function must take aNAME
and aTEST_LIB
argument which are the expected name of the executable target and the target which provides the unit test(s).Type: string (name of a CMake function)
Usage: toolchain-controlled only
- pw_unit_test_ADD_EXECUTABLE_FUNCTION_FILE <cmake file path>#
The path to the
.cmake
file that definespw_unit_test_ADD_EXECUTABLE_FUNCTION
.Type: string (path to a
.cmake
file)Usage: toolchain-controlled only