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 // An event handler is responsible for collecting and processing the results of 98 // a unit test run. Its interface is called by the unit test framework as tests 99 // are executed and various test events occur. 100 class EventHandler { 101 public: 102 virtual ~EventHandler() = default; 103 104 // Called before all tests are run. 105 virtual void RunAllTestsStart() = 0; 106 107 // Called after all tests are run. 108 virtual void RunAllTestsEnd(const RunTestsSummary& run_tests_summary) = 0; 109 110 // Called when a new test case is started. 111 virtual void TestCaseStart(const TestCase& test_case) = 0; 112 113 // Called when a test case completes. The overall result of the test case is 114 // provided. 115 virtual void TestCaseEnd(const TestCase& test_case, TestResult result) = 0; 116 117 // Called when a disabled test case is encountered. TestCaseDisabled(const TestCase &)118 virtual void TestCaseDisabled(const TestCase&) {} 119 120 // Called after each expect/assert statement within a test case with the 121 // result of the expectation. 122 virtual void TestCaseExpect(const TestCase& test_case, 123 const TestExpectation& expectation) = 0; 124 }; 125 126 // Sets the event handler for a test run. Must be called before RUN_ALL_TESTS() 127 // to receive test output. 128 void RegisterEventHandler(EventHandler* event_handler); 129 130 } // namespace unit_test 131 } // namespace pw 132