UnitTestFrameworkPkg/PrivateInclude/UnitTestFrameworkTypes.h

   1 /** @file
   2   Provides the basic types and common elements of the unit test framework
   3
   4   Copyright (c) Microsoft Corporation.<BR>
   5   Copyright (c) 2019 - 2020, Intel Corporation. All rights reserved.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __UNIT_TEST_TYPES_H__
  11 #define __UNIT_TEST_TYPES_H__
  12
  13 #include <Library/UnitTestLib.h>
  14
  15 ///
  16 /// The maximum length of a string stored in the unit test framework
  17 ///
  18 #define UNIT_TEST_MAX_STRING_LENGTH      (120)
  19
  20 ///
  21 /// The size of a firngerprint used to save/resume execution of a unit test
  22 /// framework.  This is the size of a CRC32 value which is 32-bit value.
  23 ///
  24 ///
  25 #define UNIT_TEST_FINGERPRINT_SIZE       (sizeof (UINT32))
  26
  27 ///
  28 /// The maximum length of a test failure message stored in the unit test
  29 /// framework
  30 ///
  31 #define UNIT_TEST_TESTFAILUREMSG_LENGTH  (120)
  32
  33 ///
  34 /// FAILURE_TYPE used to record the type of assert that was triggered by a unit
  35 /// test.
  36 ///
  37 typedef UINT32 FAILURE_TYPE;
  38 #define FAILURETYPE_NOFAILURE            (0)
  39 #define FAILURETYPE_OTHER                (1)
  40 #define FAILURETYPE_ASSERTTRUE           (2)
  41 #define FAILURETYPE_ASSERTFALSE          (3)
  42 #define FAILURETYPE_ASSERTEQUAL          (4)
  43 #define FAILURETYPE_ASSERTNOTEQUAL       (5)
  44 #define FAILURETYPE_ASSERTNOTEFIERROR    (6)
  45 #define FAILURETYPE_ASSERTSTATUSEQUAL    (7)
  46 #define FAILURETYPE_ASSERTNOTNULL        (8)
  47
  48 ///
  49 /// Unit Test context structure tracked by the unit test framework.
  50 ///
  51 typedef struct {
  52   CHAR8                   *Description;
  53   CHAR8                   *Name;  //can't have spaces and should be short
  54   CHAR8                   *Log;
  55   FAILURE_TYPE            FailureType;
  56   CHAR8                   FailureMessage[UNIT_TEST_TESTFAILUREMSG_LENGTH];
  57   UINT8                   Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];
  58   UNIT_TEST_STATUS        Result;
  59   UNIT_TEST_FUNCTION      RunTest;
  60   UNIT_TEST_PREREQUISITE  Prerequisite;
  61   UNIT_TEST_CLEANUP       CleanUp;
  62   UNIT_TEST_CONTEXT       Context;
  63   UNIT_TEST_SUITE_HANDLE  ParentSuite;
  64 } UNIT_TEST;
  65
  66 ///
  67 /// Structure used to store the set of unit tests in a unit test suite as a list.
  68 ///
  69 typedef struct {
  70   LIST_ENTRY  Entry;
  71   UNIT_TEST   UT;
  72 } UNIT_TEST_LIST_ENTRY;
  73
  74 ///
  75 /// Unit Test Suite context structure tracked by the unit test framework.
  76 ///
  77 typedef struct {
  78   UINTN                       NumTests;
  79   CHAR8                       *Title;
  80   CHAR8                       *Name;
  81   UINT8                       Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];
  82   UNIT_TEST_SUITE_SETUP       Setup;
  83   UNIT_TEST_SUITE_TEARDOWN    Teardown;
  84   LIST_ENTRY                  TestCaseList;     // UNIT_TEST_LIST_ENTRY
  85   UNIT_TEST_FRAMEWORK_HANDLE  ParentFramework;
  86 } UNIT_TEST_SUITE;
  87
  88 ///
  89 /// Structure used to store the set of unit test suites in a unit test framework
  90 /// as a list.
  91 ///
  92 typedef struct {
  93   LIST_ENTRY       Entry;
  94   UNIT_TEST_SUITE  UTS;
  95 } UNIT_TEST_SUITE_LIST_ENTRY;
  96
  97 ///
  98 /// Unit Test Framework context structure tracked by the unit test framework.
  99 ///
 100 typedef struct {
 101   CHAR8       *Title;
 102   CHAR8       *ShortTitle;      // This title should contain NO spaces or non-filename characters. Is used in reporting and serialization.
 103   CHAR8       *VersionString;
 104   CHAR8       *Log;
 105   UINT8       Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];
 106   LIST_ENTRY  TestSuiteList;    // UNIT_TEST_SUITE_LIST_ENTRY
 107   EFI_TIME    StartTime;
 108   EFI_TIME    EndTime;
 109   UNIT_TEST   *CurrentTest;
 110   VOID        *SavedState;      // This is an instance of UNIT_TEST_SAVE_HEADER*, if present.
 111 } UNIT_TEST_FRAMEWORK;
 112
 113 ///
 114 /// Serialized version of a unit test
 115 ///
 116 typedef struct {
 117   UINT32            Size;                                         // Size of the UNIT_TEST_SAVE_TEST including Log[]
 118   UINT8             Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];      // Fingerprint of the test itself.
 119   CHAR8             FailureMessage[UNIT_TEST_TESTFAILUREMSG_LENGTH];
 120   FAILURE_TYPE      FailureType;
 121   UNIT_TEST_STATUS  Result;
 122   CHAR8             Log[];
 123 } UNIT_TEST_SAVE_TEST;
 124
 125 ///
 126 /// Serialized version of a unit test context
 127 ///
 128 typedef struct {
 129   UINT32  Size;                                     // Size of the UNIT_TEST_SAVE_CONTEXT including Data[]
 130   UINT8   Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];  // Fingerprint of the corresponding test.
 131   UINT8   Data[];                                   // Actual data of the context.
 132 } UNIT_TEST_SAVE_CONTEXT;
 133
 134 ///
 135 /// Serialized version of unit test framework
 136 ///
 137 typedef struct {
 138   UINT8     Version;
 139   UINT32    SaveStateSize;                            // Size of the entire serialized buffer.
 140   UINT8     Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];  // Fingerprint of the framework that has been saved.
 141   EFI_TIME  StartTime;
 142   UINT32    TestCount;
 143   BOOLEAN   HasSavedContext;
 144   // UNIT_TEST_SAVE_TEST    Tests[];         // Array of structures starts here.
 145   // UNIT_TEST_SAVE_CONTEXT SavedContext[];  // Saved context for the currently running test.
 146   // CHAR8                  Log[];           // NOTE: Not yet implemented!!
 147 } UNIT_TEST_SAVE_HEADER;
 148
 149 /**
 150   This function is responsible for initializing the log buffer for a single test. It can
 151   be used internally, but may also be consumed by the test framework to add pre-existing
 152   data to a log before it's used.
 153
 154   @param[in,out]  TestHandle    A handle to the test being initialized.
 155   @param[in]      Buffer        [Optional] A pointer to pre-existing log data that should
 156                                 be used to initialize the log. Should include a NULL terminator.
 157   @param[in]      BufferSize    [Optional] The size of the pre-existing log data.
 158
 159 **/
 160 VOID
 161 EFIAPI
 162 UnitTestLogInit (
 163   IN OUT UNIT_TEST  *Test,
 164   IN UINT8          *Buffer     OPTIONAL,
 165   IN UINTN          BufferSize  OPTIONAL
 166   );
 167
 168 /**
 169   Internal helper function to return a handle to the currently executing framework.
 170   This function is generally used for communication within the UnitTest framework, but is
 171   defined here so that it can be consumed by the Assertion and Logging macros.
 172
 173   There should be no need to consume as a test writer, but it's there if you need it.
 174
 175   @retval     Handle to the currently executing test framework.
 176
 177 **/
 178 UNIT_TEST_FRAMEWORK_HANDLE
 179 GetActiveFrameworkHandle (
 180   VOID
 181   );
 182
 183 #endif