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 #define FAILURETYPE_EXPECTASSERT       (9)
  48
  49 ///
  50 /// Unit Test context structure tracked by the unit test framework.
  51 ///
  52 typedef struct {
  53   CHAR8                     *Description;
  54   CHAR8                     *Name; // can't have spaces and should be short
  55   CHAR8                     *Log;
  56   FAILURE_TYPE              FailureType;
  57   CHAR8                     FailureMessage[UNIT_TEST_TESTFAILUREMSG_LENGTH];
  58   UINT8                     Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];
  59   UNIT_TEST_STATUS          Result;
  60   UNIT_TEST_FUNCTION        RunTest;
  61   UNIT_TEST_PREREQUISITE    Prerequisite;
  62   UNIT_TEST_CLEANUP         CleanUp;
  63   UNIT_TEST_CONTEXT         Context;
  64   UNIT_TEST_SUITE_HANDLE    ParentSuite;
  65 } UNIT_TEST;
  66
  67 ///
  68 /// Structure used to store the set of unit tests in a unit test suite as a list.
  69 ///
  70 typedef struct {
  71   LIST_ENTRY    Entry;
  72   UNIT_TEST     UT;
  73 } UNIT_TEST_LIST_ENTRY;
  74
  75 ///
  76 /// Unit Test Suite context structure tracked by the unit test framework.
  77 ///
  78 typedef struct {
  79   UINTN                         NumTests;
  80   CHAR8                         *Title;
  81   CHAR8                         *Name;
  82   UINT8                         Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];
  83   UNIT_TEST_SUITE_SETUP         Setup;
  84   UNIT_TEST_SUITE_TEARDOWN      Teardown;
  85   LIST_ENTRY                    TestCaseList;   // UNIT_TEST_LIST_ENTRY
  86   UNIT_TEST_FRAMEWORK_HANDLE    ParentFramework;
  87 } UNIT_TEST_SUITE;
  88
  89 ///
  90 /// Structure used to store the set of unit test suites in a unit test framework
  91 /// as a list.
  92 ///
  93 typedef struct {
  94   LIST_ENTRY         Entry;
  95   UNIT_TEST_SUITE    UTS;
  96 } UNIT_TEST_SUITE_LIST_ENTRY;
  97
  98 ///
  99 /// Unit Test Framework context structure tracked by the unit test framework.
 100 ///
 101 typedef struct {
 102   CHAR8         *Title;
 103   CHAR8         *ShortTitle;    // This title should contain NO spaces or non-filename characters. Is used in reporting and serialization.
 104   CHAR8         *VersionString;
 105   CHAR8         *Log;
 106   UINT8         Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];
 107   LIST_ENTRY    TestSuiteList;  // UNIT_TEST_SUITE_LIST_ENTRY
 108   EFI_TIME      StartTime;
 109   EFI_TIME      EndTime;
 110   UNIT_TEST     *CurrentTest;
 111   VOID          *SavedState;    // This is an instance of UNIT_TEST_SAVE_HEADER*, if present.
 112 } UNIT_TEST_FRAMEWORK;
 113
 114 ///
 115 /// Serialized version of a unit test
 116 ///
 117 typedef struct {
 118   UINT32              Size;                                       // Size of the UNIT_TEST_SAVE_TEST including Log[]
 119   UINT8               Fingerprint[UNIT_TEST_FINGERPRINT_SIZE];    // Fingerprint of the test itself.
 120   CHAR8               FailureMessage[UNIT_TEST_TESTFAILUREMSG_LENGTH];
 121   FAILURE_TYPE        FailureType;
 122   UNIT_TEST_STATUS    Result;
 123   CHAR8               Log[];
 124 } UNIT_TEST_SAVE_TEST;
 125
 126 ///
 127 /// Serialized version of a unit test context
 128 ///
 129 typedef struct {
 130   UINT32    Size;                                    // Size of the UNIT_TEST_SAVE_CONTEXT including Data[]
 131   UINT8     Fingerprint[UNIT_TEST_FINGERPRINT_SIZE]; // Fingerprint of the corresponding test.
 132   UINT8     Data[];                                  // Actual data of the context.
 133 } UNIT_TEST_SAVE_CONTEXT;
 134
 135 ///
 136 /// Serialized version of unit test framework
 137 ///
 138 typedef struct {
 139   UINT8       Version;
 140   UINT32      SaveStateSize;                           // Size of the entire serialized buffer.
 141   UINT8       Fingerprint[UNIT_TEST_FINGERPRINT_SIZE]; // Fingerprint of the framework that has been saved.
 142   EFI_TIME    StartTime;
 143   UINT32      TestCount;
 144   BOOLEAN     HasSavedContext;
 145   // UNIT_TEST_SAVE_TEST    Tests[];         // Array of structures starts here.
 146   // UNIT_TEST_SAVE_CONTEXT SavedContext[];  // Saved context for the currently running test.
 147   // CHAR8                  Log[];           // NOTE: Not yet implemented!!
 148 } UNIT_TEST_SAVE_HEADER;
 149
 150 /**
 151   This function is responsible for initializing the log buffer for a single test. It can
 152   be used internally, but may also be consumed by the test framework to add pre-existing
 153   data to a log before it's used.
 154
 155   @param[in,out]  TestHandle    A handle to the test being initialized.
 156   @param[in]      Buffer        [Optional] A pointer to pre-existing log data that should
 157                                 be used to initialize the log. Should include a NULL terminator.
 158   @param[in]      BufferSize    [Optional] The size of the pre-existing log data.
 159
 160 **/
 161 VOID
 162 EFIAPI
 163 UnitTestLogInit (
 164   IN OUT UNIT_TEST  *Test,
 165   IN UINT8          *Buffer     OPTIONAL,
 166   IN UINTN          BufferSize  OPTIONAL
 167   );
 168
 169 /**
 170   Internal helper function to return a handle to the currently executing framework.
 171   This function is generally used for communication within the UnitTest framework, but is
 172   defined here so that it can be consumed by the Assertion and Logging macros.
 173
 174   There should be no need to consume as a test writer, but it's there if you need it.
 175
 176   @retval     Handle to the currently executing test framework.
 177
 178 **/
 179 UNIT_TEST_FRAMEWORK_HANDLE
 180 GetActiveFrameworkHandle (
 181   VOID
 182   );
 183
 184 #endif