third_party/pigweed/repo/pw_unit_test/public/pw_unit_test/event_handler.h

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