pw_unit_test/public/pw_unit_test/internal/framework.h - pigweed/pigweed - Git at Google

 // 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
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // 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"

 #if PW_CXX_STANDARD_IS_SUPPORTED(17)
 #include <string_view>

 #include "pw_string/string_builder.h"
 #endif  // PW_CXX_STANDARD_IS_SUPPORTED(17)

 #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.
 #if !(defined(GTEST_DONT_DEFINE_TEST) && GTEST_DONT_DEFINE_TEST)
 #define TEST(test_suite_name, test_name) GTEST_TEST(test_suite_name, test_name)
 #endif  // !GTEST_DONT_DEFINE_TEST

 #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.
 #if !(defined(GTEST_DONT_DEFINE_FAIL) && GTEST_DONT_DEFINE_FAIL)
 #define FAIL() GTEST_FAIL()
 #endif  // !GTEST_DONT_DEFINE_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.
 #if !(defined(GTEST_DONT_DEFINE_SUCCEED) && GTEST_DONT_DEFINE_SUCCEED)
 #define SUCCEED() GTEST_SUCCEED()
 #endif  // !GTEST_DONT_DEFINE_SUCCEED

 // 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() \
   ::pw::unit_test::internal::Framework::Get().RunAllTests()

 // Death tests are not supported. The *_DEATH_IF_SUPPORTED macros do nothing.
 #define GTEST_HAS_DEATH_TEST 0

 #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) \
   EXPECT_DEATH_IF_SUPPORTED(statement, regex)

 namespace pw {

 #if PW_CXX_STANDARD_IS_SUPPORTED(17)

 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>", value.id);
 //   }
 //
 //   }  // 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

 #endif  // PW_CXX_STANDARD_IS_SUPPORTED(17)

 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 {
  public:
   constexpr Framework()
       : current_test_(nullptr),
         current_result_(TestResult::kSuccess),
         run_tests_summary_{.passed_tests = 0,
                            .failed_tests = 0,
                            .skipped_tests = 0,
                            .disabled_tests = 0},
         exit_status_(0),
         event_handler_(nullptr),
         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();

 #if PW_CXX_STANDARD_IS_SUPPORTED(17)
   // 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;
   }
 #endif  // PW_CXX_STANDARD_IS_SUPPORTED(17)

   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) {
     static_assert(
         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();
     framework.StartTest(test_info);

     // 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;
     test_instance->PigweedTestRun();

     // Manually call the destructor as it is not called automatically for
     // objects constructed using placement new.
     test_instance->~TestInstance();

     framework.EndCurrentTest();
   }

   // 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);
     CurrentTestExpectSimple(
         expression,
 #if PW_CXX_STANDARD_IS_SUPPORTED(17)
         MakeString<kExpectationBufferSizeBytes>(ConvertForPrint(lhs),
                                                 ' ',
                                                 expectation_string,
                                                 ' ',
                                                 ConvertForPrint(rhs))
             .c_str(),
 #else
         "(evaluation requires C++17)",
 #endif  // PW_CXX_STANDARD_IS_SUPPORTED(17)
         line,
         success);
     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);

  private:
   // 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_;

 #if PW_CXX_STANDARD_IS_SUPPORTED(17)
   span<std::string_view> test_suites_to_run_;
 #else
   span<const char*> test_suites_to_run_;  // Always empty in C++14.
 #endif  // PW_CXX_STANDARD_IS_SUPPORTED(17)

   std::aligned_storage_t<config::kMemoryPoolSize, alignof(std::max_align_t)>
       memory_pool_;
 };

 // 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 {
  public:
   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) {
     Framework::Get().RegisterTest(this);
   }

   // 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; }

  private:
   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 {
  public:
   Test(const Test&) = delete;
   Test& operator=(const Test&) = delete;

   virtual ~Test() = default;

   // Runs the unit test.
   void PigweedTestRun() {
     SetUp();
     // TODO(deymo): Skip the test body if there's a fatal error in SetUp().
     if (!Framework::Get().IsSkipped()) {
       PigweedTestBody();
     }
     TearDown();
   }

  protected:
   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() {}

  private:
   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

 #if PW_CXX_STANDARD_IS_SUPPORTED(17)
 inline void SetTestSuitesToRun(span<std::string_view> test_suites) {
   internal::Framework::Get().SetTestSuitesToRun(test_suites);
 }
 #endif  // PW_CXX_STANDARD_IS_SUPPORTED(17)

 }  // 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,                         \
                  parent_class)

 #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 */ \
   /* with the PW_UNIT_TEST_LINK_FILE_CONTAINING_TEST macro. */              \
   /* 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,                                       \
       __LINE__)

 #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,                                     \
       __LINE__)

 #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,                                     \
       __LINE__)

 // 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_DIAGNOSTICS_PUSH();                                                \
   PW_MODIFY_DIAGNOSTIC(ignored, "-Wredundant-decls");                          \
   extern "C" return_type /* use extern "C" to escape namespacing */            \
       PwUnitTestSuiteNamesMustBeUniqueBetweenTESTandTEST_F_##test_suite(void); \
   PW_MODIFY_DIAGNOSTICS_POP()
 #endif  // GCC8 or older.

 // Alias Test as ::testing::Test for GoogleTest compatibility.
 namespace testing {

 using Test = ::pw::unit_test::internal::Test;

 }  // namespace testing
	// 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
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// 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"

	#if PW_CXX_STANDARD_IS_SUPPORTED(17)
	#include <string_view>

	#include "pw_string/string_builder.h"
	#endif // PW_CXX_STANDARD_IS_SUPPORTED(17)

	#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.
	#if !(defined(GTEST_DONT_DEFINE_TEST) && GTEST_DONT_DEFINE_TEST)
	#define TEST(test_suite_name, test_name) GTEST_TEST(test_suite_name, test_name)
	#endif // !GTEST_DONT_DEFINE_TEST

	#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.
	#if !(defined(GTEST_DONT_DEFINE_FAIL) && GTEST_DONT_DEFINE_FAIL)
	#define FAIL() GTEST_FAIL()
	#endif // !GTEST_DONT_DEFINE_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.
	#if !(defined(GTEST_DONT_DEFINE_SUCCEED) && GTEST_DONT_DEFINE_SUCCEED)
	#define SUCCEED() GTEST_SUCCEED()
	#endif // !GTEST_DONT_DEFINE_SUCCEED

	// 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() \
	::pw::unit_test::internal::Framework::Get().RunAllTests()

	// Death tests are not supported. The *_DEATH_IF_SUPPORTED macros do nothing.
	#define GTEST_HAS_DEATH_TEST 0

	#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) \
	EXPECT_DEATH_IF_SUPPORTED(statement, regex)

	namespace pw {

	#if PW_CXX_STANDARD_IS_SUPPORTED(17)

	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>", value.id);
	// }
	//
	// } // 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

	#endif // PW_CXX_STANDARD_IS_SUPPORTED(17)

	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 {
	public:
	constexpr Framework()
	: current_test_(nullptr),
	current_result_(TestResult::kSuccess),
	run_tests_summary_{.passed_tests = 0,
	.failed_tests = 0,
	.skipped_tests = 0,
	.disabled_tests = 0},
	exit_status_(0),
	event_handler_(nullptr),
	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();

	#if PW_CXX_STANDARD_IS_SUPPORTED(17)
	// 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;
	}
	#endif // PW_CXX_STANDARD_IS_SUPPORTED(17)

	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) {
	static_assert(
	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();
	framework.StartTest(test_info);

	// 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;
	test_instance->PigweedTestRun();

	// Manually call the destructor as it is not called automatically for
	// objects constructed using placement new.
	test_instance->~TestInstance();

	framework.EndCurrentTest();
	}

	// 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);
	CurrentTestExpectSimple(
	expression,
	#if PW_CXX_STANDARD_IS_SUPPORTED(17)
	MakeString<kExpectationBufferSizeBytes>(ConvertForPrint(lhs),
	' ',
	expectation_string,
	' ',
	ConvertForPrint(rhs))
	.c_str(),
	#else
	"(evaluation requires C++17)",
	#endif // PW_CXX_STANDARD_IS_SUPPORTED(17)
	line,
	success);
	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);

	private:
	// 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_;

	#if PW_CXX_STANDARD_IS_SUPPORTED(17)
	span<std::string_view> test_suites_to_run_;
	#else
	span<const char*> test_suites_to_run_; // Always empty in C++14.
	#endif // PW_CXX_STANDARD_IS_SUPPORTED(17)

	std::aligned_storage_t<config::kMemoryPoolSize, alignof(std::max_align_t)>
	memory_pool_;
	};

	// 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 {
	public:
	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) {
	Framework::Get().RegisterTest(this);
	}

	// 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; }

	private:
	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 {
	public:
	Test(const Test&) = delete;
	Test& operator=(const Test&) = delete;

	virtual ~Test() = default;

	// Runs the unit test.
	void PigweedTestRun() {
	SetUp();
	// TODO(deymo): Skip the test body if there's a fatal error in SetUp().
	if (!Framework::Get().IsSkipped()) {
	PigweedTestBody();
	}
	TearDown();
	}

	protected:
	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() {}

	private:
	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

	#if PW_CXX_STANDARD_IS_SUPPORTED(17)
	inline void SetTestSuitesToRun(span<std::string_view> test_suites) {
	internal::Framework::Get().SetTestSuitesToRun(test_suites);
	}
	#endif // PW_CXX_STANDARD_IS_SUPPORTED(17)

	} // 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, \
	parent_class)

	#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 */ \
	/* with the PW_UNIT_TEST_LINK_FILE_CONTAINING_TEST macro. */ \
	/* 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, \
	__LINE__)

	#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, \
	__LINE__)

	#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, \
	__LINE__)

	// 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_DIAGNOSTICS_PUSH(); \
	PW_MODIFY_DIAGNOSTIC(ignored, "-Wredundant-decls"); \
	extern "C" return_type /* use extern "C" to escape namespacing */ \
	PwUnitTestSuiteNamesMustBeUniqueBetweenTESTandTEST_F_##test_suite(void); \
	PW_MODIFY_DIAGNOSTICS_POP()
	#endif // GCC8 or older.

	// Alias Test as ::testing::Test for GoogleTest compatibility.
	namespace testing {

	using Test = ::pw::unit_test::internal::Test;

	} // namespace testing