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