| /** @file | |
| Provides a unit test framework. This allows tests to focus on testing logic | |
| and the framework to focus on runnings, reporting, statistics, etc. | |
| Copyright (c) Microsoft Corporation.<BR> | |
| Copyright (c) 2020, Intel Corporation. All rights reserved.<BR> | |
| SPDX-License-Identifier: BSD-2-Clause-Patent | |
| **/ | |
| #ifndef __UNIT_TEST_LIB_H__ | |
| #define __UNIT_TEST_LIB_H__ | |
| /// | |
| /// Unit Test Status | |
| /// | |
| typedef UINT32 UNIT_TEST_STATUS; | |
| #define UNIT_TEST_PASSED (0) | |
| #define UNIT_TEST_ERROR_PREREQUISITE_NOT_MET (1) | |
| #define UNIT_TEST_ERROR_TEST_FAILED (2) | |
| #define UNIT_TEST_ERROR_CLEANUP_FAILED (3) | |
| #define UNIT_TEST_SKIPPED (0xFFFFFFFD) | |
| #define UNIT_TEST_RUNNING (0xFFFFFFFE) | |
| #define UNIT_TEST_PENDING (0xFFFFFFFF) | |
| /// | |
| /// Declare PcdUnitTestLogLevel bits and UnitTestLog() ErrorLevel parameter. | |
| /// | |
| #define UNIT_TEST_LOG_LEVEL_ERROR BIT0 | |
| #define UNIT_TEST_LOG_LEVEL_WARN BIT1 | |
| #define UNIT_TEST_LOG_LEVEL_INFO BIT2 | |
| #define UNIT_TEST_LOG_LEVEL_VERBOSE BIT3 | |
| /// | |
| /// Unit Test Framework Handle | |
| /// | |
| struct UNIT_TEST_FRAMEWORK_OBJECT; | |
| typedef struct UNIT_TEST_FRAMEWORK_OBJECT *UNIT_TEST_FRAMEWORK_HANDLE; | |
| /// | |
| /// Unit Test Suite Handle | |
| /// | |
| struct UNIT_TEST_SUITE_OBJECT; | |
| typedef struct UNIT_TEST_SUITE_OBJECT *UNIT_TEST_SUITE_HANDLE; | |
| /// | |
| /// Unit Test Handle | |
| /// | |
| struct UNIT_TEST_OBJECT; | |
| typedef struct UNIT_TEST_OBJECT *UNIT_TEST_HANDLE; | |
| /// | |
| /// Unit Test Context | |
| /// | |
| typedef VOID *UNIT_TEST_CONTEXT; | |
| /** | |
| The prototype for a single UnitTest case function. | |
| Functions with this prototype are registered to be dispatched by the | |
| UnitTest framework, and results are recorded as test Pass or Fail. | |
| @param[in] Context [Optional] An optional parameter that enables: | |
| 1) test-case reuse with varied parameters and | |
| 2) test-case re-entry for Target tests that need a | |
| reboot. This parameter is a VOID* and it is the | |
| responsibility of the test author to ensure that the | |
| contents are well understood by all test cases that may | |
| consume it. | |
| @retval UNIT_TEST_PASSED The Unit test has completed and the test | |
| case was successful. | |
| @retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed. | |
| **/ | |
| typedef | |
| UNIT_TEST_STATUS | |
| (EFIAPI *UNIT_TEST_FUNCTION)( | |
| IN UNIT_TEST_CONTEXT Context | |
| ); | |
| /** | |
| Unit-Test Prerequisite Function pointer type. | |
| Functions with this prototype are registered to be dispatched by the unit test | |
| framework prior to a given test case. If this prereq function returns | |
| UNIT_TEST_ERROR_PREREQUISITE_NOT_MET, the test case will be skipped. | |
| @param[in] Context [Optional] An optional parameter that enables: | |
| 1) test-case reuse with varied parameters and | |
| 2) test-case re-entry for Target tests that need a | |
| reboot. This parameter is a VOID* and it is the | |
| responsibility of the test author to ensure that the | |
| contents are well understood by all test cases that may | |
| consume it. | |
| @retval UNIT_TEST_PASSED Unit test case prerequisites | |
| are met. | |
| @retval UNIT_TEST_ERROR_PREREQUISITE_NOT_MET Test case should be skipped. | |
| **/ | |
| typedef | |
| UNIT_TEST_STATUS | |
| (EFIAPI *UNIT_TEST_PREREQUISITE)( | |
| IN UNIT_TEST_CONTEXT Context | |
| ); | |
| /** | |
| Unit-Test Cleanup (after) function pointer type. | |
| Functions with this prototype are registered to be dispatched by the | |
| unit test framework after a given test case. This will be called even if the | |
| test case returns an error, but not if the prerequisite fails and the test is | |
| skipped. The purpose of this function is to clean up any global state or | |
| test data. | |
| @param[in] Context [Optional] An optional parameter that enables: | |
| 1) test-case reuse with varied parameters and | |
| 2) test-case re-entry for Target tests that need a | |
| reboot. This parameter is a VOID* and it is the | |
| responsibility of the test author to ensure that the | |
| contents are well understood by all test cases that may | |
| consume it. | |
| @retval UNIT_TEST_PASSED Test case cleanup succeeded. | |
| @retval UNIT_TEST_ERROR_CLEANUP_FAILED Test case cleanup failed. | |
| **/ | |
| typedef | |
| VOID | |
| (EFIAPI *UNIT_TEST_CLEANUP)( | |
| IN UNIT_TEST_CONTEXT Context | |
| ); | |
| /** | |
| Unit-Test Test Suite Setup (before) function pointer type. Functions with this | |
| prototype are registered to be dispatched by the UnitTest framework prior to | |
| running any of the test cases in a test suite. It will only be run once at | |
| the beginning of the suite (not prior to each case). | |
| The purpose of this function is to set up any global state or test data. | |
| **/ | |
| typedef | |
| VOID | |
| (EFIAPI *UNIT_TEST_SUITE_SETUP)( | |
| VOID | |
| ); | |
| /** | |
| Unit-Test Test Suite Teardown (after) function pointer type. Functions with | |
| this prototype are registered to be dispatched by the UnitTest framework after | |
| running all of the test cases in a test suite. It will only be run once at | |
| the end of the suite. | |
| The purpose of this function is to clean up any global state or test data. | |
| **/ | |
| typedef | |
| VOID | |
| (EFIAPI *UNIT_TEST_SUITE_TEARDOWN)( | |
| VOID | |
| ); | |
| /** | |
| Method to Initialize the Unit Test framework. This function registers the | |
| test name and also initializes the internal state of the test framework to | |
| receive any new suites and tests. | |
| @param[out] FrameworkHandle Unit test framework to be created. | |
| @param[in] Title Null-terminated ASCII string that is the user | |
| friendly name of the framework. String is | |
| copied. | |
| @param[in] ShortTitle Null-terminated ASCII short string that is the | |
| short name of the framework with no spaces. | |
| String is copied. | |
| @param[in] VersionString Null-terminated ASCII version string for the | |
| framework. String is copied. | |
| @retval EFI_SUCCESS The unit test framework was initialized. | |
| @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. | |
| @retval EFI_INVALID_PARAMETER Title is NULL. | |
| @retval EFI_INVALID_PARAMETER ShortTitle is NULL. | |
| @retval EFI_INVALID_PARAMETER VersionString is NULL. | |
| @retval EFI_INVALID_PARAMETER ShortTitle is invalid. | |
| @retval EFI_OUT_OF_RESOURCES There are not enough resources available to | |
| initialize the unit test framework. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| InitUnitTestFramework ( | |
| OUT UNIT_TEST_FRAMEWORK_HANDLE *FrameworkHandle, | |
| IN CHAR8 *Title, | |
| IN CHAR8 *ShortTitle, | |
| IN CHAR8 *VersionString | |
| ); | |
| /** | |
| Registers a Unit Test Suite in the Unit Test Framework. | |
| At least one test suite must be registered, because all test cases must be | |
| within a unit test suite. | |
| @param[out] SuiteHandle Unit test suite to create | |
| @param[in] FrameworkHandle Unit test framework to add unit test suite to | |
| @param[in] Title Null-terminated ASCII string that is the user | |
| friendly name of the test suite. String is | |
| copied. | |
| @param[in] Name Null-terminated ASCII string that is the short | |
| name of the test suite with no spaces. String | |
| is copied. | |
| @param[in] Setup Setup function, runs before suite. This is an | |
| optional parameter that may be NULL. | |
| @param[in] Teardown Teardown function, runs after suite. This is an | |
| optional parameter that may be NULL. | |
| @retval EFI_SUCCESS The unit test suite was created. | |
| @retval EFI_INVALID_PARAMETER SuiteHandle is NULL. | |
| @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. | |
| @retval EFI_INVALID_PARAMETER Title is NULL. | |
| @retval EFI_INVALID_PARAMETER Name is NULL. | |
| @retval EFI_OUT_OF_RESOURCES There are not enough resources available to | |
| initialize the unit test suite. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| CreateUnitTestSuite ( | |
| OUT UNIT_TEST_SUITE_HANDLE *SuiteHandle, | |
| IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle, | |
| IN CHAR8 *Title, | |
| IN CHAR8 *Name, | |
| IN UNIT_TEST_SUITE_SETUP Setup OPTIONAL, | |
| IN UNIT_TEST_SUITE_TEARDOWN Teardown OPTIONAL | |
| ); | |
| /** | |
| Adds test case to Suite | |
| @param[in] SuiteHandle Unit test suite to add test to. | |
| @param[in] Description Null-terminated ASCII string that is the user | |
| friendly description of a test. String is copied. | |
| @param[in] Name Null-terminated ASCII string that is the short name | |
| of the test with no spaces. String is copied. | |
| @param[in] Function Unit test function. | |
| @param[in] Prerequisite Prerequisite function, runs before test. This is | |
| an optional parameter that may be NULL. | |
| @param[in] CleanUp Clean up function, runs after test. This is an | |
| optional parameter that may be NULL. | |
| @param[in] Context Pointer to context. This is an optional parameter | |
| that may be NULL. | |
| @retval EFI_SUCCESS The unit test case was added to Suite. | |
| @retval EFI_INVALID_PARAMETER SuiteHandle is NULL. | |
| @retval EFI_INVALID_PARAMETER Description is NULL. | |
| @retval EFI_INVALID_PARAMETER Name is NULL. | |
| @retval EFI_INVALID_PARAMETER Function is NULL. | |
| @retval EFI_OUT_OF_RESOURCES There are not enough resources available to | |
| add the unit test case to Suite. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| AddTestCase ( | |
| IN UNIT_TEST_SUITE_HANDLE SuiteHandle, | |
| IN CHAR8 *Description, | |
| IN CHAR8 *Name, | |
| IN UNIT_TEST_FUNCTION Function, | |
| IN UNIT_TEST_PREREQUISITE Prerequisite OPTIONAL, | |
| IN UNIT_TEST_CLEANUP CleanUp OPTIONAL, | |
| IN UNIT_TEST_CONTEXT Context OPTIONAL | |
| ); | |
| /** | |
| Execute all unit test cases in all unit test suites added to a Framework. | |
| Once a unit test framework is initialized and all unit test suites and unit | |
| test cases are registered, this function will cause the unit test framework to | |
| dispatch all unit test cases in sequence and record the results for reporting. | |
| @param[in] FrameworkHandle A handle to the current running framework that | |
| dispatched the test. Necessary for recording | |
| certain test events with the framework. | |
| @retval EFI_SUCCESS All test cases were dispatched. | |
| @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| RunAllTestSuites ( | |
| IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle | |
| ); | |
| /** | |
| Cleanup a test framework. | |
| After tests are run, this will teardown the entire framework and free all | |
| allocated data within. | |
| @param[in] FrameworkHandle A handle to the current running framework that | |
| dispatched the test. Necessary for recording | |
| certain test events with the framework. | |
| @retval EFI_SUCCESS All resources associated with framework were | |
| freed. | |
| @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| FreeUnitTestFramework ( | |
| IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle | |
| ); | |
| /** | |
| Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're | |
| a framework author) to save the state of the executing framework along with | |
| any allocated data so that the test may be resumed upon reentry. A test case | |
| should pass any needed context (which, to prevent an infinite loop, should be | |
| at least the current execution count) which will be saved by the framework and | |
| passed to the test case upon resume. | |
| This should be called while the current test framework is valid and active. It is | |
| generally called from within a test case prior to quitting or rebooting. | |
| @param[in] ContextToSave A buffer of test case-specific data to be saved | |
| along with framework state. Will be passed as | |
| "Context" to the test case upon resume. This | |
| is an optional parameter that may be NULL. | |
| @param[in] ContextToSaveSize Size of the ContextToSave buffer. | |
| @retval EFI_SUCCESS The framework state and context were saved. | |
| @retval EFI_NOT_FOUND An active framework handle was not found. | |
| @retval EFI_INVALID_PARAMETER ContextToSave is not NULL and | |
| ContextToSaveSize is 0. | |
| @retval EFI_INVALID_PARAMETER ContextToSave is >= 4GB. | |
| @retval EFI_OUT_OF_RESOURCES There are not enough resources available to | |
| save the framework and context state. | |
| @retval EFI_DEVICE_ERROR The framework and context state could not be | |
| saved to a persistent storage device due to a | |
| device error. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| SaveFrameworkState ( | |
| IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL, | |
| IN UINTN ContextToSaveSize | |
| ); | |
| /** | |
| This macro uses the framework assertion logic to check an expression for | |
| "TRUE". If the expression evaluates to TRUE, execution continues. | |
| Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. | |
| @param[in] Expression Expression to be evaluated for TRUE. | |
| **/ | |
| #define UT_ASSERT_TRUE(Expression) \ | |
| if(!UnitTestAssertTrue ((Expression), __func__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } | |
| /** | |
| This macro uses the framework assertion logic to check an expression for | |
| "FALSE". If the expression evaluates to FALSE, execution continues. | |
| Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. | |
| @param[in] Expression Expression to be evaluated for FALSE. | |
| **/ | |
| #define UT_ASSERT_FALSE(Expression) \ | |
| if(!UnitTestAssertFalse ((Expression), __func__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } | |
| /** | |
| This macro uses the framework assertion logic to check whether two simple | |
| values are equal. If the values are equal, execution continues. | |
| Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. | |
| @param[in] ValueA Value to be compared for equality (64-bit comparison). | |
| @param[in] ValueB Value to be compared for equality (64-bit comparison). | |
| **/ | |
| #define UT_ASSERT_EQUAL(ValueA, ValueB) \ | |
| if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __func__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } | |
| /** | |
| This macro uses the framework assertion logic to check whether two memory | |
| buffers are equal. If the buffers are equal, execution continues. | |
| Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. | |
| @param[in] BufferA Pointer to a buffer for comparison. | |
| @param[in] BufferB Pointer to a buffer for comparison. | |
| @param[in] Length Number of bytes to compare in BufferA and BufferB. | |
| **/ | |
| #define UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length) \ | |
| if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __func__, DEBUG_LINE_NUMBER, __FILE__, #BufferA, #BufferB)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } | |
| /** | |
| This macro uses the framework assertion logic to check whether two simple | |
| values are non-equal. If the values are non-equal, execution continues. | |
| Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. | |
| @param[in] ValueA Value to be compared for inequality (64-bit comparison). | |
| @param[in] ValueB Value to be compared for inequality (64-bit comparison). | |
| **/ | |
| #define UT_ASSERT_NOT_EQUAL(ValueA, ValueB) \ | |
| if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __func__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } | |
| /** | |
| This macro uses the framework assertion logic to check whether an EFI_STATUS | |
| value is !EFI_ERROR(). If the status is !EFI_ERROR(), execution continues. | |
| Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. | |
| @param[in] Status EFI_STATUS value to check. | |
| **/ | |
| #define UT_ASSERT_NOT_EFI_ERROR(Status) \ | |
| if(!UnitTestAssertNotEfiError ((Status), __func__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } | |
| /** | |
| This macro uses the framework assertion logic to check whether two EFI_STATUS | |
| values are equal. If the values are equal, execution continues. | |
| Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. | |
| @param[in] Status EFI_STATUS values to compare for equality. | |
| @param[in] Expected EFI_STATUS values to compare for equality. | |
| **/ | |
| #define UT_ASSERT_STATUS_EQUAL(Status, Expected) \ | |
| if(!UnitTestAssertStatusEqual ((Status), (Expected), __func__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } | |
| /** | |
| This macro uses the framework assertion logic to check whether a pointer is | |
| not NULL. If the pointer is not NULL, execution continues. Otherwise, the | |
| test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. | |
| @param[in] Pointer Pointer to be checked against NULL. | |
| **/ | |
| #define UT_ASSERT_NOT_NULL(Pointer) \ | |
| if(!UnitTestAssertNotNull ((Pointer), __func__, DEBUG_LINE_NUMBER, __FILE__, #Pointer)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } | |
| /** | |
| This macro uses the framework assertion logic to check whether a function call | |
| triggers an ASSERT() condition. The BaseLib SetJump()/LongJump() services | |
| are used to establish a safe return point when an ASSERT() is triggered. | |
| If an ASSERT() is triggered, unit test execution continues and Status is set | |
| to UNIT_TEST_PASSED. Otherwise, a unit test case failure is raised and | |
| Status is set to UNIT_TEST_ERROR_TEST_FAILED. | |
| If ASSERT() macros are disabled, then the test case is skipped and a warning | |
| message is added to the unit test log. Status is set to UNIT_TEST_SKIPPED. | |
| @param[in] FunctionCall Function call that is expected to trigger ASSERT(). | |
| @param[out] Status Pointer to a UNIT_TEST_STATUS return value. This | |
| is an optional parameter that may be NULL. | |
| **/ | |
| #if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED) | |
| #include <Library/BaseLib.h> | |
| /// | |
| /// Pointer to jump buffer used with SetJump()/LongJump() to test if a | |
| /// function under test generates an expected ASSERT() condition. | |
| /// | |
| extern BASE_LIBRARY_JUMP_BUFFER *gUnitTestExpectAssertFailureJumpBuffer; | |
| #define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) \ | |
| do { \ | |
| UNIT_TEST_STATUS UnitTestJumpStatus; \ | |
| BASE_LIBRARY_JUMP_BUFFER UnitTestJumpBuffer; \ | |
| UnitTestJumpStatus = UNIT_TEST_SKIPPED; \ | |
| if (DebugAssertEnabled ()) { \ | |
| gUnitTestExpectAssertFailureJumpBuffer = &UnitTestJumpBuffer; \ | |
| if (SetJump (gUnitTestExpectAssertFailureJumpBuffer) == 0) { \ | |
| FunctionCall; \ | |
| UnitTestJumpStatus = UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } else { \ | |
| UnitTestJumpStatus = UNIT_TEST_PASSED; \ | |
| } \ | |
| gUnitTestExpectAssertFailureJumpBuffer = NULL; \ | |
| } \ | |
| if (!UnitTestExpectAssertFailure ( \ | |
| UnitTestJumpStatus, \ | |
| __func__, DEBUG_LINE_NUMBER, __FILE__, \ | |
| #FunctionCall, Status)) { \ | |
| return UNIT_TEST_ERROR_TEST_FAILED; \ | |
| } \ | |
| } while (FALSE) | |
| #else | |
| #define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) FunctionCall; | |
| #endif | |
| /** | |
| If Expression is TRUE, then TRUE is returned. | |
| If Expression is FALSE, then an assert is triggered and the location of the | |
| assert provided by FunctionName, LineNumber, FileName, and Description are | |
| recorded and FALSE is returned. | |
| @param[in] Expression The BOOLEAN result of the expression evaluation. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the assert macro. | |
| @param[in] LineNumber The source file line number of the assert macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the assert macro. | |
| @param[in] Description Null-terminated ASCII string of the expression being | |
| evaluated. | |
| @retval TRUE Expression is TRUE. | |
| @retval FALSE Expression is FALSE. | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestAssertTrue ( | |
| IN BOOLEAN Expression, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *Description | |
| ); | |
| /** | |
| If Expression is FALSE, then TRUE is returned. | |
| If Expression is TRUE, then an assert is triggered and the location of the | |
| assert provided by FunctionName, LineNumber, FileName, and Description are | |
| recorded and FALSE is returned. | |
| @param[in] Expression The BOOLEAN result of the expression evaluation. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the assert macro. | |
| @param[in] LineNumber The source file line number of the assert macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the assert macro. | |
| @param[in] Description Null-terminated ASCII string of the expression being | |
| evaluated. | |
| @retval TRUE Expression is FALSE. | |
| @retval FALSE Expression is TRUE. | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestAssertFalse ( | |
| IN BOOLEAN Expression, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *Description | |
| ); | |
| /** | |
| If Status is not an EFI_ERROR(), then TRUE is returned. | |
| If Status is an EFI_ERROR(), then an assert is triggered and the location of | |
| the assert provided by FunctionName, LineNumber, FileName, and Description are | |
| recorded and FALSE is returned. | |
| @param[in] Status The EFI_STATUS value to evaluate. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the assert macro. | |
| @param[in] LineNumber The source file line number of the assert macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the assert macro. | |
| @param[in] Description Null-terminated ASCII string of the status | |
| expression being evaluated. | |
| @retval TRUE Status is not an EFI_ERROR(). | |
| @retval FALSE Status is an EFI_ERROR(). | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestAssertNotEfiError ( | |
| IN EFI_STATUS Status, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *Description | |
| ); | |
| /** | |
| If ValueA is equal ValueB, then TRUE is returned. | |
| If ValueA is not equal to ValueB, then an assert is triggered and the location | |
| of the assert provided by FunctionName, LineNumber, FileName, DescriptionA, | |
| and DescriptionB are recorded and FALSE is returned. | |
| @param[in] ValueA 64-bit value. | |
| @param[in] ValueB 64-bit value. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the assert macro. | |
| @param[in] LineNumber The source file line number of the assert macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the assert macro. | |
| @param[in] DescriptionA Null-terminated ASCII string that is a description | |
| of ValueA. | |
| @param[in] DescriptionB Null-terminated ASCII string that is a description | |
| of ValueB. | |
| @retval TRUE ValueA is equal to ValueB. | |
| @retval FALSE ValueA is not equal to ValueB. | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestAssertEqual ( | |
| IN UINT64 ValueA, | |
| IN UINT64 ValueB, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *DescriptionA, | |
| IN CONST CHAR8 *DescriptionB | |
| ); | |
| /** | |
| If the contents of BufferA are identical to the contents of BufferB, then TRUE | |
| is returned. If the contents of BufferA are not identical to the contents of | |
| BufferB, then an assert is triggered and the location of the assert provided | |
| by FunctionName, LineNumber, FileName, DescriptionA, and DescriptionB are | |
| recorded and FALSE is returned. | |
| @param[in] BufferA Pointer to a buffer for comparison. | |
| @param[in] BufferB Pointer to a buffer for comparison. | |
| @param[in] Length Number of bytes to compare in BufferA and BufferB. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the assert macro. | |
| @param[in] LineNumber The source file line number of the assert macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the assert macro. | |
| @param[in] DescriptionA Null-terminated ASCII string that is a description | |
| of BufferA. | |
| @param[in] DescriptionB Null-terminated ASCII string that is a description | |
| of BufferB. | |
| @retval TRUE The contents of BufferA are identical to the contents of | |
| BufferB. | |
| @retval FALSE The contents of BufferA are not identical to the contents of | |
| BufferB. | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestAssertMemEqual ( | |
| IN VOID *BufferA, | |
| IN VOID *BufferB, | |
| IN UINTN Length, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *DescriptionA, | |
| IN CONST CHAR8 *DescriptionB | |
| ); | |
| /** | |
| If ValueA is not equal ValueB, then TRUE is returned. | |
| If ValueA is equal to ValueB, then an assert is triggered and the location | |
| of the assert provided by FunctionName, LineNumber, FileName, DescriptionA | |
| and DescriptionB are recorded and FALSE is returned. | |
| @param[in] ValueA 64-bit value. | |
| @param[in] ValueB 64-bit value. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the assert macro. | |
| @param[in] LineNumber The source file line number of the assert macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the assert macro. | |
| @param[in] DescriptionA Null-terminated ASCII string that is a description | |
| of ValueA. | |
| @param[in] DescriptionB Null-terminated ASCII string that is a description | |
| of ValueB. | |
| @retval TRUE ValueA is not equal to ValueB. | |
| @retval FALSE ValueA is equal to ValueB. | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestAssertNotEqual ( | |
| IN UINT64 ValueA, | |
| IN UINT64 ValueB, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *DescriptionA, | |
| IN CONST CHAR8 *DescriptionB | |
| ); | |
| /** | |
| If Status is equal to Expected, then TRUE is returned. | |
| If Status is not equal to Expected, then an assert is triggered and the | |
| location of the assert provided by FunctionName, LineNumber, FileName, and | |
| Description are recorded and FALSE is returned. | |
| @param[in] Status EFI_STATUS value returned from an API under test. | |
| @param[in] Expected The expected EFI_STATUS return value from an API | |
| under test. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the assert macro. | |
| @param[in] LineNumber The source file line number of the assert macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the assert macro. | |
| @param[in] Description Null-terminated ASCII string that is a description | |
| of Status. | |
| @retval TRUE Status is equal to Expected. | |
| @retval FALSE Status is not equal to Expected. | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestAssertStatusEqual ( | |
| IN EFI_STATUS Status, | |
| IN EFI_STATUS Expected, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *Description | |
| ); | |
| /** | |
| If Pointer is not equal to NULL, then TRUE is returned. | |
| If Pointer is equal to NULL, then an assert is triggered and the location of | |
| the assert provided by FunctionName, LineNumber, FileName, and PointerName | |
| are recorded and FALSE is returned. | |
| @param[in] Pointer Pointer value to be checked against NULL. | |
| @param[in] Expected The expected EFI_STATUS return value from a function | |
| under test. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the assert macro. | |
| @param[in] LineNumber The source file line number of the assert macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the assert macro. | |
| @param[in] PointerName Null-terminated ASCII string that is a description | |
| of Pointer. | |
| @retval TRUE Pointer is not equal to NULL. | |
| @retval FALSE Pointer is equal to NULL. | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestAssertNotNull ( | |
| IN VOID *Pointer, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *PointerName | |
| ); | |
| /** | |
| If UnitTestStatus is UNIT_TEST_PASSED, then log an info message and return | |
| TRUE because an ASSERT() was expected when FunctionCall was executed and an | |
| ASSERT() was triggered. If UnitTestStatus is UNIT_TEST_SKIPPED, then log a | |
| warning message and return TRUE because ASSERT() macros are disabled. If | |
| UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED, then log an error message and | |
| return FALSE because an ASSERT() was expected when FunctionCall was executed, | |
| but no ASSERT() conditions were triggered. The log messages contain | |
| FunctionName, LineNumber, and FileName strings to provide the location of the | |
| UT_EXPECT_ASSERT_FAILURE() macro. | |
| @param[in] UnitTestStatus The status from UT_EXPECT_ASSERT_FAILURE() that | |
| is either pass, skipped, or failed. | |
| @param[in] FunctionName Null-terminated ASCII string of the function | |
| executing the UT_EXPECT_ASSERT_FAILURE() macro. | |
| @param[in] LineNumber The source file line number of the the function | |
| executing the UT_EXPECT_ASSERT_FAILURE() macro. | |
| @param[in] FileName Null-terminated ASCII string of the filename | |
| executing the UT_EXPECT_ASSERT_FAILURE() macro. | |
| @param[in] FunctionCall Null-terminated ASCII string of the function call | |
| executed by the UT_EXPECT_ASSERT_FAILURE() macro. | |
| @param[out] ResultStatus Used to return the UnitTestStatus value to the | |
| caller of UT_EXPECT_ASSERT_FAILURE(). This is | |
| optional parameter that may be NULL. | |
| @retval TRUE UnitTestStatus is UNIT_TEST_PASSED. | |
| @retval TRUE UnitTestStatus is UNIT_TEST_SKIPPED. | |
| @retval FALSE UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED. | |
| **/ | |
| BOOLEAN | |
| EFIAPI | |
| UnitTestExpectAssertFailure ( | |
| IN UNIT_TEST_STATUS UnitTestStatus, | |
| IN CONST CHAR8 *FunctionName, | |
| IN UINTN LineNumber, | |
| IN CONST CHAR8 *FileName, | |
| IN CONST CHAR8 *FunctionCall, | |
| OUT UNIT_TEST_STATUS *ResultStatus OPTIONAL | |
| ); | |
| /** | |
| Test logging macro that records an ERROR message in the test framework log. | |
| Record is associated with the currently executing test case. | |
| @param[in] Format Formatting string following the format defined in | |
| MdePkg/Include/Library/PrintLib.h. | |
| @param[in] ... Print args. | |
| **/ | |
| #define UT_LOG_ERROR(Format, ...) \ | |
| UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__) | |
| /** | |
| Test logging macro that records a WARNING message in the test framework log. | |
| Record is associated with the currently executing test case. | |
| @param[in] Format Formatting string following the format defined in | |
| MdePkg/Include/Library/PrintLib.h. | |
| @param[in] ... Print args. | |
| **/ | |
| #define UT_LOG_WARNING(Format, ...) \ | |
| UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, Format, ##__VA_ARGS__) | |
| /** | |
| Test logging macro that records an INFO message in the test framework log. | |
| Record is associated with the currently executing test case. | |
| @param[in] Format Formatting string following the format defined in | |
| MdePkg/Include/Library/PrintLib.h. | |
| @param[in] ... Print args. | |
| **/ | |
| #define UT_LOG_INFO(Format, ...) \ | |
| UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, Format, ##__VA_ARGS__) | |
| /** | |
| Test logging macro that records a VERBOSE message in the test framework log. | |
| Record is associated with the currently executing test case. | |
| @param[in] Format Formatting string following the format defined in | |
| MdePkg/Include/Library/PrintLib.h. | |
| @param[in] ... Print args. | |
| **/ | |
| #define UT_LOG_VERBOSE(Format, ...) \ | |
| UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, Format, ##__VA_ARGS__) | |
| /** | |
| Test logging function that records a messages in the test framework log. | |
| Record is associated with the currently executing test case. | |
| @param[in] ErrorLevel The error level of the unit test log message. | |
| @param[in] Format Formatting string following the format defined in the | |
| MdePkg/Include/Library/PrintLib.h. | |
| @param[in] ... Print args. | |
| **/ | |
| VOID | |
| EFIAPI | |
| UnitTestLog ( | |
| IN UINTN ErrorLevel, | |
| IN CONST CHAR8 *Format, | |
| ... | |
| ); | |
| #endif |