[mirror_edk2.git] / UnitTestFrameworkPkg / PrivateInclude / UnitTestFrameworkTypes.h

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