2 This is a sample to demostrate the usage of the Unit Test Library that
3 supports the PEI, DXE, SMM, UEFI SHell, and host execution environments.
5 Copyright (c) Microsoft Corporation.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
11 #include <Library/UefiLib.h>
12 #include <Library/DebugLib.h>
13 #include <Library/UnitTestLib.h>
14 #include <Library/PrintLib.h>
16 #define UNIT_TEST_NAME "Sample Unit Test"
17 #define UNIT_TEST_VERSION "0.1"
20 /// Global variables used in unit tests
22 BOOLEAN mSampleGlobalTestBoolean
= FALSE
;
23 VOID
*mSampleGlobalTestPointer
= NULL
;
26 Sample Unit-Test Prerequisite Function that checks to make sure the global
27 pointer used in the test is already set to NULL.
29 Functions with this prototype are registered to be dispatched by the unit test
30 framework prior to a given test case. If this prereq function returns
31 UNIT_TEST_ERROR_PREREQUISITE_NOT_MET, the test case will be skipped.
33 @param[in] Context [Optional] An optional parameter that enables:
34 1) test-case reuse with varied parameters and
35 2) test-case re-entry for Target tests that need a
36 reboot. This parameter is a VOID* and it is the
37 responsibility of the test author to ensure that the
38 contents are well understood by all test cases that may
41 @retval UNIT_TEST_PASSED Unit test case prerequisites
43 @retval UNIT_TEST_ERROR_PREREQUISITE_NOT_MET Test case should be skipped.
48 MakeSureThatPointerIsNull (
49 IN UNIT_TEST_CONTEXT Context
52 UT_ASSERT_EQUAL ((UINTN
)mSampleGlobalTestPointer
, (UINTN
)NULL
);
53 return UNIT_TEST_PASSED
;
57 Sample Unit-Test Cleanup (after) function that resets the global pointer to
60 Functions with this prototype are registered to be dispatched by the
61 unit test framework after a given test case. This will be called even if the
62 test case returns an error, but not if the prerequisite fails and the test is
63 skipped. The purpose of this function is to clean up any global state or
66 @param[in] Context [Optional] An optional parameter that enables:
67 1) test-case reuse with varied parameters and
68 2) test-case re-entry for Target tests that need a
69 reboot. This parameter is a VOID* and it is the
70 responsibility of the test author to ensure that the
71 contents are well understood by all test cases that may
74 @retval UNIT_TEST_PASSED Test case cleanup succeeded.
75 @retval UNIT_TEST_ERROR_CLEANUP_FAILED Test case cleanup failed.
81 IN UNIT_TEST_CONTEXT Context
84 mSampleGlobalTestPointer
= NULL
;
88 Sample unit test that verifies the expected result of an unsigned integer
91 @param[in] Context [Optional] An optional parameter that enables:
92 1) test-case reuse with varied parameters and
93 2) test-case re-entry for Target tests that need a
94 reboot. This parameter is a VOID* and it is the
95 responsibility of the test author to ensure that the
96 contents are well understood by all test cases that may
99 @retval UNIT_TEST_PASSED The Unit test has completed and the test
101 @retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed.
105 OnePlusOneShouldEqualTwo (
106 IN UNIT_TEST_CONTEXT Context
117 UT_ASSERT_EQUAL (C
, 2);
119 return UNIT_TEST_PASSED
;
123 Sample unit test that verifies that a global BOOLEAN is updatable.
125 @param[in] Context [Optional] An optional parameter that enables:
126 1) test-case reuse with varied parameters and
127 2) test-case re-entry for Target tests that need a
128 reboot. This parameter is a VOID* and it is the
129 responsibility of the test author to ensure that the
130 contents are well understood by all test cases that may
133 @retval UNIT_TEST_PASSED The Unit test has completed and the test
135 @retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed.
139 GlobalBooleanShouldBeChangeable (
140 IN UNIT_TEST_CONTEXT Context
143 mSampleGlobalTestBoolean
= TRUE
;
144 UT_ASSERT_TRUE (mSampleGlobalTestBoolean
);
146 mSampleGlobalTestBoolean
= FALSE
;
147 UT_ASSERT_FALSE (mSampleGlobalTestBoolean
);
149 return UNIT_TEST_PASSED
;
153 Sample unit test that logs a warning message and verifies that a global
154 pointer is updatable.
156 @param[in] Context [Optional] An optional parameter that enables:
157 1) test-case reuse with varied parameters and
158 2) test-case re-entry for Target tests that need a
159 reboot. This parameter is a VOID* and it is the
160 responsibility of the test author to ensure that the
161 contents are well understood by all test cases that may
164 @retval UNIT_TEST_PASSED The Unit test has completed and the test
166 @retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed.
170 GlobalPointerShouldBeChangeable (
171 IN UNIT_TEST_CONTEXT Context
175 // Example of logging.
177 UT_LOG_WARNING ("About to change a global pointer! Current value is 0x%X\n", mSampleGlobalTestPointer
);
179 mSampleGlobalTestPointer
= (VOID
*)-1;
180 UT_ASSERT_EQUAL ((UINTN
)mSampleGlobalTestPointer
, (UINTN
)((VOID
*)-1));
181 return UNIT_TEST_PASSED
;
185 Initialize the unit test framework, suite, and unit tests for the
186 sample unit tests and run the unit tests.
188 @retval EFI_SUCCESS All test cases were dispatched.
189 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
190 initialize the unit tests.
199 UNIT_TEST_FRAMEWORK_HANDLE Framework
;
200 UNIT_TEST_SUITE_HANDLE SimpleMathTests
;
201 UNIT_TEST_SUITE_HANDLE GlobalVarTests
;
205 DEBUG(( DEBUG_INFO
, "%a v%a\n", UNIT_TEST_NAME
, UNIT_TEST_VERSION
));
208 // Start setting up the test framework for running the tests.
210 Status
= InitUnitTestFramework (&Framework
, UNIT_TEST_NAME
, gEfiCallerBaseName
, UNIT_TEST_VERSION
);
211 if (EFI_ERROR (Status
)) {
212 DEBUG((DEBUG_ERROR
, "Failed in InitUnitTestFramework. Status = %r\n", Status
));
217 // Populate the SimpleMathTests Unit Test Suite.
219 Status
= CreateUnitTestSuite (&SimpleMathTests
, Framework
, "Simple Math Tests", "Sample.Math", NULL
, NULL
);
220 if (EFI_ERROR (Status
)) {
221 DEBUG ((DEBUG_ERROR
, "Failed in CreateUnitTestSuite for SimpleMathTests\n"));
222 Status
= EFI_OUT_OF_RESOURCES
;
225 AddTestCase (SimpleMathTests
, "Adding 1 to 1 should produce 2", "Addition", OnePlusOneShouldEqualTwo
, NULL
, NULL
, NULL
);
228 // Populate the GlobalVarTests Unit Test Suite.
230 Status
= CreateUnitTestSuite (&GlobalVarTests
, Framework
, "Global Variable Tests", "Sample.Globals", NULL
, NULL
);
231 if (EFI_ERROR (Status
)) {
232 DEBUG ((DEBUG_ERROR
, "Failed in CreateUnitTestSuite for GlobalVarTests\n"));
233 Status
= EFI_OUT_OF_RESOURCES
;
236 AddTestCase (GlobalVarTests
, "You should be able to change a global BOOLEAN", "Boolean", GlobalBooleanShouldBeChangeable
, NULL
, NULL
, NULL
);
237 AddTestCase (GlobalVarTests
, "You should be able to change a global pointer", "Pointer", GlobalPointerShouldBeChangeable
, MakeSureThatPointerIsNull
, ClearThePointer
, NULL
);
240 // Execute the tests.
242 Status
= RunAllTestSuites (Framework
);
246 FreeUnitTestFramework (Framework
);
253 Standard PEIM entry point for target based unit test execution from PEI.
258 IN EFI_PEI_FILE_HANDLE FileHandle
,
259 IN CONST EFI_PEI_SERVICES
**PeiServices
262 return UefiTestMain ();
266 Standard UEFI entry point for target based unit test execution from DXE, SMM,
272 IN EFI_HANDLE ImageHandle
,
273 IN EFI_SYSTEM_TABLE
*SystemTable
276 return UefiTestMain ();
280 Standard POSIX C entry point for host based unit test execution.
288 return UefiTestMain ();