1 // Copyright 2020 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 namespace pw { 17 namespace unit_test { 18 19 // The result of a complete test run. 20 enum class TestResult { 21 kSuccess = 0, 22 kFailure = 1, 23 // Test skipped at runtime. This is neither a success nor a failure. 24 kSkipped = 2, 25 }; 26 27 struct TestCase { 28 // Name of the test suite to which this test case belongs. 29 const char* suite_name; 30 31 // Name of the test case. 32 const char* test_name; 33 34 // Path to the file in which the test case is defined. 35 const char* file_name; 36 }; 37 38 struct TestExpectation { 39 // The source code for the expression which was run. 40 const char* expression; 41 42 // The expression with arguments evaluated. 43 const char* evaluated_expression; 44 45 // Line number at which the expectation is located. 46 int line_number; 47 48 // Whether the expectation succeeded. 49 bool success; 50 }; 51 52 struct RunTestsSummary { 53 // The number of passed tests among the run tests. 54 int passed_tests; 55 56 // The number of passed tests among the run tests. 57 int failed_tests; 58 59 // The number of tests skipped or filtered out. 60 int skipped_tests; 61 62 // The number of disabled tests encountered. 63 int disabled_tests; 64 }; 65 66 struct ProgramSummary { 67 // The total number of tests to run in the program. 68 int tests_to_run; 69 70 // The number of test suites included in the program. 71 int test_suites; 72 73 // Test summary for the program once complete. 74 RunTestsSummary tests_summary; 75 }; 76 77 struct TestSuite { 78 // Name of the test suite. 79 const char* name; 80 81 // Total number of tests in suite to run. 82 int test_to_run_count; 83 }; 84 85 /// Collects and processes the results of a unit test run. Its interface is 86 /// called by the unit test framework as tests are executed and various test 87 /// events occur. 88 /// 89 /// A program wanting to process test events must define a class implementing 90 /// the ``pw::unit_test::EventHandler`` interface and register it with the 91 /// framework. When ``RUN_ALL_TESTS()`` is called, ``pw_unit_test`` notifies 92 /// the handler of various events which occur in the test process. 93 /// For example, consider a file containing the following test definitions: 94 /// 95 /// @code{.cpp} 96 /// TEST(MyTestSuite, MyFirstCase) { 97 /// EXPECT_TRUE(true); 98 /// } 99 /// 100 /// TEST(MyTestSuite, MySecondCase) { 101 /// EXPECT_TRUE(false); 102 /// } 103 /// @endcode 104 /// 105 /// There's one test suite consisting of two test cases. When ``pw_unit_test`` 106 /// starts running the first test case (``MyFirstCase``), it dispatches a 107 /// ``TestCaseStart`` event to the event handler. It then runs the body of the 108 /// test, sequentially checking each expectation within. After each expectation, 109 /// a 110 /// ``TestCaseExpect`` event is sent to the event handler with the expectation's 111 /// result. In this case, there's only one, which passes successfully. Finally, 112 /// after the test is finished, a ``TestCaseEnd`` event is dispatched with the 113 /// overall result of the test case. ``pw_unit_test`` then runs ``MySecondCase`` 114 /// in the same way. 115 class EventHandler { 116 public: 117 virtual ~EventHandler() = default; 118 119 /// Called before any test activity starts. 120 virtual void TestProgramStart(const ProgramSummary& program_summary) = 0; 121 122 /// Called after environment setup for each iteration of tests ends. 123 virtual void EnvironmentsSetUpEnd() = 0; 124 125 /// Called before the test suite starts. 126 virtual void TestSuiteStart(const TestSuite& test_suite) = 0; 127 128 /// Called after the test suite ends. 129 virtual void TestSuiteEnd(const TestSuite& test_suite) = 0; 130 131 /// Called after environment teardown for each iteration of tests ends. 132 virtual void EnvironmentsTearDownEnd() = 0; 133 134 /// Called after all test activities have ended. 135 virtual void TestProgramEnd(const ProgramSummary& program_summary) = 0; 136 137 /// Called before all tests are run. 138 virtual void RunAllTestsStart() = 0; 139 140 /// Called after all tests are run. 141 virtual void RunAllTestsEnd(const RunTestsSummary& run_tests_summary) = 0; 142 143 /// Called when a new test case is started. 144 virtual void TestCaseStart(const TestCase& test_case) = 0; 145 146 /// Called when a test case completes. The overall result of the test case is 147 /// provided. 148 virtual void TestCaseEnd(const TestCase& test_case, TestResult result) = 0; 149 150 /// Called when a disabled test case is encountered. TestCaseDisabled(const TestCase &)151 virtual void TestCaseDisabled(const TestCase&) {} 152 153 /// Called after each expect or assert statement within a test case with the 154 /// result. 155 virtual void TestCaseExpect(const TestCase& test_case, 156 const TestExpectation& expectation) = 0; 157 }; 158 159 /// Sets the event handler for a test run. Must be called before 160 /// `RUN_ALL_TESTS()` to receive test output. Set `event_handler` to null 161 /// to disable event handling. 162 /// 163 /// @warning This method is not thread-safe. 164 void RegisterEventHandler(EventHandler* event_handler); 165 166 } // namespace unit_test 167 } // namespace pw 168