blob: 73af3928e11f304fd9b33de311fed4b22185ed7a [file] [log] [blame]
// Copyright 2020 The Pigweed Authors
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
// The Pigweed unit test framework requires C++17 to use its full functionality.
#pragma once
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <new>
#include "pw_polyfill/standard.h"
#include "pw_preprocessor/compiler.h"
#include "pw_preprocessor/util.h"
#include "pw_span/span.h"
#include "pw_unit_test/config.h"
#include "pw_unit_test/event_handler.h"
#include <string_view>
#include "pw_string/string_builder.h"
#define GTEST_TEST(test_suite_name, test_name) \
_PW_TEST_SUITE_NAMES_MUST_BE_UNIQUE(void /* TEST */, test_suite_name); \
_PW_TEST(test_suite_name, test_name, ::pw::unit_test::internal::Test)
// TEST() is a pretty generic macro name which could conflict with other code.
// If GTEST_DONT_DEFINE_TEST is set, don't alias GTEST_TEST to TEST.
#define TEST(test_suite_name, test_name) GTEST_TEST(test_suite_name, test_name)
#define TEST_F(test_fixture, test_name) \
_PW_TEST_SUITE_NAMES_MUST_BE_UNIQUE(int /* TEST_F */, test_fixture); \
_PW_TEST(test_fixture, test_name, test_fixture)
#define EXPECT_TRUE(expr) static_cast<void>(_PW_TEST_BOOL(expr, true))
#define EXPECT_FALSE(expr) static_cast<void>(_PW_TEST_BOOL(expr, false))
#define EXPECT_EQ(lhs, rhs) static_cast<void>(_PW_TEST_OP(lhs, rhs, ==))
#define EXPECT_NE(lhs, rhs) static_cast<void>(_PW_TEST_OP(lhs, rhs, !=))
#define EXPECT_GT(lhs, rhs) static_cast<void>(_PW_TEST_OP(lhs, rhs, >))
#define EXPECT_GE(lhs, rhs) static_cast<void>(_PW_TEST_OP(lhs, rhs, >=))
#define EXPECT_LT(lhs, rhs) static_cast<void>(_PW_TEST_OP(lhs, rhs, <))
#define EXPECT_LE(lhs, rhs) static_cast<void>(_PW_TEST_OP(lhs, rhs, <=))
#define EXPECT_STREQ(lhs, rhs) static_cast<void>(_PW_TEST_C_STR(lhs, rhs, ==))
#define EXPECT_STRNE(lhs, rhs) static_cast<void>(_PW_TEST_C_STR(lhs, rhs, !=))
#define ASSERT_TRUE(expr) _PW_TEST_ASSERT(_PW_TEST_BOOL(expr, true))
#define ASSERT_FALSE(expr) _PW_TEST_ASSERT(_PW_TEST_BOOL(expr, false))
#define ASSERT_EQ(lhs, rhs) _PW_TEST_ASSERT(_PW_TEST_OP(lhs, rhs, ==))
#define ASSERT_NE(lhs, rhs) _PW_TEST_ASSERT(_PW_TEST_OP(lhs, rhs, !=))
#define ASSERT_GT(lhs, rhs) _PW_TEST_ASSERT(_PW_TEST_OP(lhs, rhs, >))
#define ASSERT_GE(lhs, rhs) _PW_TEST_ASSERT(_PW_TEST_OP(lhs, rhs, >=))
#define ASSERT_LT(lhs, rhs) _PW_TEST_ASSERT(_PW_TEST_OP(lhs, rhs, <))
#define ASSERT_LE(lhs, rhs) _PW_TEST_ASSERT(_PW_TEST_OP(lhs, rhs, <=))
#define ASSERT_STREQ(lhs, rhs) _PW_TEST_ASSERT(_PW_TEST_C_STR(lhs, rhs, ==))
#define ASSERT_STRNE(lhs, rhs) _PW_TEST_ASSERT(_PW_TEST_C_STR(lhs, rhs, !=))
// Generates a non-fatal failure with a generic message.
#define ADD_FAILURE() \
::pw::unit_test::internal::Framework::Get().CurrentTestExpectSimple( \
"(line is not executed)", "(line was executed)", __LINE__, false)
// Generates a fatal failure with a generic message.
#define GTEST_FAIL() return ADD_FAILURE()
// Skips test at runtime, which is neither successful nor failed. Skip aborts
// current function.
#define GTEST_SKIP() \
return ::pw::unit_test::internal::Framework::Get().CurrentTestSkip(__LINE__)
// Define either macro to 1 to omit the definition of FAIL(), which is a
// generic name and clashes with some other libraries.
#define FAIL() GTEST_FAIL()
// Generates a success with a generic message.
#define GTEST_SUCCEED() \
::pw::unit_test::internal::Framework::Get().CurrentTestExpectSimple( \
"(success)", "(success)", __LINE__, true)
// Define either macro to 1 to omit the definition of SUCCEED(), which
// is a generic name and clashes with some other libraries.
// pw_unit_test framework entry point. Runs every registered test case and
// dispatches the results through the event handler. Returns a status of zero
// if all tests passed, or nonzero if there were any failures.
// This is compatible with GoogleTest.
// In order to receive test output, an event handler must be registered before
// this is called:
// int main() {
// MyEventHandler handler;
// pw::unit_test::RegisterEventHandler(&handler);
// return RUN_ALL_TESTS();
// }
#define RUN_ALL_TESTS() \
// Death tests are not supported. The *_DEATH_IF_SUPPORTED macros do nothing.
#define EXPECT_DEATH_IF_SUPPORTED(statement, regex) \
if (0) { \
static_cast<void>(statement); \
static_cast<void>(regex); \
} \
static_assert(true, "Macros must be terminated with a semicolon")
#define ASSERT_DEATH_IF_SUPPORTED(statement, regex) \
namespace pw {
namespace string {
// This function is used to print unknown types that are used in EXPECT or
// ASSERT statements in tests.
// You can add support for displaying custom types by defining a ToString
// template specialization. For example:
// namespace pw {
// template <>
// StatusWithSize ToString<MyType>(const MyType& value,
// span<char> buffer) {
// return string::Format("<MyType|%d>",;
// }
// } // namespace pw
// See the documentation in pw_string/string_builder.h for more information.
template <typename T>
StatusWithSize UnknownTypeToString(const T& value, span<char> buffer) {
StringBuilder sb(buffer);
sb << '<' << sizeof(value) << "-byte object at 0x" << &value << '>';
return sb.status_with_size();
} // namespace string
namespace unit_test {
// Sets the event handler for a test run. Must be called before RUN_ALL_TESTS()
// to receive test output.
void RegisterEventHandler(EventHandler* event_handler);
namespace internal {
class Test;
class TestInfo;
// Used to tag arguments to EXPECT_STREQ/EXPECT_STRNE so they are treated like C
// strings rather than pointers.
struct CStringArg {
const char* const c_str;
// Singleton test framework class responsible for managing and running test
// cases. This implementation is internal to Pigweed test; free functions
// wrapping its functionality are exposed as the public interface.
class Framework {
constexpr Framework()
: current_test_(nullptr),
run_tests_summary_{.passed_tests = 0,
.failed_tests = 0,
.skipped_tests = 0,
.disabled_tests = 0},
memory_pool_() {}
static Framework& Get() { return framework_; }
// Registers a single test case with the framework. The framework owns the
// registered unit test. Called during static initialization.
void RegisterTest(TestInfo* test) const;
// Sets the handler to which the framework dispatches test events. During a
// test run, the framework owns the event handler.
void RegisterEventHandler(EventHandler* event_handler) {
event_handler_ = event_handler;
// Runs all registered test cases, returning a status of 0 if all succeeded or
// nonzero if there were any failures. Test events that occur during the run
// are sent to the registered event handler, if any.
int RunAllTests();
// Only run test suites whose names are included in the provided list during
// the next test run. This is C++17 only; older versions of C++ will run all
// non-disabled tests.
void SetTestSuitesToRun(span<std::string_view> test_suites) {
test_suites_to_run_ = test_suites;
bool ShouldRunTest(const TestInfo& test_info) const;
// Whether the current test is skipped.
bool IsSkipped() const { return current_result_ == TestResult::kSkipped; }
// Constructs an instance of a unit test class and runs the test.
// Tests are constructed within a static memory pool at run time instead of
// being statically allocated to avoid blowing up the size of the test binary
// in cases where users have large test fixtures (e.g. containing buffers)
// reused many times. Instead, only a small, fixed-size TestInfo struct is
// statically allocated per test case, with a run() function that references
// this method instantiated for its test class.
template <typename TestInstance>
static void CreateAndRunTest(const TestInfo& test_info) {
sizeof(TestInstance) <= sizeof(memory_pool_),
"The test memory pool is too small for this test. Either increase "
"PW_UNIT_TEST_CONFIG_MEMORY_POOL_SIZE or decrease the size of your "
"test fixture.");
Framework& framework = Get();
// Reset the memory pool to a marker value to help detect use of
// uninitialized memory.
std::memset(&framework.memory_pool_, 0xa5, sizeof(framework.memory_pool_));
// Construct the test object within the static memory pool. The StartTest
// function has already been called by the TestInfo at this point.
TestInstance* test_instance = new (&framework.memory_pool_) TestInstance;
// Manually call the destructor as it is not called automatically for
// objects constructed using placement new.
// Runs an expectation function for the currently active test case.
template <typename Expectation, typename Lhs, typename Rhs>
bool CurrentTestExpect(Expectation expectation,
const Lhs& lhs,
const Rhs& rhs,
[[maybe_unused]] const char* expectation_string,
const char* expression,
int line) {
// Size of the buffer into which to write the string with the evaluated
// version of the arguments. This buffer is allocated on the unit test's
// stack, so it shouldn't be too large.
// TODO(hepler): Make this configurable.
[[maybe_unused]] constexpr size_t kExpectationBufferSizeBytes = 128;
const bool success = expectation(lhs, rhs);
' ',
' ',
"(evaluation requires C++17)",
return success;
// Skips the current test and dispatches an event for it.
void CurrentTestSkip(int line);
// Dispatches an event indicating the result of an expectation.
void CurrentTestExpectSimple(const char* expression,
const char* evaluated_expression,
int line,
bool success);
// Convert char* to void* so that they are printed as pointers instead of
// strings in EXPECT_EQ and other macros. EXPECT_STREQ wraps its pointers in a
// CStringArg so its pointers are treated like C strings.
static constexpr const void* ConvertForPrint(const char* str) { return str; }
static constexpr const void* ConvertForPrint(char* str) { return str; }
static constexpr const char* ConvertForPrint(CStringArg value) {
return value.c_str;
template <typename T>
static constexpr T ConvertForPrint(T&& value) {
return std::forward<T>(value);
// Sets current_test_ and dispatches an event indicating that a test started.
void StartTest(const TestInfo& test);
// Dispatches event indicating that a test finished and clears current_test_.
void EndCurrentTest();
// Singleton instance of the framework class.
static Framework framework_;
// Linked list of all registered test cases. This is static as it tests are
// registered using static initialization.
static TestInfo* tests_;
// The current test case which is running.
const TestInfo* current_test_;
// Overall result of the current test case (pass/fail/skip).
TestResult current_result_;
// Overall result of the ongoing test run, which covers multiple tests.
RunTestsSummary run_tests_summary_;
// Program exit status returned by RunAllTests for GoogleTest compatibility.
int exit_status_;
// Handler to which to dispatch test events.
EventHandler* event_handler_;
span<std::string_view> test_suites_to_run_;
span<const char*> test_suites_to_run_; // Always empty in C++14.
std::aligned_storage_t<config::kMemoryPoolSize, alignof(std::max_align_t)>
// Information about a single test case, including a pointer to a function which
// constructs and runs the test class. These are statically allocated instead of
// the test classes, as test classes can be very large.
class TestInfo {
TestInfo(const char* const test_suite_name,
const char* const test_name,
const char* const file_name,
void (*run_func)(const TestInfo&))
: test_case_{
.suite_name = test_suite_name,
.test_name = test_name,
.file_name = file_name,
}, run_(run_func) {
// The name of the suite to which the test case belongs, the name of the test
// case itself, and the path to the file in which the test case is located.
const TestCase& test_case() const { return test_case_; }
bool enabled() const;
void run() const { run_(*this); }
TestInfo* next() const { return next_; }
void set_next(TestInfo* next) { next_ = next; }
TestCase test_case_;
// Function which runs the test case. Refers to Framework::CreateAndRunTest
// instantiated for the test case's class.
void (*run_)(const TestInfo&);
// TestInfo structs are registered with the test framework and stored as a
// linked list.
TestInfo* next_ = nullptr;
// Base class for all test cases or custom test fixtures.
// Every unit test created using the TEST or TEST_F macro defines a class that
// inherits from this (or a subclass of this).
// For example, given the following test definition:
// TEST(MyTest, SaysHello) {
// ASSERT_STREQ(SayHello(), "Hello, world!");
// }
// A new class is defined for the test, e.g. MyTest_SaysHello_Test. This class
// inherits from the Test class and implements its PigweedTestBody function with
// the block provided to the TEST macro.
class Test {
Test(const Test&) = delete;
Test& operator=(const Test&) = delete;
virtual ~Test() = default;
// Runs the unit test.
void PigweedTestRun() {
// TODO(deymo): Skip the test body if there's a fatal error in SetUp().
if (!Framework::Get().IsSkipped()) {
Test() = default;
// Called immediately before executing the test body.
// Setup and cleanup can typically be done in the test fixture's constructor
// and destructor, but there are cases where SetUp/TearDown must be used
// instead. See the Google Test documentation for more information.
virtual void SetUp() {}
// Called immediately after executing the test body.
virtual void TearDown() {}
friend class internal::Framework;
// The user-provided body of the test case. Populated by the TEST macro.
virtual void PigweedTestBody() = 0;
// Checks that a test suite name is valid.
constexpr bool HasNoUnderscores(const char* suite) {
const char* disabled_prefix = "DISABLED_";
for (; *suite != '\0'; ++suite) {
if (*suite == *disabled_prefix) {
disabled_prefix += 1;
} else {
disabled_prefix = "";
if (*suite == '_') {
return false;
return true;
} // namespace internal
inline void SetTestSuitesToRun(span<std::string_view> test_suites) {
} // namespace unit_test
} // namespace pw
#define _PW_TEST(test_suite_name, test_name, parent_class) \
static_assert(sizeof(#test_suite_name) > 1, \
"The test suite name must not be empty"); \
static_assert(::pw::unit_test::internal::HasNoUnderscores(#test_suite_name), \
"The test suite name (" #test_suite_name \
") cannot contain underscores"); \
static_assert(sizeof(#test_name) > 1, "The test name must not be empty"); \
_PW_TEST_CLASS(test_suite_name, \
test_name, \
test_suite_name##_##test_name##_Test, \
#define _PW_TEST_CLASS(suite, name, class_name, parent_class) \
class class_name final : public parent_class { \
private: \
void PigweedTestBody() override; \
}; \
extern "C" { \
/* Declare the TestInfo as non-const since const variables do not work */ \
/* NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables) */ \
::pw::unit_test::internal::TestInfo _pw_unit_test_Info_##suite##_##name( \
#suite, \
#name, \
__FILE__, \
::pw::unit_test::internal::Framework::CreateAndRunTest<class_name>); \
} /* extern "C" */ \
void class_name::PigweedTestBody()
#define _PW_TEST_ASSERT(expectation) \
do { \
if (!(expectation)) { \
return static_cast<void>(0); /* Prevent using ASSERT in constructors. */ \
} \
} while (0)
#define _PW_TEST_BOOL(expr, value) \
::pw::unit_test::internal::Framework::Get().CurrentTestExpect( \
[](bool lhs, bool rhs) { return lhs == rhs; }, \
static_cast<bool>(expr), \
value, \
"is", \
#expr " is " #value, \
#define _PW_TEST_OP(lhs, rhs, op) \
::pw::unit_test::internal::Framework::Get().CurrentTestExpect( \
[](const auto& _pw_lhs, const auto& _pw_rhs) { \
return _pw_lhs op _pw_rhs; \
}, \
(lhs), \
(rhs), \
#op, \
#lhs " " #op " " #rhs, \
#define _PW_TEST_C_STR(lhs, rhs, op) \
::pw::unit_test::internal::Framework::Get().CurrentTestExpect( \
[](const auto& _pw_lhs, const auto& _pw_rhs) { \
return std::strcmp(_pw_lhs.c_str, _pw_rhs.c_str) op 0; \
}, \
::pw::unit_test::internal::CStringArg{lhs}, \
::pw::unit_test::internal::CStringArg{rhs}, \
#op, \
#lhs " " #op " " #rhs, \
// Checks that test suite names between TEST and TEST_F declarations are unique.
// This works by declaring a function named for the test suite. The function
// takes no arguments but is declared with different return types in the TEST
// and TEST_F macros. If a TEST and TEST_F use the same test suite name, the
// function declarations conflict, resulting in a compilation error.
// This catches most conflicts, but a runtime check is ultimately needed since
// tests may be declared in different translation units.
#if !defined(__clang__) && !defined(__GNUC___) && __GNUC__ <= 8
// For some reason GCC8 is unable to ignore -Wredundant-decls here.
#define _PW_TEST_SUITE_NAMES_MUST_BE_UNIQUE(return_type, test_suite)
#else // All other compilers.
#define _PW_TEST_SUITE_NAMES_MUST_BE_UNIQUE(return_type, test_suite) \
PW_MODIFY_DIAGNOSTIC(ignored, "-Wredundant-decls"); \
extern "C" return_type /* use extern "C" to escape namespacing */ \
PwUnitTestSuiteNamesMustBeUniqueBetweenTESTandTEST_F_##test_suite(void); \
#endif // GCC8 or older.
// Alias Test as ::testing::Test for GoogleTest compatibility.
namespace testing {
using Test = ::pw::unit_test::internal::Test;
} // namespace testing