| // 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) { |
| // TODO(frolv): Update the assert message with the name of the config option |
| // for memory pool size once it is configurable. |
| static_assert( |
| sizeof(TestInstance) <= sizeof(memory_pool_), |
| "The test memory pool is too small for this test. Either increase " |
| "kTestMemoryPoolSizeBytes 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 |