UnitTestFrameworkTypes.h 6.3 KB

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