2 Provides a unit test framework. This allows tests to focus on testing logic
3 and the framework to focus on runnings, reporting, statistics, etc.
5 Copyright (c) Microsoft Corporation.<BR>
6 Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
10 #ifndef __UNIT_TEST_LIB_H__
11 #define __UNIT_TEST_LIB_H__
16 typedef UINT32 UNIT_TEST_STATUS
;
17 #define UNIT_TEST_PASSED (0)
18 #define UNIT_TEST_ERROR_PREREQUISITE_NOT_MET (1)
19 #define UNIT_TEST_ERROR_TEST_FAILED (2)
20 #define UNIT_TEST_ERROR_CLEANUP_FAILED (3)
21 #define UNIT_TEST_SKIPPED (0xFFFFFFFD)
22 #define UNIT_TEST_RUNNING (0xFFFFFFFE)
23 #define UNIT_TEST_PENDING (0xFFFFFFFF)
26 /// Declare PcdUnitTestLogLevel bits and UnitTestLog() ErrorLevel parameter.
28 #define UNIT_TEST_LOG_LEVEL_ERROR BIT0
29 #define UNIT_TEST_LOG_LEVEL_WARN BIT1
30 #define UNIT_TEST_LOG_LEVEL_INFO BIT2
31 #define UNIT_TEST_LOG_LEVEL_VERBOSE BIT3
34 /// Unit Test Framework Handle
36 struct UNIT_TEST_FRAMEWORK_OBJECT
;
37 typedef struct UNIT_TEST_FRAMEWORK_OBJECT
*UNIT_TEST_FRAMEWORK_HANDLE
;
40 /// Unit Test Suite Handle
42 struct UNIT_TEST_SUITE_OBJECT
;
43 typedef struct UNIT_TEST_SUITE_OBJECT
*UNIT_TEST_SUITE_HANDLE
;
48 struct UNIT_TEST_OBJECT
;
49 typedef struct UNIT_TEST_OBJECT
*UNIT_TEST_HANDLE
;
54 typedef VOID
*UNIT_TEST_CONTEXT
;
57 The prototype for a single UnitTest case function.
59 Functions with this prototype are registered to be dispatched by the
60 UnitTest framework, and results are recorded as test Pass or Fail.
62 @param[in] Context [Optional] An optional parameter that enables:
63 1) test-case reuse with varied parameters and
64 2) test-case re-entry for Target tests that need a
65 reboot. This parameter is a VOID* and it is the
66 responsibility of the test author to ensure that the
67 contents are well understood by all test cases that may
70 @retval UNIT_TEST_PASSED The Unit test has completed and the test
72 @retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed.
77 (EFIAPI
*UNIT_TEST_FUNCTION
)(
78 IN UNIT_TEST_CONTEXT Context
82 Unit-Test Prerequisite Function pointer type.
84 Functions with this prototype are registered to be dispatched by the unit test
85 framework prior to a given test case. If this prereq function returns
86 UNIT_TEST_ERROR_PREREQUISITE_NOT_MET, the test case will be skipped.
88 @param[in] Context [Optional] An optional parameter that enables:
89 1) test-case reuse with varied parameters and
90 2) test-case re-entry for Target tests that need a
91 reboot. This parameter is a VOID* and it is the
92 responsibility of the test author to ensure that the
93 contents are well understood by all test cases that may
96 @retval UNIT_TEST_PASSED Unit test case prerequisites
98 @retval UNIT_TEST_ERROR_PREREQUISITE_NOT_MET Test case should be skipped.
103 (EFIAPI
*UNIT_TEST_PREREQUISITE
)(
104 IN UNIT_TEST_CONTEXT Context
108 Unit-Test Cleanup (after) function pointer type.
110 Functions with this prototype are registered to be dispatched by the
111 unit test framework after a given test case. This will be called even if the
112 test case returns an error, but not if the prerequisite fails and the test is
113 skipped. The purpose of this function is to clean up any global state or
116 @param[in] Context [Optional] An optional parameter that enables:
117 1) test-case reuse with varied parameters and
118 2) test-case re-entry for Target tests that need a
119 reboot. This parameter is a VOID* and it is the
120 responsibility of the test author to ensure that the
121 contents are well understood by all test cases that may
124 @retval UNIT_TEST_PASSED Test case cleanup succeeded.
125 @retval UNIT_TEST_ERROR_CLEANUP_FAILED Test case cleanup failed.
130 (EFIAPI
*UNIT_TEST_CLEANUP
)(
131 IN UNIT_TEST_CONTEXT Context
135 Unit-Test Test Suite Setup (before) function pointer type. Functions with this
136 prototype are registered to be dispatched by the UnitTest framework prior to
137 running any of the test cases in a test suite. It will only be run once at
138 the beginning of the suite (not prior to each case).
140 The purpose of this function is to set up any global state or test data.
144 (EFIAPI
*UNIT_TEST_SUITE_SETUP
)(
149 Unit-Test Test Suite Teardown (after) function pointer type. Functions with
150 this prototype are registered to be dispatched by the UnitTest framework after
151 running all of the test cases in a test suite. It will only be run once at
152 the end of the suite.
154 The purpose of this function is to clean up any global state or test data.
158 (EFIAPI
*UNIT_TEST_SUITE_TEARDOWN
)(
163 Method to Initialize the Unit Test framework. This function registers the
164 test name and also initializes the internal state of the test framework to
165 receive any new suites and tests.
167 @param[out] FrameworkHandle Unit test framework to be created.
168 @param[in] Title Null-terminated ASCII string that is the user
169 friendly name of the framework. String is
171 @param[in] ShortTitle Null-terminated ASCII short string that is the
172 short name of the framework with no spaces.
174 @param[in] VersionString Null-terminated ASCII version string for the
175 framework. String is copied.
177 @retval EFI_SUCCESS The unit test framework was initialized.
178 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
179 @retval EFI_INVALID_PARAMETER Title is NULL.
180 @retval EFI_INVALID_PARAMETER ShortTitle is NULL.
181 @retval EFI_INVALID_PARAMETER VersionString is NULL.
182 @retval EFI_INVALID_PARAMETER ShortTitle is invalid.
183 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
184 initialize the unit test framework.
188 InitUnitTestFramework (
189 OUT UNIT_TEST_FRAMEWORK_HANDLE
*FrameworkHandle
,
191 IN CHAR8
*ShortTitle
,
192 IN CHAR8
*VersionString
196 Registers a Unit Test Suite in the Unit Test Framework.
197 At least one test suite must be registered, because all test cases must be
198 within a unit test suite.
200 @param[out] SuiteHandle Unit test suite to create
201 @param[in] FrameworkHandle Unit test framework to add unit test suite to
202 @param[in] Title Null-terminated ASCII string that is the user
203 friendly name of the test suite. String is
205 @param[in] Name Null-terminated ASCII string that is the short
206 name of the test suite with no spaces. String
208 @param[in] Setup Setup function, runs before suite. This is an
209 optional parameter that may be NULL.
210 @param[in] Teardown Teardown function, runs after suite. This is an
211 optional parameter that may be NULL.
213 @retval EFI_SUCCESS The unit test suite was created.
214 @retval EFI_INVALID_PARAMETER SuiteHandle is NULL.
215 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
216 @retval EFI_INVALID_PARAMETER Title is NULL.
217 @retval EFI_INVALID_PARAMETER Name is NULL.
218 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
219 initialize the unit test suite.
223 CreateUnitTestSuite (
224 OUT UNIT_TEST_SUITE_HANDLE
*SuiteHandle
,
225 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
,
228 IN UNIT_TEST_SUITE_SETUP Setup OPTIONAL
,
229 IN UNIT_TEST_SUITE_TEARDOWN Teardown OPTIONAL
233 Adds test case to Suite
235 @param[in] SuiteHandle Unit test suite to add test to.
236 @param[in] Description Null-terminated ASCII string that is the user
237 friendly description of a test. String is copied.
238 @param[in] Name Null-terminated ASCII string that is the short name
239 of the test with no spaces. String is copied.
240 @param[in] Function Unit test function.
241 @param[in] Prerequisite Prerequisite function, runs before test. This is
242 an optional parameter that may be NULL.
243 @param[in] CleanUp Clean up function, runs after test. This is an
244 optional parameter that may be NULL.
245 @param[in] Context Pointer to context. This is an optional parameter
248 @retval EFI_SUCCESS The unit test case was added to Suite.
249 @retval EFI_INVALID_PARAMETER SuiteHandle is NULL.
250 @retval EFI_INVALID_PARAMETER Description is NULL.
251 @retval EFI_INVALID_PARAMETER Name is NULL.
252 @retval EFI_INVALID_PARAMETER Function is NULL.
253 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
254 add the unit test case to Suite.
259 IN UNIT_TEST_SUITE_HANDLE SuiteHandle
,
260 IN CHAR8
*Description
,
262 IN UNIT_TEST_FUNCTION Function
,
263 IN UNIT_TEST_PREREQUISITE Prerequisite OPTIONAL
,
264 IN UNIT_TEST_CLEANUP CleanUp OPTIONAL
,
265 IN UNIT_TEST_CONTEXT Context OPTIONAL
269 Execute all unit test cases in all unit test suites added to a Framework.
271 Once a unit test framework is initialized and all unit test suites and unit
272 test cases are registered, this function will cause the unit test framework to
273 dispatch all unit test cases in sequence and record the results for reporting.
275 @param[in] FrameworkHandle A handle to the current running framework that
276 dispatched the test. Necessary for recording
277 certain test events with the framework.
279 @retval EFI_SUCCESS All test cases were dispatched.
280 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
285 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
289 Cleanup a test framework.
291 After tests are run, this will teardown the entire framework and free all
292 allocated data within.
294 @param[in] FrameworkHandle A handle to the current running framework that
295 dispatched the test. Necessary for recording
296 certain test events with the framework.
298 @retval EFI_SUCCESS All resources associated with framework were
300 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
304 FreeUnitTestFramework (
305 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
309 Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're
310 a framework author) to save the state of the executing framework along with
311 any allocated data so that the test may be resumed upon reentry. A test case
312 should pass any needed context (which, to prevent an infinite loop, should be
313 at least the current execution count) which will be saved by the framework and
314 passed to the test case upon resume.
316 This should be called while the current test framework is valid and active. It is
317 generally called from within a test case prior to quitting or rebooting.
319 @param[in] ContextToSave A buffer of test case-specific data to be saved
320 along with framework state. Will be passed as
321 "Context" to the test case upon resume. This
322 is an optional parameter that may be NULL.
323 @param[in] ContextToSaveSize Size of the ContextToSave buffer.
325 @retval EFI_SUCCESS The framework state and context were saved.
326 @retval EFI_NOT_FOUND An active framework handle was not found.
327 @retval EFI_INVALID_PARAMETER ContextToSave is not NULL and
328 ContextToSaveSize is 0.
329 @retval EFI_INVALID_PARAMETER ContextToSave is >= 4GB.
330 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
331 save the framework and context state.
332 @retval EFI_DEVICE_ERROR The framework and context state could not be
333 saved to a persistent storage device due to a
339 IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL
,
340 IN UINTN ContextToSaveSize
344 This macro uses the framework assertion logic to check an expression for
345 "TRUE". If the expression evaluates to TRUE, execution continues.
346 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
348 @param[in] Expression Expression to be evaluated for TRUE.
350 #define UT_ASSERT_TRUE(Expression) \
351 if(!UnitTestAssertTrue ((Expression), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \
352 return UNIT_TEST_ERROR_TEST_FAILED; \
356 This macro uses the framework assertion logic to check an expression for
357 "FALSE". If the expression evaluates to FALSE, execution continues.
358 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
360 @param[in] Expression Expression to be evaluated for FALSE.
362 #define UT_ASSERT_FALSE(Expression) \
363 if(!UnitTestAssertFalse ((Expression), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \
364 return UNIT_TEST_ERROR_TEST_FAILED; \
368 This macro uses the framework assertion logic to check whether two simple
369 values are equal. If the values are equal, execution continues.
370 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
372 @param[in] ValueA Value to be compared for equality (64-bit comparison).
373 @param[in] ValueB Value to be compared for equality (64-bit comparison).
375 #define UT_ASSERT_EQUAL(ValueA, ValueB) \
376 if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \
377 return UNIT_TEST_ERROR_TEST_FAILED; \
381 This macro uses the framework assertion logic to check whether two memory
382 buffers are equal. If the buffers are equal, execution continues.
383 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
385 @param[in] BufferA Pointer to a buffer for comparison.
386 @param[in] BufferB Pointer to a buffer for comparison.
387 @param[in] Length Number of bytes to compare in BufferA and BufferB.
389 #define UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length) \
390 if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #BufferA, #BufferB)) { \
391 return UNIT_TEST_ERROR_TEST_FAILED; \
395 This macro uses the framework assertion logic to check whether two simple
396 values are non-equal. If the values are non-equal, execution continues.
397 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
399 @param[in] ValueA Value to be compared for inequality (64-bit comparison).
400 @param[in] ValueB Value to be compared for inequality (64-bit comparison).
402 #define UT_ASSERT_NOT_EQUAL(ValueA, ValueB) \
403 if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \
404 return UNIT_TEST_ERROR_TEST_FAILED; \
408 This macro uses the framework assertion logic to check whether an EFI_STATUS
409 value is !EFI_ERROR(). If the status is !EFI_ERROR(), execution continues.
410 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
412 @param[in] Status EFI_STATUS value to check.
414 #define UT_ASSERT_NOT_EFI_ERROR(Status) \
415 if(!UnitTestAssertNotEfiError ((Status), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \
416 return UNIT_TEST_ERROR_TEST_FAILED; \
420 This macro uses the framework assertion logic to check whether two EFI_STATUS
421 values are equal. If the values are equal, execution continues.
422 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
424 @param[in] Status EFI_STATUS values to compare for equality.
425 @param[in] Expected EFI_STATUS values to compare for equality.
427 #define UT_ASSERT_STATUS_EQUAL(Status, Expected) \
428 if(!UnitTestAssertStatusEqual ((Status), (Expected), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \
429 return UNIT_TEST_ERROR_TEST_FAILED; \
433 This macro uses the framework assertion logic to check whether a pointer is
434 not NULL. If the pointer is not NULL, execution continues. Otherwise, the
435 test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
437 @param[in] Pointer Pointer to be checked against NULL.
439 #define UT_ASSERT_NOT_NULL(Pointer) \
440 if(!UnitTestAssertNotNull ((Pointer), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #Pointer)) { \
441 return UNIT_TEST_ERROR_TEST_FAILED; \
445 This macro uses the framework assertion logic to check whether a function call
446 triggers an ASSERT() condition. The BaseLib SetJump()/LongJump() services
447 are used to establish a safe return point when an ASSERT() is triggered.
448 If an ASSERT() is triggered, unit test execution continues and Status is set
449 to UNIT_TEST_PASSED. Otherwise, a unit test case failure is raised and
450 Status is set to UNIT_TEST_ERROR_TEST_FAILED.
452 If ASSERT() macros are disabled, then the test case is skipped and a warning
453 message is added to the unit test log. Status is set to UNIT_TEST_SKIPPED.
455 @param[in] FunctionCall Function call that is expected to trigger ASSERT().
456 @param[out] Status Pointer to a UNIT_TEST_STATUS return value. This
457 is an optional parameter that may be NULL.
459 #if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED)
460 #include <Library/BaseLib.h>
463 /// Pointer to jump buffer used with SetJump()/LongJump() to test if a
464 /// function under test generates an expected ASSERT() condition.
466 extern BASE_LIBRARY_JUMP_BUFFER
*gUnitTestExpectAssertFailureJumpBuffer
;
468 #define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) \
470 UNIT_TEST_STATUS UnitTestJumpStatus; \
471 BASE_LIBRARY_JUMP_BUFFER UnitTestJumpBuffer; \
472 UnitTestJumpStatus = UNIT_TEST_SKIPPED; \
473 if (DebugAssertEnabled ()) { \
474 gUnitTestExpectAssertFailureJumpBuffer = &UnitTestJumpBuffer; \
475 if (SetJump (gUnitTestExpectAssertFailureJumpBuffer) == 0) { \
477 UnitTestJumpStatus = UNIT_TEST_ERROR_TEST_FAILED; \
479 UnitTestJumpStatus = UNIT_TEST_PASSED; \
481 gUnitTestExpectAssertFailureJumpBuffer = NULL; \
483 if (!UnitTestExpectAssertFailure ( \
484 UnitTestJumpStatus, \
485 __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, \
486 #FunctionCall, Status)) { \
487 return UNIT_TEST_ERROR_TEST_FAILED; \
491 #define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) FunctionCall;
495 If Expression is TRUE, then TRUE is returned.
496 If Expression is FALSE, then an assert is triggered and the location of the
497 assert provided by FunctionName, LineNumber, FileName, and Description are
498 recorded and FALSE is returned.
500 @param[in] Expression The BOOLEAN result of the expression evaluation.
501 @param[in] FunctionName Null-terminated ASCII string of the function
502 executing the assert macro.
503 @param[in] LineNumber The source file line number of the assert macro.
504 @param[in] FileName Null-terminated ASCII string of the filename
505 executing the assert macro.
506 @param[in] Description Null-terminated ASCII string of the expression being
509 @retval TRUE Expression is TRUE.
510 @retval FALSE Expression is FALSE.
515 IN BOOLEAN Expression
,
516 IN CONST CHAR8
*FunctionName
,
518 IN CONST CHAR8
*FileName
,
519 IN CONST CHAR8
*Description
523 If Expression is FALSE, then TRUE is returned.
524 If Expression is TRUE, then an assert is triggered and the location of the
525 assert provided by FunctionName, LineNumber, FileName, and Description are
526 recorded and FALSE is returned.
528 @param[in] Expression The BOOLEAN result of the expression evaluation.
529 @param[in] FunctionName Null-terminated ASCII string of the function
530 executing the assert macro.
531 @param[in] LineNumber The source file line number of the assert macro.
532 @param[in] FileName Null-terminated ASCII string of the filename
533 executing the assert macro.
534 @param[in] Description Null-terminated ASCII string of the expression being
537 @retval TRUE Expression is FALSE.
538 @retval FALSE Expression is TRUE.
542 UnitTestAssertFalse (
543 IN BOOLEAN Expression
,
544 IN CONST CHAR8
*FunctionName
,
546 IN CONST CHAR8
*FileName
,
547 IN CONST CHAR8
*Description
551 If Status is not an EFI_ERROR(), then TRUE is returned.
552 If Status is an EFI_ERROR(), then an assert is triggered and the location of
553 the assert provided by FunctionName, LineNumber, FileName, and Description are
554 recorded and FALSE is returned.
556 @param[in] Status The EFI_STATUS value to evaluate.
557 @param[in] FunctionName Null-terminated ASCII string of the function
558 executing the assert macro.
559 @param[in] LineNumber The source file line number of the assert macro.
560 @param[in] FileName Null-terminated ASCII string of the filename
561 executing the assert macro.
562 @param[in] Description Null-terminated ASCII string of the status
563 expression being evaluated.
565 @retval TRUE Status is not an EFI_ERROR().
566 @retval FALSE Status is an EFI_ERROR().
570 UnitTestAssertNotEfiError (
571 IN EFI_STATUS Status
,
572 IN CONST CHAR8
*FunctionName
,
574 IN CONST CHAR8
*FileName
,
575 IN CONST CHAR8
*Description
579 If ValueA is equal ValueB, then TRUE is returned.
580 If ValueA is not equal to ValueB, then an assert is triggered and the location
581 of the assert provided by FunctionName, LineNumber, FileName, DescriptionA,
582 and DescriptionB are recorded and FALSE is returned.
584 @param[in] ValueA 64-bit value.
585 @param[in] ValueB 64-bit value.
586 @param[in] FunctionName Null-terminated ASCII string of the function
587 executing the assert macro.
588 @param[in] LineNumber The source file line number of the assert macro.
589 @param[in] FileName Null-terminated ASCII string of the filename
590 executing the assert macro.
591 @param[in] DescriptionA Null-terminated ASCII string that is a description
593 @param[in] DescriptionB Null-terminated ASCII string that is a description
596 @retval TRUE ValueA is equal to ValueB.
597 @retval FALSE ValueA is not equal to ValueB.
601 UnitTestAssertEqual (
604 IN CONST CHAR8
*FunctionName
,
606 IN CONST CHAR8
*FileName
,
607 IN CONST CHAR8
*DescriptionA
,
608 IN CONST CHAR8
*DescriptionB
612 If the contents of BufferA are identical to the contents of BufferB, then TRUE
613 is returned. If the contents of BufferA are not identical to the contents of
614 BufferB, then an assert is triggered and the location of the assert provided
615 by FunctionName, LineNumber, FileName, DescriptionA, and DescriptionB are
616 recorded and FALSE is returned.
618 @param[in] BufferA Pointer to a buffer for comparison.
619 @param[in] BufferB Pointer to a buffer for comparison.
620 @param[in] Length Number of bytes to compare in BufferA and BufferB.
621 @param[in] FunctionName Null-terminated ASCII string of the function
622 executing the assert macro.
623 @param[in] LineNumber The source file line number of the assert macro.
624 @param[in] FileName Null-terminated ASCII string of the filename
625 executing the assert macro.
626 @param[in] DescriptionA Null-terminated ASCII string that is a description
628 @param[in] DescriptionB Null-terminated ASCII string that is a description
631 @retval TRUE The contents of BufferA are identical to the contents of
633 @retval FALSE The contents of BufferA are not identical to the contents of
638 UnitTestAssertMemEqual (
642 IN CONST CHAR8
*FunctionName
,
644 IN CONST CHAR8
*FileName
,
645 IN CONST CHAR8
*DescriptionA
,
646 IN CONST CHAR8
*DescriptionB
650 If ValueA is not equal ValueB, then TRUE is returned.
651 If ValueA is equal to ValueB, then an assert is triggered and the location
652 of the assert provided by FunctionName, LineNumber, FileName, DescriptionA
653 and DescriptionB are recorded and FALSE is returned.
655 @param[in] ValueA 64-bit value.
656 @param[in] ValueB 64-bit value.
657 @param[in] FunctionName Null-terminated ASCII string of the function
658 executing the assert macro.
659 @param[in] LineNumber The source file line number of the assert macro.
660 @param[in] FileName Null-terminated ASCII string of the filename
661 executing the assert macro.
662 @param[in] DescriptionA Null-terminated ASCII string that is a description
664 @param[in] DescriptionB Null-terminated ASCII string that is a description
667 @retval TRUE ValueA is not equal to ValueB.
668 @retval FALSE ValueA is equal to ValueB.
672 UnitTestAssertNotEqual (
675 IN CONST CHAR8
*FunctionName
,
677 IN CONST CHAR8
*FileName
,
678 IN CONST CHAR8
*DescriptionA
,
679 IN CONST CHAR8
*DescriptionB
683 If Status is equal to Expected, then TRUE is returned.
684 If Status is not equal to Expected, then an assert is triggered and the
685 location of the assert provided by FunctionName, LineNumber, FileName, and
686 Description are recorded and FALSE is returned.
688 @param[in] Status EFI_STATUS value returned from an API under test.
689 @param[in] Expected The expected EFI_STATUS return value from an API
691 @param[in] FunctionName Null-terminated ASCII string of the function
692 executing the assert macro.
693 @param[in] LineNumber The source file line number of the assert macro.
694 @param[in] FileName Null-terminated ASCII string of the filename
695 executing the assert macro.
696 @param[in] Description Null-terminated ASCII string that is a description
699 @retval TRUE Status is equal to Expected.
700 @retval FALSE Status is not equal to Expected.
704 UnitTestAssertStatusEqual (
705 IN EFI_STATUS Status
,
706 IN EFI_STATUS Expected
,
707 IN CONST CHAR8
*FunctionName
,
709 IN CONST CHAR8
*FileName
,
710 IN CONST CHAR8
*Description
714 If Pointer is not equal to NULL, then TRUE is returned.
715 If Pointer is equal to NULL, then an assert is triggered and the location of
716 the assert provided by FunctionName, LineNumber, FileName, and PointerName
717 are recorded and FALSE is returned.
719 @param[in] Pointer Pointer value to be checked against NULL.
720 @param[in] Expected The expected EFI_STATUS return value from a function
722 @param[in] FunctionName Null-terminated ASCII string of the function
723 executing the assert macro.
724 @param[in] LineNumber The source file line number of the assert macro.
725 @param[in] FileName Null-terminated ASCII string of the filename
726 executing the assert macro.
727 @param[in] PointerName Null-terminated ASCII string that is a description
730 @retval TRUE Pointer is not equal to NULL.
731 @retval FALSE Pointer is equal to NULL.
735 UnitTestAssertNotNull (
737 IN CONST CHAR8
*FunctionName
,
739 IN CONST CHAR8
*FileName
,
740 IN CONST CHAR8
*PointerName
744 If UnitTestStatus is UNIT_TEST_PASSED, then log an info message and return
745 TRUE because an ASSERT() was expected when FunctionCall was executed and an
746 ASSERT() was triggered. If UnitTestStatus is UNIT_TEST_SKIPPED, then log a
747 warning message and return TRUE because ASSERT() macros are disabled. If
748 UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED, then log an error message and
749 return FALSE because an ASSERT() was expected when FunctionCall was executed,
750 but no ASSERT() conditions were triggered. The log messages contain
751 FunctionName, LineNumber, and FileName strings to provide the location of the
752 UT_EXPECT_ASSERT_FAILURE() macro.
754 @param[in] UnitTestStatus The status from UT_EXPECT_ASSERT_FAILURE() that
755 is either pass, skipped, or failed.
756 @param[in] FunctionName Null-terminated ASCII string of the function
757 executing the UT_EXPECT_ASSERT_FAILURE() macro.
758 @param[in] LineNumber The source file line number of the the function
759 executing the UT_EXPECT_ASSERT_FAILURE() macro.
760 @param[in] FileName Null-terminated ASCII string of the filename
761 executing the UT_EXPECT_ASSERT_FAILURE() macro.
762 @param[in] FunctionCall Null-terminated ASCII string of the function call
763 executed by the UT_EXPECT_ASSERT_FAILURE() macro.
764 @param[out] ResultStatus Used to return the UnitTestStatus value to the
765 caller of UT_EXPECT_ASSERT_FAILURE(). This is
766 optional parameter that may be NULL.
768 @retval TRUE UnitTestStatus is UNIT_TEST_PASSED.
769 @retval TRUE UnitTestStatus is UNIT_TEST_SKIPPED.
770 @retval FALSE UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED.
774 UnitTestExpectAssertFailure (
775 IN UNIT_TEST_STATUS UnitTestStatus
,
776 IN CONST CHAR8
*FunctionName
,
778 IN CONST CHAR8
*FileName
,
779 IN CONST CHAR8
*FunctionCall
,
780 OUT UNIT_TEST_STATUS
*ResultStatus OPTIONAL
784 Test logging macro that records an ERROR message in the test framework log.
785 Record is associated with the currently executing test case.
787 @param[in] Format Formatting string following the format defined in
788 MdePkg/Include/Library/PrintLib.h.
789 @param[in] ... Print args.
791 #define UT_LOG_ERROR(Format, ...) \
792 UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__)
795 Test logging macro that records a WARNING message in the test framework log.
796 Record is associated with the currently executing test case.
798 @param[in] Format Formatting string following the format defined in
799 MdePkg/Include/Library/PrintLib.h.
800 @param[in] ... Print args.
802 #define UT_LOG_WARNING(Format, ...) \
803 UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, Format, ##__VA_ARGS__)
806 Test logging macro that records an INFO message in the test framework log.
807 Record is associated with the currently executing test case.
809 @param[in] Format Formatting string following the format defined in
810 MdePkg/Include/Library/PrintLib.h.
811 @param[in] ... Print args.
813 #define UT_LOG_INFO(Format, ...) \
814 UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, Format, ##__VA_ARGS__)
817 Test logging macro that records a VERBOSE message in the test framework log.
818 Record is associated with the currently executing test case.
820 @param[in] Format Formatting string following the format defined in
821 MdePkg/Include/Library/PrintLib.h.
822 @param[in] ... Print args.
824 #define UT_LOG_VERBOSE(Format, ...) \
825 UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, Format, ##__VA_ARGS__)
828 Test logging function that records a messages in the test framework log.
829 Record is associated with the currently executing test case.
831 @param[in] ErrorLevel The error level of the unit test log message.
832 @param[in] Format Formatting string following the format defined in the
833 MdePkg/Include/Library/PrintLib.h.
834 @param[in] ... Print args.
840 IN CONST CHAR8
*Format
,