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 }; 55 56 struct TestCase { 57 // Name of the test suite to which this test case belongs. 58 const char* suite_name; 59 60 // Name of the test case. 61 const char* test_name; 62 63 // Path to the file in which the test case is defined. 64 const char* file_name; 65 }; 66 67 struct TestExpectation { 68 // The source code for the expression which was run. 69 const char* expression; 70 71 // The expression with arguments evaluated. 72 const char* evaluated_expression; 73 74 // Line number at which the expectation is located. 75 int line_number; 76 77 // Whether the expectation succeeded. 78 bool success; 79 }; 80 81 struct RunTestsSummary { 82 // The number of passed tests among the run tests. 83 int passed_tests; 84 85 // The number of passed tests among the run tests. 86 int failed_tests; 87 88 // The number of tests skipped or filtered out. 89 int skipped_tests; 90 91 // The number of disabled tests encountered. 92 int disabled_tests; 93 }; 94 95 // An event handler is responsible for collecting and processing the results of 96 // a unit test run. Its interface is called by the unit test framework as tests 97 // are executed and various test events occur. 98 class EventHandler { 99 public: 100 virtual ~EventHandler() = default; 101 102 // Called before all tests are run. 103 virtual void RunAllTestsStart() = 0; 104 105 // Called after all tests are run. 106 virtual void RunAllTestsEnd(const RunTestsSummary& run_tests_summary) = 0; 107 108 // Called when a new test case is started. 109 virtual void TestCaseStart(const TestCase& test_case) = 0; 110 111 // Called when a test case completes. The overall result of the test case is 112 // provided. 113 virtual void TestCaseEnd(const TestCase& test_case, TestResult result) = 0; 114 115 // Called when a disabled test case is encountered. TestCaseDisabled(const TestCase &)116 virtual void TestCaseDisabled(const TestCase&) {} 117 118 // Called after each expect/assert statement within a test case with the 119 // result of the expectation. 120 virtual void TestCaseExpect(const TestCase& test_case, 121 const TestExpectation& expectation) = 0; 122 }; 123 124 // Sets the event handler for a test run. Must be called before RUN_ALL_TESTS() 125 // to receive test output. 126 void RegisterEventHandler(EventHandler* event_handler); 127 128 } // namespace unit_test 129 } // namespace pw 130