4 Copyright (c) Microsoft Corporation.
5 Copyright (c) 2022, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
10 #include <Library/UnitTestLib.h>
11 #include <Library/BaseLib.h>
12 #include <Library/BaseMemoryLib.h>
13 #include <Library/MemoryAllocationLib.h>
14 #include <Library/DebugLib.h>
15 #include <Library/UnitTestPersistenceLib.h>
16 #include <Library/UnitTestResultReportLib.h>
19 /// Forward declaration of prototype
24 IN OUT UNIT_TEST
*Test
,
25 IN UNIT_TEST_SAVE_HEADER
*SavedState
29 This function will determine whether the short name violates any rules that would
30 prevent it from being used as a reporting name or as a serialization name.
32 Example: If the name cannot be serialized to a filesystem file name.
34 @param[in] ShortTitleString A pointer to the short title string to be evaluated.
36 @retval TRUE The string is acceptable.
37 @retval FALSE The string should not be used.
42 IsFrameworkShortNameValid (
43 IN CHAR8
*ShortTitleString
46 // TODO: Finish this function.
52 AllocateAndCopyString (
53 IN CHAR8
*StringToCopy
57 UINTN NewStringLength
;
60 NewStringLength
= AsciiStrnLenS (StringToCopy
, UNIT_TEST_MAX_STRING_LENGTH
) + 1;
61 NewString
= AllocatePool (NewStringLength
* sizeof (CHAR8
));
62 if (NewString
!= NULL
) {
63 AsciiStrCpyS (NewString
, NewStringLength
, StringToCopy
);
71 SetFrameworkFingerprint (
72 OUT UINT8
*Fingerprint
,
73 IN UNIT_TEST_FRAMEWORK
*Framework
76 UINT32 NewFingerprint
;
78 // For this one we'll just use the title and version as the unique fingerprint.
79 NewFingerprint
= CalculateCrc32 (Framework
->Title
, (AsciiStrLen (Framework
->Title
) * sizeof (CHAR8
)));
80 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32 (Framework
->VersionString
, (AsciiStrLen (Framework
->VersionString
) * sizeof (CHAR8
)));
82 CopyMem (Fingerprint
, &NewFingerprint
, UNIT_TEST_FINGERPRINT_SIZE
);
89 OUT UINT8
*Fingerprint
,
90 IN UNIT_TEST_FRAMEWORK
*Framework
,
91 IN UNIT_TEST_SUITE
*Suite
94 UINT32 NewFingerprint
;
96 // For this one, we'll use the fingerprint from the framework, and the title of the suite.
97 NewFingerprint
= CalculateCrc32 (&Framework
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
98 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32 (Suite
->Title
, (AsciiStrLen (Suite
->Title
) * sizeof (CHAR8
)));
99 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32 (Suite
->Name
, (AsciiStrLen (Suite
->Name
) * sizeof (CHAR8
)));
101 CopyMem (Fingerprint
, &NewFingerprint
, UNIT_TEST_FINGERPRINT_SIZE
);
108 OUT UINT8
*Fingerprint
,
109 IN UNIT_TEST_SUITE
*Suite
,
113 UINT32 NewFingerprint
;
115 // For this one, we'll use the fingerprint from the suite, and the description and classname of the test.
116 NewFingerprint
= CalculateCrc32 (&Suite
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
117 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32 (Test
->Description
, (AsciiStrLen (Test
->Description
) * sizeof (CHAR8
)));
118 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32 (Test
->Name
, (AsciiStrLen (Test
->Name
) * sizeof (CHAR8
)));
120 CopyMem (Fingerprint
, &NewFingerprint
, UNIT_TEST_FINGERPRINT_SIZE
);
126 CompareFingerprints (
127 IN UINT8
*FingerprintA
,
128 IN UINT8
*FingerprintB
131 return (CompareMem (FingerprintA
, FingerprintB
, UNIT_TEST_FINGERPRINT_SIZE
) == 0);
135 Cleanup a test framework.
137 After tests are run, this will teardown the entire framework and free all
138 allocated data within.
140 @param[in] FrameworkHandle A handle to the current running framework that
141 dispatched the test. Necessary for recording
142 certain test events with the framework.
144 @retval EFI_SUCCESS All resources associated with framework were
146 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
150 FreeUnitTestFramework (
151 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
154 // TODO: Finish this function.
160 FreeUnitTestSuiteEntry (
161 IN UNIT_TEST_SUITE_LIST_ENTRY
*SuiteEntry
164 // TODO: Finish this function.
170 FreeUnitTestTestEntry (
171 IN UNIT_TEST_LIST_ENTRY
*TestEntry
174 // TODO: Finish this function.
179 Method to Initialize the Unit Test framework. This function registers the
180 test name and also initializes the internal state of the test framework to
181 receive any new suites and tests.
183 @param[out] FrameworkHandle Unit test framework to be created.
184 @param[in] Title Null-terminated ASCII string that is the user
185 friendly name of the framework. String is
187 @param[in] ShortTitle Null-terminated ASCII short string that is the
188 short name of the framework with no spaces.
190 @param[in] VersionString Null-terminated ASCII version string for the
191 framework. String is copied.
193 @retval EFI_SUCCESS The unit test framework was initialized.
194 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
195 @retval EFI_INVALID_PARAMETER Title is NULL.
196 @retval EFI_INVALID_PARAMETER ShortTitle is NULL.
197 @retval EFI_INVALID_PARAMETER VersionString is NULL.
198 @retval EFI_INVALID_PARAMETER ShortTitle is invalid.
199 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
200 initialize the unit test framework.
204 InitUnitTestFramework (
205 OUT UNIT_TEST_FRAMEWORK_HANDLE
*FrameworkHandle
,
207 IN CHAR8
*ShortTitle
,
208 IN CHAR8
*VersionString
212 UNIT_TEST_FRAMEWORK_HANDLE NewFrameworkHandle
;
213 UNIT_TEST_FRAMEWORK
*NewFramework
;
216 Status
= EFI_SUCCESS
;
220 // First, check all pointers and make sure nothing's broked.
222 if ((FrameworkHandle
== NULL
) || (Title
== NULL
) ||
223 (ShortTitle
== NULL
) || (VersionString
== NULL
))
225 return EFI_INVALID_PARAMETER
;
229 // Next, determine whether all of the strings are good to use.
231 if (!IsFrameworkShortNameValid (ShortTitle
)) {
232 return EFI_INVALID_PARAMETER
;
236 // Next, set aside some space to start messing with the framework.
238 NewFramework
= AllocateZeroPool (sizeof (UNIT_TEST_FRAMEWORK
));
239 if (NewFramework
== NULL
) {
240 return EFI_OUT_OF_RESOURCES
;
244 // Next, set up all the test data.
246 NewFrameworkHandle
= (UNIT_TEST_FRAMEWORK_HANDLE
)NewFramework
;
247 NewFramework
->Title
= AllocateAndCopyString (Title
);
248 NewFramework
->ShortTitle
= AllocateAndCopyString (ShortTitle
);
249 NewFramework
->VersionString
= AllocateAndCopyString (VersionString
);
250 NewFramework
->Log
= NULL
;
251 NewFramework
->CurrentTest
= NULL
;
252 NewFramework
->SavedState
= NULL
;
253 if ((NewFramework
->Title
== NULL
) ||
254 (NewFramework
->ShortTitle
== NULL
) ||
255 (NewFramework
->VersionString
== NULL
))
257 Status
= EFI_OUT_OF_RESOURCES
;
261 InitializeListHead (&(NewFramework
->TestSuiteList
));
264 // Create the framework fingerprint.
266 SetFrameworkFingerprint (&NewFramework
->Fingerprint
[0], NewFramework
);
269 // If there is a persisted context, load it now.
271 if (DoesCacheExist (NewFrameworkHandle
)) {
272 Status
= LoadUnitTestCache (NewFrameworkHandle
, (VOID
**)(&NewFramework
->SavedState
), &SaveStateSize
);
273 if (EFI_ERROR (Status
)) {
275 // Don't actually report it as an error, but emit a warning.
277 DEBUG ((DEBUG_ERROR
, "%a - Cache was detected, but failed to load.\n", __FUNCTION__
));
278 Status
= EFI_SUCCESS
;
284 // If we're good, then let's copy the framework.
286 if (!EFI_ERROR (Status
)) {
287 *FrameworkHandle
= NewFrameworkHandle
;
290 // Otherwise, we need to undo this horrible thing that we've done.
292 FreeUnitTestFramework (NewFrameworkHandle
);
299 Registers a Unit Test Suite in the Unit Test Framework.
300 At least one test suite must be registered, because all test cases must be
301 within a unit test suite.
303 @param[out] SuiteHandle Unit test suite to create
304 @param[in] FrameworkHandle Unit test framework to add unit test suite to
305 @param[in] Title Null-terminated ASCII string that is the user
306 friendly name of the test suite. String is
308 @param[in] Name Null-terminated ASCII string that is the short
309 name of the test suite with no spaces. String
311 @param[in] Setup Setup function, runs before suite. This is an
312 optional parameter that may be NULL.
313 @param[in] Teardown Teardown function, runs after suite. This is an
314 optional parameter that may be NULL.
316 @retval EFI_SUCCESS The unit test suite was created.
317 @retval EFI_INVALID_PARAMETER SuiteHandle is NULL.
318 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
319 @retval EFI_INVALID_PARAMETER Title is NULL.
320 @retval EFI_INVALID_PARAMETER Name is NULL.
321 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
322 initialize the unit test suite.
326 CreateUnitTestSuite (
327 OUT UNIT_TEST_SUITE_HANDLE
*SuiteHandle
,
328 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
,
331 IN UNIT_TEST_SUITE_SETUP Setup OPTIONAL
,
332 IN UNIT_TEST_SUITE_TEARDOWN Teardown OPTIONAL
336 UNIT_TEST_SUITE_LIST_ENTRY
*NewSuiteEntry
;
337 UNIT_TEST_FRAMEWORK
*Framework
;
339 Status
= EFI_SUCCESS
;
340 Framework
= (UNIT_TEST_FRAMEWORK
*)FrameworkHandle
;
343 // First, let's check to make sure that our parameters look good.
345 if ((SuiteHandle
== NULL
) || (Framework
== NULL
) || (Title
== NULL
) || (Name
== NULL
)) {
346 return EFI_INVALID_PARAMETER
;
350 // Create the new entry.
352 NewSuiteEntry
= AllocateZeroPool (sizeof (UNIT_TEST_SUITE_LIST_ENTRY
));
353 if (NewSuiteEntry
== NULL
) {
354 return EFI_OUT_OF_RESOURCES
;
358 // Copy the fields we think we need.
360 NewSuiteEntry
->UTS
.NumTests
= 0;
361 NewSuiteEntry
->UTS
.Title
= AllocateAndCopyString (Title
);
362 NewSuiteEntry
->UTS
.Name
= AllocateAndCopyString (Name
);
363 NewSuiteEntry
->UTS
.Setup
= Setup
;
364 NewSuiteEntry
->UTS
.Teardown
= Teardown
;
365 NewSuiteEntry
->UTS
.ParentFramework
= FrameworkHandle
;
366 InitializeListHead (&(NewSuiteEntry
->Entry
)); // List entry for sibling suites.
367 InitializeListHead (&(NewSuiteEntry
->UTS
.TestCaseList
)); // List entry for child tests.
368 if (NewSuiteEntry
->UTS
.Title
== NULL
) {
369 Status
= EFI_OUT_OF_RESOURCES
;
373 if (NewSuiteEntry
->UTS
.Name
== NULL
) {
374 Status
= EFI_OUT_OF_RESOURCES
;
379 // Create the suite fingerprint.
381 SetSuiteFingerprint (&NewSuiteEntry
->UTS
.Fingerprint
[0], Framework
, &NewSuiteEntry
->UTS
);
385 // If everything is going well, add the new suite to the tail list for the framework.
387 if (!EFI_ERROR (Status
)) {
388 InsertTailList (&(Framework
->TestSuiteList
), (LIST_ENTRY
*)NewSuiteEntry
);
389 *SuiteHandle
= (UNIT_TEST_SUITE_HANDLE
)(&NewSuiteEntry
->UTS
);
392 // Otherwise, make with the destruction.
394 FreeUnitTestSuiteEntry (NewSuiteEntry
);
401 Adds test case to Suite
403 @param[in] SuiteHandle Unit test suite to add test to.
404 @param[in] Description Null-terminated ASCII string that is the user
405 friendly description of a test. String is copied.
406 @param[in] Name Null-terminated ASCII string that is the short name
407 of the test with no spaces. String is copied.
408 @param[in] Function Unit test function.
409 @param[in] Prerequisite Prerequisite function, runs before test. This is
410 an optional parameter that may be NULL.
411 @param[in] CleanUp Clean up function, runs after test. This is an
412 optional parameter that may be NULL.
413 @param[in] Context Pointer to context. This is an optional parameter
416 @retval EFI_SUCCESS The unit test case was added to Suite.
417 @retval EFI_INVALID_PARAMETER SuiteHandle is NULL.
418 @retval EFI_INVALID_PARAMETER Description is NULL.
419 @retval EFI_INVALID_PARAMETER Name is NULL.
420 @retval EFI_INVALID_PARAMETER Function is NULL.
421 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
422 add the unit test case to Suite.
427 IN UNIT_TEST_SUITE_HANDLE SuiteHandle
,
428 IN CHAR8
*Description
,
430 IN UNIT_TEST_FUNCTION Function
,
431 IN UNIT_TEST_PREREQUISITE Prerequisite OPTIONAL
,
432 IN UNIT_TEST_CLEANUP CleanUp OPTIONAL
,
433 IN UNIT_TEST_CONTEXT Context OPTIONAL
437 UNIT_TEST_LIST_ENTRY
*NewTestEntry
;
438 UNIT_TEST_FRAMEWORK
*ParentFramework
;
439 UNIT_TEST_SUITE
*Suite
;
441 Status
= EFI_SUCCESS
;
442 Suite
= (UNIT_TEST_SUITE
*)SuiteHandle
;
445 // First, let's check to make sure that our parameters look good.
447 if ((Suite
== NULL
) || (Description
== NULL
) || (Name
== NULL
) || (Function
== NULL
)) {
448 return EFI_INVALID_PARAMETER
;
451 ParentFramework
= (UNIT_TEST_FRAMEWORK
*)Suite
->ParentFramework
;
453 // Create the new entry.
454 NewTestEntry
= AllocateZeroPool (sizeof (UNIT_TEST_LIST_ENTRY
));
455 if (NewTestEntry
== NULL
) {
456 return EFI_OUT_OF_RESOURCES
;
460 // Copy the fields we think we need.
461 NewTestEntry
->UT
.Description
= AllocateAndCopyString (Description
);
462 NewTestEntry
->UT
.Name
= AllocateAndCopyString (Name
);
463 NewTestEntry
->UT
.FailureType
= FAILURETYPE_NOFAILURE
;
464 NewTestEntry
->UT
.FailureMessage
[0] = '\0';
465 NewTestEntry
->UT
.Log
= NULL
;
466 NewTestEntry
->UT
.Prerequisite
= Prerequisite
;
467 NewTestEntry
->UT
.CleanUp
= CleanUp
;
468 NewTestEntry
->UT
.RunTest
= Function
;
469 NewTestEntry
->UT
.Context
= Context
;
470 NewTestEntry
->UT
.Result
= UNIT_TEST_PENDING
;
471 NewTestEntry
->UT
.ParentSuite
= SuiteHandle
;
472 InitializeListHead (&(NewTestEntry
->Entry
)); // List entry for sibling tests.
473 if (NewTestEntry
->UT
.Description
== NULL
) {
474 Status
= EFI_OUT_OF_RESOURCES
;
478 if (NewTestEntry
->UT
.Name
== NULL
) {
479 Status
= EFI_OUT_OF_RESOURCES
;
484 // Create the test fingerprint.
486 SetTestFingerprint (&NewTestEntry
->UT
.Fingerprint
[0], Suite
, &NewTestEntry
->UT
);
488 // TODO: Make sure that duplicate fingerprints cannot be created.
491 // If there is saved test data, update this record.
493 if (ParentFramework
->SavedState
!= NULL
) {
494 UpdateTestFromSave (&NewTestEntry
->UT
, ParentFramework
->SavedState
);
499 // If everything is going well, add the new suite to the tail list for the framework.
501 if (!EFI_ERROR (Status
)) {
502 InsertTailList (&(Suite
->TestCaseList
), (LIST_ENTRY
*)NewTestEntry
);
506 // Otherwise, make with the destruction.
508 FreeUnitTestTestEntry (NewTestEntry
);
517 IN OUT UNIT_TEST
*Test
,
518 IN UNIT_TEST_SAVE_HEADER
*SavedState
521 UNIT_TEST_SAVE_TEST
*CurrentTest
;
522 UNIT_TEST_SAVE_TEST
*MatchingTest
;
523 UINT8
*FloatingPointer
;
524 UNIT_TEST_SAVE_CONTEXT
*SavedContext
;
528 // First, evaluate the inputs.
530 if ((Test
== NULL
) || (SavedState
== NULL
)) {
534 if (SavedState
->TestCount
== 0) {
539 // Next, determine whether a matching test can be found.
540 // Start at the beginning.
543 FloatingPointer
= (UINT8
*)SavedState
+ sizeof (*SavedState
);
544 for (Index
= 0; Index
< SavedState
->TestCount
; Index
++) {
545 CurrentTest
= (UNIT_TEST_SAVE_TEST
*)FloatingPointer
;
546 if (CompareFingerprints (&Test
->Fingerprint
[0], &CurrentTest
->Fingerprint
[0])) {
547 MatchingTest
= CurrentTest
;
549 // If there's a saved context, it's important that we iterate through the entire list.
551 if (!SavedState
->HasSavedContext
) {
557 // If we didn't find it, we have to increment to the next test.
559 FloatingPointer
= (UINT8
*)CurrentTest
+ CurrentTest
->Size
;
563 // If a matching test was found, copy the status.
567 // Override the test status with the saved status.
569 Test
->Result
= MatchingTest
->Result
;
571 Test
->FailureType
= MatchingTest
->FailureType
;
573 &Test
->FailureMessage
[0],
574 UNIT_TEST_TESTFAILUREMSG_LENGTH
,
575 &MatchingTest
->FailureMessage
[0],
576 UNIT_TEST_TESTFAILUREMSG_LENGTH
580 // If there is a log string associated, grab that.
581 // We can tell that there's a log string because the "size" will be larger than
582 // the structure size.
583 // IMPORTANT NOTE: There are security implications here.
584 // This data is user-supplied and we're about to play kinda
585 // fast and loose with data buffers.
587 if (MatchingTest
->Size
> sizeof (UNIT_TEST_SAVE_TEST
)) {
588 UnitTestLogInit (Test
, (UINT8
*)MatchingTest
->Log
, MatchingTest
->Size
- sizeof (UNIT_TEST_SAVE_TEST
));
593 // If the saved context exists and matches this test, grab it, too.
595 if (SavedState
->HasSavedContext
) {
597 // If there was a saved context, the "matching test" loop will have placed the FloatingPointer
598 // at the beginning of the context structure.
600 SavedContext
= (UNIT_TEST_SAVE_CONTEXT
*)FloatingPointer
;
601 if (((SavedContext
->Size
- sizeof (UNIT_TEST_SAVE_CONTEXT
)) > 0) &&
602 CompareFingerprints (&Test
->Fingerprint
[0], &SavedContext
->Fingerprint
[0]))
605 // Override the test context with the saved context.
607 Test
->Context
= (VOID
*)SavedContext
->Data
;
613 UNIT_TEST_SAVE_HEADER
*
615 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
,
616 IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL
,
617 IN UINTN ContextToSaveSize
620 UNIT_TEST_FRAMEWORK
*Framework
;
621 UNIT_TEST_SAVE_HEADER
*Header
;
622 LIST_ENTRY
*SuiteListHead
;
624 LIST_ENTRY
*TestListHead
;
629 UNIT_TEST_SAVE_TEST
*TestSaveData
;
630 UNIT_TEST_SAVE_CONTEXT
*TestSaveContext
;
632 UINT8
*FloatingPointer
;
634 Framework
= (UNIT_TEST_FRAMEWORK
*)FrameworkHandle
;
638 // First, let's not make assumptions about the parameters.
640 if ((Framework
== NULL
) ||
641 ((ContextToSave
!= NULL
) && (ContextToSaveSize
== 0)) ||
642 (ContextToSaveSize
> MAX_UINT32
))
648 // Next, we've gotta figure out the resources that will be required to serialize the
649 // the framework state so that we can persist it.
650 // To start with, we're gonna need a header.
652 TotalSize
= sizeof (UNIT_TEST_SAVE_HEADER
);
654 // Now we need to figure out how many tests there are.
658 // Iterate all suites.
660 SuiteListHead
= &Framework
->TestSuiteList
;
661 for (Suite
= GetFirstNode (SuiteListHead
); Suite
!= SuiteListHead
; Suite
= GetNextNode (SuiteListHead
, Suite
)) {
663 // Iterate all tests within the suite.
665 TestListHead
= &((UNIT_TEST_SUITE_LIST_ENTRY
*)Suite
)->UTS
.TestCaseList
;
666 for (Test
= GetFirstNode (TestListHead
); Test
!= TestListHead
; Test
= GetNextNode (TestListHead
, Test
)) {
667 UnitTest
= &((UNIT_TEST_LIST_ENTRY
*)Test
)->UT
;
669 // Account for the size of a test structure.
671 TotalSize
+= sizeof (UNIT_TEST_SAVE_TEST
);
673 // If there's a log, make sure to account for the log size.
675 if (UnitTest
->Log
!= NULL
) {
677 // The +1 is for the NULL character. Can't forget the NULL character.
679 LogSize
= (AsciiStrLen (UnitTest
->Log
) + 1) * sizeof (CHAR8
);
680 ASSERT (LogSize
< MAX_UINT32
);
681 TotalSize
+= (UINT32
)LogSize
;
685 // Increment the test count.
692 // If there are no tests, we're done here.
694 if (TestCount
== 0) {
699 // Add room for the context, if there is one.
701 if (ContextToSave
!= NULL
) {
702 TotalSize
+= sizeof (UNIT_TEST_SAVE_CONTEXT
) + (UINT32
)ContextToSaveSize
;
706 // Now that we know the size, we need to allocate space for the serialized output.
708 Header
= AllocateZeroPool (TotalSize
);
709 if (Header
== NULL
) {
714 // Alright, let's start setting up some data.
716 Header
->Version
= UNIT_TEST_PERSISTENCE_LIB_VERSION
;
717 Header
->SaveStateSize
= TotalSize
;
718 CopyMem (&Header
->Fingerprint
[0], &Framework
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
719 CopyMem (&Header
->StartTime
, &Framework
->StartTime
, sizeof (EFI_TIME
));
720 Header
->TestCount
= TestCount
;
721 Header
->HasSavedContext
= FALSE
;
724 // Start adding all of the test cases.
725 // Set the floating pointer to the start of the current test save buffer.
727 FloatingPointer
= (UINT8
*)Header
+ sizeof (UNIT_TEST_SAVE_HEADER
);
729 // Iterate all suites.
731 SuiteListHead
= &Framework
->TestSuiteList
;
732 for (Suite
= GetFirstNode (SuiteListHead
); Suite
!= SuiteListHead
; Suite
= GetNextNode (SuiteListHead
, Suite
)) {
734 // Iterate all tests within the suite.
736 TestListHead
= &((UNIT_TEST_SUITE_LIST_ENTRY
*)Suite
)->UTS
.TestCaseList
;
737 for (Test
= GetFirstNode (TestListHead
); Test
!= TestListHead
; Test
= GetNextNode (TestListHead
, Test
)) {
738 TestSaveData
= (UNIT_TEST_SAVE_TEST
*)FloatingPointer
;
739 UnitTest
= &((UNIT_TEST_LIST_ENTRY
*)Test
)->UT
;
742 // Save the fingerprint.
744 CopyMem (&TestSaveData
->Fingerprint
[0], &UnitTest
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
749 TestSaveData
->Result
= UnitTest
->Result
;
750 TestSaveData
->FailureType
= UnitTest
->FailureType
;
751 AsciiStrnCpyS (&TestSaveData
->FailureMessage
[0], UNIT_TEST_TESTFAILUREMSG_LENGTH
, &UnitTest
->FailureMessage
[0], UNIT_TEST_TESTFAILUREMSG_LENGTH
);
754 // If there is a log, save the log.
756 FloatingPointer
+= sizeof (UNIT_TEST_SAVE_TEST
);
757 if (UnitTest
->Log
!= NULL
) {
759 // The +1 is for the NULL character. Can't forget the NULL character.
761 LogSize
= (AsciiStrLen (UnitTest
->Log
) + 1) * sizeof (CHAR8
);
762 CopyMem (FloatingPointer
, UnitTest
->Log
, LogSize
);
763 FloatingPointer
+= LogSize
;
767 // Update the size once the structure is complete.
768 // NOTE: Should this be a straight cast without validation?
770 TestSaveData
->Size
= (UINT32
)(FloatingPointer
- (UINT8
*)TestSaveData
);
775 // If there is a context to save, let's do that now.
777 if ((ContextToSave
!= NULL
) && (Framework
->CurrentTest
!= NULL
)) {
778 TestSaveContext
= (UNIT_TEST_SAVE_CONTEXT
*)FloatingPointer
;
779 TestSaveContext
->Size
= (UINT32
)ContextToSaveSize
+ sizeof (UNIT_TEST_SAVE_CONTEXT
);
780 CopyMem (&TestSaveContext
->Fingerprint
[0], &Framework
->CurrentTest
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
781 CopyMem (((UINT8
*)TestSaveContext
+ sizeof (UNIT_TEST_SAVE_CONTEXT
)), ContextToSave
, ContextToSaveSize
);
782 Header
->HasSavedContext
= TRUE
;
789 Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're
790 a framework author) to save the state of the executing framework along with
791 any allocated data so that the test may be resumed upon reentry. A test case
792 should pass any needed context (which, to prevent an infinite loop, should be
793 at least the current execution count) which will be saved by the framework and
794 passed to the test case upon resume.
796 This should be called while the current test framework is valid and active. It is
797 generally called from within a test case prior to quitting or rebooting.
799 @param[in] ContextToSave A buffer of test case-specific data to be saved
800 along with framework state. Will be passed as
801 "Context" to the test case upon resume. This
802 is an optional parameter that may be NULL.
803 @param[in] ContextToSaveSize Size of the ContextToSave buffer.
805 @retval EFI_SUCCESS The framework state and context were saved.
806 @retval EFI_NOT_FOUND An active framework handle was not found.
807 @retval EFI_INVALID_PARAMETER ContextToSave is not NULL and
808 ContextToSaveSize is 0.
809 @retval EFI_INVALID_PARAMETER ContextToSave is >= 4GB.
810 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
811 save the framework and context state.
812 @retval EFI_DEVICE_ERROR The framework and context state could not be
813 saved to a persistent storage device due to a
819 IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL
,
820 IN UINTN ContextToSaveSize
824 UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
;
825 UNIT_TEST_SAVE_HEADER
*Header
;
828 FrameworkHandle
= GetActiveFrameworkHandle ();
831 // Return a unique error code if the framework is not set.
833 if (FrameworkHandle
== NULL
) {
834 return EFI_NOT_FOUND
;
838 // First, let's not make assumptions about the parameters.
840 if (((ContextToSave
!= NULL
) && (ContextToSaveSize
== 0)) ||
841 (ContextToSaveSize
> MAX_UINT32
))
843 return EFI_INVALID_PARAMETER
;
847 // Now, let's package up all the data for saving.
849 Header
= SerializeState (FrameworkHandle
, ContextToSave
, ContextToSaveSize
);
850 if (Header
== NULL
) {
851 return EFI_OUT_OF_RESOURCES
;
855 // All that should be left to do is save it using the associated persistence lib.
857 Status
= SaveUnitTestCache (FrameworkHandle
, Header
, Header
->SaveStateSize
);
858 if (EFI_ERROR (Status
)) {
859 DEBUG ((DEBUG_ERROR
, "%a - Could not save state! %r\n", __FUNCTION__
, Status
));
860 Status
= EFI_DEVICE_ERROR
;
864 // Free data that was used.