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 // This file defines the interface through which the pw_unit_test framework 20 // sends its test data as it runs unit tests. A program wanting to process test 21 // events must define a class implementing the EventHandler interface and 22 // register it with the framework. When RUN_ALL_TESTS() is called, pw_unit_test 23 // will notify the handler of various events which occur in the test process. 24 // 25 // For example, consider a file containing the following test definitions: 26 // 27 // TEST(MyTestSuite, MyFirstCase) { 28 // EXPECT_TRUE(true); 29 // } 30 // 31 // TEST(MyTestSuite, MySecondCase) { 32 // EXPECT_TRUE(false); 33 // } 34 // 35 // In this file, there is one test suite consisting of two test cases. 36 // 37 // When pw_unit_test starts running the first test case, it dispatches a 38 // TestCaseStart event to the event handler. It then runs the body of the test, 39 // sequentially checking each assertion within. After each assertion, a 40 // TestCaseExpect event is sent to the event handler with the assertion's 41 // result. In this case, there is only one, which passes successfully (as 42 // `true`, is in fact, true). Finally, after the test is finished, a TestCaseEnd 43 // event is dispatched with the overall result of the test case. 44 // 45 // pw_unit_test then runs MySecondCase, still within the same test suite. The 46 // sequence of events dispatched is the same, except that this TestCaseExpect 47 // event is marked as a failure. The result passed alongside the TestCaseEnd 48 // event also indicates that the test case did not complete successfully. 49 50 // The result of a complete test run. 51 enum class TestResult { 52 kSuccess = 0, 53 kFailure = 1, 54 // Test skipped at runtime. This is neither a success nor a failure. 55 kSkipped = 2, 56 }; 57 58 struct TestCase { 59 // Name of the test suite to which this test case belongs. 60 const char* suite_name; 61 62 // Name of the test case. 63 const char* test_name; 64 65 // Path to the file in which the test case is defined. 66 const char* file_name; 67 }; 68 69 struct TestExpectation { 70 // The source code for the expression which was run. 71 const char* expression; 72 73 // The expression with arguments evaluated. 74 const char* evaluated_expression; 75 76 // Line number at which the expectation is located. 77 int line_number; 78 79 // Whether the expectation succeeded. 80 bool success; 81 }; 82 83 struct RunTestsSummary { 84 // The number of passed tests among the run tests. 85 int passed_tests; 86 87 // The number of passed tests among the run tests. 88 int failed_tests; 89 90 // The number of tests skipped or filtered out. 91 int skipped_tests; 92 93 // The number of disabled tests encountered. 94 int disabled_tests; 95 }; 96 97 struct ProgramSummary { 98 // The total number of tests to run in the program. 99 int tests_to_run; 100 101 // The number of test suites included in the program. 102 int test_suites; 103 104 // Test summary for the program once complete. 105 RunTestsSummary tests_summary; 106 }; 107 108 struct TestSuite { 109 // Name of the test suite. 110 const char* name; 111 112 // Total number of tests in suite to run. 113 int test_to_run_count; 114 }; 115 116 // An event handler is responsible for collecting and processing the results of 117 // a unit test run. Its interface is called by the unit test framework as tests 118 // are executed and various test events occur. 119 class EventHandler { 120 public: 121 virtual ~EventHandler() = default; 122 123 // Called before any test activity starts. 124 virtual void TestProgramStart(const ProgramSummary& program_summary) = 0; 125 126 // Called after environment set-up for each iteration of tests ends. 127 virtual void EnvironmentsSetUpEnd() = 0; 128 129 // Called before the test suite starts. 130 virtual void TestSuiteStart(const TestSuite& test_suite) = 0; 131 132 // Called after the test suite ends. 133 virtual void TestSuiteEnd(const TestSuite& test_suite) = 0; 134 135 // Called after environment tear-down for each iteration of tests ends. 136 virtual void EnvironmentsTearDownEnd() = 0; 137 138 // Called after all test activities have ended. 139 virtual void TestProgramEnd(const ProgramSummary& program_summary) = 0; 140 141 // Called before all tests are run. 142 virtual void RunAllTestsStart() = 0; 143 144 // Called after all tests are run. 145 virtual void RunAllTestsEnd(const RunTestsSummary& run_tests_summary) = 0; 146 147 // Called when a new test case is started. 148 virtual void TestCaseStart(const TestCase& test_case) = 0; 149 150 // Called when a test case completes. The overall result of the test case is 151 // provided. 152 virtual void TestCaseEnd(const TestCase& test_case, TestResult result) = 0; 153 154 // Called when a disabled test case is encountered. TestCaseDisabled(const TestCase &)155 virtual void TestCaseDisabled(const TestCase&) {} 156 157 // Called after each expect/assert statement within a test case with the 158 // result of the expectation. 159 virtual void TestCaseExpect(const TestCase& test_case, 160 const TestExpectation& expectation) = 0; 161 }; 162 163 } // namespace unit_test 164 } // namespace pw 165