4 Copyright (c) Microsoft Corporation.
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #include <Library/UnitTestLib.h>
10 #include <Library/BaseLib.h>
11 #include <Library/BaseMemoryLib.h>
12 #include <Library/MemoryAllocationLib.h>
13 #include <Library/DebugLib.h>
14 #include <Library/UnitTestPersistenceLib.h>
15 #include <Library/UnitTestResultReportLib.h>
18 /// Forward declaration of prototype
23 IN OUT UNIT_TEST
*Test
,
24 IN UNIT_TEST_SAVE_HEADER
*SavedState
28 This function will determine whether the short name violates any rules that would
29 prevent it from being used as a reporting name or as a serialization name.
31 Example: If the name cannot be serialized to a filesystem file name.
33 @param[in] ShortTitleString A pointer to the short title string to be evaluated.
35 @retval TRUE The string is acceptable.
36 @retval FALSE The string should not be used.
41 IsFrameworkShortNameValid (
42 IN CHAR8
*ShortTitleString
45 // TODO: Finish this function.
51 AllocateAndCopyString (
52 IN CHAR8
*StringToCopy
56 UINTN NewStringLength
;
59 NewStringLength
= AsciiStrnLenS (StringToCopy
, UNIT_TEST_MAX_STRING_LENGTH
) + 1;
60 NewString
= AllocatePool (NewStringLength
* sizeof( CHAR8
));
61 if (NewString
!= NULL
) {
62 AsciiStrCpyS (NewString
, NewStringLength
, StringToCopy
);
69 SetFrameworkFingerprint (
70 OUT UINT8
*Fingerprint
,
71 IN UNIT_TEST_FRAMEWORK
*Framework
74 UINT32 NewFingerprint
;
76 // For this one we'll just use the title and version as the unique fingerprint.
77 NewFingerprint
= CalculateCrc32( Framework
->Title
, (AsciiStrLen( Framework
->Title
) * sizeof( CHAR8
)) );
78 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32( Framework
->VersionString
, (AsciiStrLen( Framework
->VersionString
) * sizeof( CHAR8
)) );
80 CopyMem( Fingerprint
, &NewFingerprint
, UNIT_TEST_FINGERPRINT_SIZE
);
87 OUT UINT8
*Fingerprint
,
88 IN UNIT_TEST_FRAMEWORK
*Framework
,
89 IN UNIT_TEST_SUITE
*Suite
92 UINT32 NewFingerprint
;
94 // For this one, we'll use the fingerprint from the framework, and the title of the suite.
95 NewFingerprint
= CalculateCrc32( &Framework
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
96 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32( Suite
->Title
, (AsciiStrLen( Suite
->Title
) * sizeof( CHAR8
)) );
97 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32( Suite
->Name
, (AsciiStrLen(Suite
->Name
) * sizeof(CHAR8
)) );
99 CopyMem( Fingerprint
, &NewFingerprint
, UNIT_TEST_FINGERPRINT_SIZE
);
106 OUT UINT8
*Fingerprint
,
107 IN UNIT_TEST_SUITE
*Suite
,
111 UINT32 NewFingerprint
;
113 // For this one, we'll use the fingerprint from the suite, and the description and classname of the test.
114 NewFingerprint
= CalculateCrc32( &Suite
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
115 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32( Test
->Description
, (AsciiStrLen( Test
->Description
) * sizeof( CHAR8
)) );
116 NewFingerprint
= (NewFingerprint
>> 8) ^ CalculateCrc32( Test
->Name
, (AsciiStrLen(Test
->Name
) * sizeof(CHAR8
)) );
118 CopyMem( Fingerprint
, &NewFingerprint
, UNIT_TEST_FINGERPRINT_SIZE
);
124 CompareFingerprints (
125 IN UINT8
*FingerprintA
,
126 IN UINT8
*FingerprintB
129 return (CompareMem( FingerprintA
, FingerprintB
, UNIT_TEST_FINGERPRINT_SIZE
) == 0);
133 Cleanup a test framework.
135 After tests are run, this will teardown the entire framework and free all
136 allocated data within.
138 @param[in] FrameworkHandle A handle to the current running framework that
139 dispatched the test. Necessary for recording
140 certain test events with the framework.
142 @retval EFI_SUCCESS All resources associated with framework were
144 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
148 FreeUnitTestFramework (
149 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
152 // TODO: Finish this function.
158 FreeUnitTestSuiteEntry (
159 IN UNIT_TEST_SUITE_LIST_ENTRY
*SuiteEntry
162 // TODO: Finish this function.
168 FreeUnitTestTestEntry (
169 IN UNIT_TEST_LIST_ENTRY
*TestEntry
172 // TODO: Finish this function.
177 Method to Initialize the Unit Test framework. This function registers the
178 test name and also initializes the internal state of the test framework to
179 receive any new suites and tests.
181 @param[out] FrameworkHandle Unit test framework to be created.
182 @param[in] Title Null-terminated ASCII string that is the user
183 friendly name of the framework. String is
185 @param[in] ShortTitle Null-terminated ASCII short string that is the
186 short name of the framework with no spaces.
188 @param[in] VersionString Null-terminated ASCII version string for the
189 framework. String is copied.
191 @retval EFI_SUCCESS The unit test framework was initialized.
192 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
193 @retval EFI_INVALID_PARAMETER Title is NULL.
194 @retval EFI_INVALID_PARAMETER ShortTitle is NULL.
195 @retval EFI_INVALID_PARAMETER VersionString is NULL.
196 @retval EFI_INVALID_PARAMETER ShortTitle is invalid.
197 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
198 initialize the unit test framework.
202 InitUnitTestFramework (
203 OUT UNIT_TEST_FRAMEWORK_HANDLE
*FrameworkHandle
,
205 IN CHAR8
*ShortTitle
,
206 IN CHAR8
*VersionString
210 UNIT_TEST_FRAMEWORK_HANDLE NewFrameworkHandle
;
211 UNIT_TEST_FRAMEWORK
*NewFramework
;
212 UNIT_TEST_SAVE_HEADER
*SavedState
;
214 Status
= EFI_SUCCESS
;
218 // First, check all pointers and make sure nothing's broked.
220 if (FrameworkHandle
== NULL
|| Title
== NULL
||
221 ShortTitle
== NULL
|| VersionString
== NULL
) {
222 return EFI_INVALID_PARAMETER
;
226 // Next, determine whether all of the strings are good to use.
228 if (!IsFrameworkShortNameValid (ShortTitle
)) {
229 return EFI_INVALID_PARAMETER
;
233 // Next, set aside some space to start messing with the framework.
235 NewFramework
= AllocateZeroPool (sizeof (UNIT_TEST_FRAMEWORK
));
236 if (NewFramework
== NULL
) {
237 return EFI_OUT_OF_RESOURCES
;
241 // Next, set up all the test data.
243 NewFrameworkHandle
= (UNIT_TEST_FRAMEWORK_HANDLE
)NewFramework
;
244 NewFramework
->Title
= AllocateAndCopyString (Title
);
245 NewFramework
->ShortTitle
= AllocateAndCopyString (ShortTitle
);
246 NewFramework
->VersionString
= AllocateAndCopyString (VersionString
);
247 NewFramework
->Log
= NULL
;
248 NewFramework
->CurrentTest
= NULL
;
249 NewFramework
->SavedState
= NULL
;
250 if (NewFramework
->Title
== NULL
||
251 NewFramework
->ShortTitle
== NULL
||
252 NewFramework
->VersionString
== NULL
) {
253 Status
= EFI_OUT_OF_RESOURCES
;
256 InitializeListHead (&(NewFramework
->TestSuiteList
));
259 // Create the framework fingerprint.
261 SetFrameworkFingerprint (&NewFramework
->Fingerprint
[0], NewFramework
);
264 // If there is a persisted context, load it now.
266 if (DoesCacheExist (NewFrameworkHandle
)) {
267 SavedState
= (UNIT_TEST_SAVE_HEADER
*)NewFramework
->SavedState
;
268 Status
= LoadUnitTestCache (NewFrameworkHandle
, &SavedState
);
269 if (EFI_ERROR (Status
)) {
271 // Don't actually report it as an error, but emit a warning.
273 DEBUG (( DEBUG_ERROR
, "%a - Cache was detected, but failed to load.\n", __FUNCTION__
));
274 Status
= EFI_SUCCESS
;
280 // If we're good, then let's copy the framework.
282 if (!EFI_ERROR (Status
)) {
283 *FrameworkHandle
= NewFrameworkHandle
;
286 // Otherwise, we need to undo this horrible thing that we've done.
288 FreeUnitTestFramework (NewFrameworkHandle
);
295 Registers a Unit Test Suite in the Unit Test Framework.
296 At least one test suite must be registered, because all test cases must be
297 within a unit test suite.
299 @param[out] SuiteHandle Unit test suite to create
300 @param[in] FrameworkHandle Unit test framework to add unit test suite to
301 @param[in] Title Null-terminated ASCII string that is the user
302 friendly name of the test suite. String is
304 @param[in] Name Null-terminated ASCII string that is the short
305 name of the test suite with no spaces. String
307 @param[in] Setup Setup function, runs before suite. This is an
308 optional parameter that may be NULL.
309 @param[in] Teardown Teardown function, runs after suite. This is an
310 optional parameter that may be NULL.
312 @retval EFI_SUCCESS The unit test suite was created.
313 @retval EFI_INVALID_PARAMETER SuiteHandle is NULL.
314 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
315 @retval EFI_INVALID_PARAMETER Title is NULL.
316 @retval EFI_INVALID_PARAMETER Name is NULL.
317 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
318 initialize the unit test suite.
322 CreateUnitTestSuite (
323 OUT UNIT_TEST_SUITE_HANDLE
*SuiteHandle
,
324 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
,
327 IN UNIT_TEST_SUITE_SETUP Setup OPTIONAL
,
328 IN UNIT_TEST_SUITE_TEARDOWN Teardown OPTIONAL
332 UNIT_TEST_SUITE_LIST_ENTRY
*NewSuiteEntry
;
333 UNIT_TEST_FRAMEWORK
*Framework
;
335 Status
= EFI_SUCCESS
;
336 Framework
= (UNIT_TEST_FRAMEWORK
*)FrameworkHandle
;
339 // First, let's check to make sure that our parameters look good.
341 if ((SuiteHandle
== NULL
) || (Framework
== NULL
) || (Title
== NULL
) || (Name
== NULL
)) {
342 return EFI_INVALID_PARAMETER
;
346 // Create the new entry.
348 NewSuiteEntry
= AllocateZeroPool (sizeof (UNIT_TEST_SUITE_LIST_ENTRY
));
349 if (NewSuiteEntry
== NULL
) {
350 return EFI_OUT_OF_RESOURCES
;
354 // Copy the fields we think we need.
356 NewSuiteEntry
->UTS
.NumTests
= 0;
357 NewSuiteEntry
->UTS
.Title
= AllocateAndCopyString (Title
);
358 NewSuiteEntry
->UTS
.Name
= AllocateAndCopyString (Name
);
359 NewSuiteEntry
->UTS
.Setup
= Setup
;
360 NewSuiteEntry
->UTS
.Teardown
= Teardown
;
361 NewSuiteEntry
->UTS
.ParentFramework
= FrameworkHandle
;
362 InitializeListHead (&(NewSuiteEntry
->Entry
)); // List entry for sibling suites.
363 InitializeListHead (&(NewSuiteEntry
->UTS
.TestCaseList
)); // List entry for child tests.
364 if (NewSuiteEntry
->UTS
.Title
== NULL
) {
365 Status
= EFI_OUT_OF_RESOURCES
;
369 if (NewSuiteEntry
->UTS
.Name
== NULL
) {
370 Status
= EFI_OUT_OF_RESOURCES
;
375 // Create the suite fingerprint.
377 SetSuiteFingerprint( &NewSuiteEntry
->UTS
.Fingerprint
[0], Framework
, &NewSuiteEntry
->UTS
);
381 // If everything is going well, add the new suite to the tail list for the framework.
383 if (!EFI_ERROR( Status
)) {
384 InsertTailList (&(Framework
->TestSuiteList
), (LIST_ENTRY
*)NewSuiteEntry
);
385 *SuiteHandle
= (UNIT_TEST_SUITE_HANDLE
)(&NewSuiteEntry
->UTS
);
388 // Otherwise, make with the destruction.
390 FreeUnitTestSuiteEntry (NewSuiteEntry
);
397 Adds test case to Suite
399 @param[in] SuiteHandle Unit test suite to add test to.
400 @param[in] Description Null-terminated ASCII string that is the user
401 friendly description of a test. String is copied.
402 @param[in] Name Null-terminated ASCII string that is the short name
403 of the test with no spaces. String is copied.
404 @param[in] Function Unit test function.
405 @param[in] Prerequisite Prerequisite function, runs before test. This is
406 an optional parameter that may be NULL.
407 @param[in] CleanUp Clean up function, runs after test. This is an
408 optional parameter that may be NULL.
409 @param[in] Context Pointer to context. This is an optional parameter
412 @retval EFI_SUCCESS The unit test case was added to Suite.
413 @retval EFI_INVALID_PARAMETER SuiteHandle is NULL.
414 @retval EFI_INVALID_PARAMETER Description is NULL.
415 @retval EFI_INVALID_PARAMETER Name is NULL.
416 @retval EFI_INVALID_PARAMETER Function is NULL.
417 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
418 add the unit test case to Suite.
423 IN UNIT_TEST_SUITE_HANDLE SuiteHandle
,
424 IN CHAR8
*Description
,
426 IN UNIT_TEST_FUNCTION Function
,
427 IN UNIT_TEST_PREREQUISITE Prerequisite OPTIONAL
,
428 IN UNIT_TEST_CLEANUP CleanUp OPTIONAL
,
429 IN UNIT_TEST_CONTEXT Context OPTIONAL
433 UNIT_TEST_LIST_ENTRY
*NewTestEntry
;
434 UNIT_TEST_FRAMEWORK
*ParentFramework
;
435 UNIT_TEST_SUITE
*Suite
;
437 Status
= EFI_SUCCESS
;
438 Suite
= (UNIT_TEST_SUITE
*)SuiteHandle
;
439 ParentFramework
= (UNIT_TEST_FRAMEWORK
*)Suite
->ParentFramework
;
442 // First, let's check to make sure that our parameters look good.
444 if ((Suite
== NULL
) || (Description
== NULL
) || (Name
== NULL
) || (Function
== NULL
)) {
445 return EFI_INVALID_PARAMETER
;
449 // Create the new entry.
450 NewTestEntry
= AllocateZeroPool (sizeof( UNIT_TEST_LIST_ENTRY
));
451 if (NewTestEntry
== NULL
) {
452 return EFI_OUT_OF_RESOURCES
;
456 // Copy the fields we think we need.
457 NewTestEntry
->UT
.Description
= AllocateAndCopyString (Description
);
458 NewTestEntry
->UT
.Name
= AllocateAndCopyString (Name
);
459 NewTestEntry
->UT
.FailureType
= FAILURETYPE_NOFAILURE
;
460 NewTestEntry
->UT
.FailureMessage
[0] = '\0';
461 NewTestEntry
->UT
.Log
= NULL
;
462 NewTestEntry
->UT
.Prerequisite
= Prerequisite
;
463 NewTestEntry
->UT
.CleanUp
= CleanUp
;
464 NewTestEntry
->UT
.RunTest
= Function
;
465 NewTestEntry
->UT
.Context
= Context
;
466 NewTestEntry
->UT
.Result
= UNIT_TEST_PENDING
;
467 NewTestEntry
->UT
.ParentSuite
= SuiteHandle
;
468 InitializeListHead (&(NewTestEntry
->Entry
)); // List entry for sibling tests.
469 if (NewTestEntry
->UT
.Description
== NULL
) {
470 Status
= EFI_OUT_OF_RESOURCES
;
473 if (NewTestEntry
->UT
.Name
== NULL
) {
474 Status
= EFI_OUT_OF_RESOURCES
;
479 // Create the test fingerprint.
481 SetTestFingerprint (&NewTestEntry
->UT
.Fingerprint
[0], Suite
, &NewTestEntry
->UT
);
483 // TODO: Make sure that duplicate fingerprints cannot be created.
486 // If there is saved test data, update this record.
488 if (ParentFramework
->SavedState
!= NULL
) {
489 UpdateTestFromSave (&NewTestEntry
->UT
, ParentFramework
->SavedState
);
494 // If everything is going well, add the new suite to the tail list for the framework.
496 if (!EFI_ERROR (Status
)) {
497 InsertTailList (&(Suite
->TestCaseList
), (LIST_ENTRY
*)NewTestEntry
);
501 // Otherwise, make with the destruction.
503 FreeUnitTestTestEntry (NewTestEntry
);
512 IN OUT UNIT_TEST
*Test
,
513 IN UNIT_TEST_SAVE_HEADER
*SavedState
516 UNIT_TEST_SAVE_TEST
*CurrentTest
;
517 UNIT_TEST_SAVE_TEST
*MatchingTest
;
518 UINT8
*FloatingPointer
;
519 UNIT_TEST_SAVE_CONTEXT
*SavedContext
;
523 // First, evaluate the inputs.
525 if (Test
== NULL
|| SavedState
== NULL
) {
528 if (SavedState
->TestCount
== 0) {
533 // Next, determine whether a matching test can be found.
534 // Start at the beginning.
537 FloatingPointer
= (UINT8
*)SavedState
+ sizeof (*SavedState
);
538 for (Index
= 0; Index
< SavedState
->TestCount
; Index
++) {
539 CurrentTest
= (UNIT_TEST_SAVE_TEST
*)FloatingPointer
;
540 if (CompareFingerprints (&Test
->Fingerprint
[0], &CurrentTest
->Fingerprint
[0])) {
541 MatchingTest
= CurrentTest
;
543 // If there's a saved context, it's important that we iterate through the entire list.
545 if (!SavedState
->HasSavedContext
) {
551 // If we didn't find it, we have to increment to the next test.
553 FloatingPointer
= (UINT8
*)CurrentTest
+ CurrentTest
->Size
;
557 // If a matching test was found, copy the status.
561 // Override the test status with the saved status.
563 Test
->Result
= MatchingTest
->Result
;
565 Test
->FailureType
= MatchingTest
->FailureType
;
567 &Test
->FailureMessage
[0],
568 UNIT_TEST_TESTFAILUREMSG_LENGTH
,
569 &MatchingTest
->FailureMessage
[0],
570 UNIT_TEST_TESTFAILUREMSG_LENGTH
574 // If there is a log string associated, grab that.
575 // We can tell that there's a log string because the "size" will be larger than
576 // the structure size.
577 // IMPORTANT NOTE: There are security implications here.
578 // This data is user-supplied and we're about to play kinda
579 // fast and loose with data buffers.
581 if (MatchingTest
->Size
> sizeof (UNIT_TEST_SAVE_TEST
)) {
582 UnitTestLogInit (Test
, (UINT8
*)MatchingTest
->Log
, MatchingTest
->Size
- sizeof (UNIT_TEST_SAVE_TEST
));
587 // If the saved context exists and matches this test, grab it, too.
589 if (SavedState
->HasSavedContext
) {
591 // If there was a saved context, the "matching test" loop will have placed the FloatingPointer
592 // at the beginning of the context structure.
594 SavedContext
= (UNIT_TEST_SAVE_CONTEXT
*)FloatingPointer
;
595 if ((SavedContext
->Size
- sizeof (UNIT_TEST_SAVE_CONTEXT
)) > 0 &&
596 CompareFingerprints (&Test
->Fingerprint
[0], &SavedContext
->Fingerprint
[0])) {
598 // Override the test context with the saved context.
600 Test
->Context
= (VOID
*)SavedContext
->Data
;
606 UNIT_TEST_SAVE_HEADER
*
608 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
,
609 IN UNIT_TEST_CONTEXT ContextToSave
, OPTIONAL
610 IN UINTN ContextToSaveSize
613 UNIT_TEST_FRAMEWORK
*Framework
;
614 UNIT_TEST_SAVE_HEADER
*Header
;
615 LIST_ENTRY
*SuiteListHead
;
617 LIST_ENTRY
*TestListHead
;
622 UNIT_TEST_SAVE_TEST
*TestSaveData
;
623 UNIT_TEST_SAVE_CONTEXT
*TestSaveContext
;
625 UINT8
*FloatingPointer
;
627 Framework
= (UNIT_TEST_FRAMEWORK
*)FrameworkHandle
;
631 // First, let's not make assumptions about the parameters.
633 if (Framework
== NULL
||
634 (ContextToSave
!= NULL
&& ContextToSaveSize
== 0) ||
635 ContextToSaveSize
> MAX_UINT32
) {
640 // Next, we've gotta figure out the resources that will be required to serialize the
641 // the framework state so that we can persist it.
642 // To start with, we're gonna need a header.
644 TotalSize
= sizeof (UNIT_TEST_SAVE_HEADER
);
646 // Now we need to figure out how many tests there are.
650 // Iterate all suites.
652 SuiteListHead
= &Framework
->TestSuiteList
;
653 for (Suite
= GetFirstNode (SuiteListHead
); Suite
!= SuiteListHead
; Suite
= GetNextNode (SuiteListHead
, Suite
)) {
655 // Iterate all tests within the suite.
657 TestListHead
= &((UNIT_TEST_SUITE_LIST_ENTRY
*)Suite
)->UTS
.TestCaseList
;
658 for (Test
= GetFirstNode (TestListHead
); Test
!= TestListHead
; Test
= GetNextNode (TestListHead
, Test
)) {
659 UnitTest
= &((UNIT_TEST_LIST_ENTRY
*)Test
)->UT
;
661 // Account for the size of a test structure.
663 TotalSize
+= sizeof( UNIT_TEST_SAVE_TEST
);
665 // If there's a log, make sure to account for the log size.
667 if (UnitTest
->Log
!= NULL
) {
669 // The +1 is for the NULL character. Can't forget the NULL character.
671 LogSize
= (AsciiStrLen (UnitTest
->Log
) + 1) * sizeof (CHAR8
);
672 ASSERT (LogSize
< MAX_UINT32
);
673 TotalSize
+= (UINT32
)LogSize
;
676 // Increment the test count.
682 // If there are no tests, we're done here.
684 if (TestCount
== 0) {
688 // Add room for the context, if there is one.
690 if (ContextToSave
!= NULL
) {
691 TotalSize
+= sizeof (UNIT_TEST_SAVE_CONTEXT
) + (UINT32
)ContextToSaveSize
;
695 // Now that we know the size, we need to allocate space for the serialized output.
697 Header
= AllocateZeroPool (TotalSize
);
698 if (Header
== NULL
) {
703 // Alright, let's start setting up some data.
705 Header
->Version
= UNIT_TEST_PERSISTENCE_LIB_VERSION
;
706 Header
->SaveStateSize
= TotalSize
;
707 CopyMem (&Header
->Fingerprint
[0], &Framework
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
708 CopyMem (&Header
->StartTime
, &Framework
->StartTime
, sizeof (EFI_TIME
));
709 Header
->TestCount
= TestCount
;
710 Header
->HasSavedContext
= FALSE
;
713 // Start adding all of the test cases.
714 // Set the floating pointer to the start of the current test save buffer.
716 FloatingPointer
= (UINT8
*)Header
+ sizeof( UNIT_TEST_SAVE_HEADER
);
718 // Iterate all suites.
720 SuiteListHead
= &Framework
->TestSuiteList
;
721 for (Suite
= GetFirstNode (SuiteListHead
); Suite
!= SuiteListHead
; Suite
= GetNextNode (SuiteListHead
, Suite
)) {
723 // Iterate all tests within the suite.
725 TestListHead
= &((UNIT_TEST_SUITE_LIST_ENTRY
*)Suite
)->UTS
.TestCaseList
;
726 for (Test
= GetFirstNode (TestListHead
); Test
!= TestListHead
; Test
= GetNextNode (TestListHead
, Test
)) {
727 TestSaveData
= (UNIT_TEST_SAVE_TEST
*)FloatingPointer
;
728 UnitTest
= &((UNIT_TEST_LIST_ENTRY
*)Test
)->UT
;
731 // Save the fingerprint.
733 CopyMem (&TestSaveData
->Fingerprint
[0], &UnitTest
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
738 TestSaveData
->Result
= UnitTest
->Result
;
739 TestSaveData
->FailureType
= UnitTest
->FailureType
;
740 AsciiStrnCpyS (&TestSaveData
->FailureMessage
[0], UNIT_TEST_TESTFAILUREMSG_LENGTH
, &UnitTest
->FailureMessage
[0], UNIT_TEST_TESTFAILUREMSG_LENGTH
);
744 // If there is a log, save the log.
746 FloatingPointer
+= sizeof (UNIT_TEST_SAVE_TEST
);
747 if (UnitTest
->Log
!= NULL
) {
749 // The +1 is for the NULL character. Can't forget the NULL character.
751 LogSize
= (AsciiStrLen (UnitTest
->Log
) + 1) * sizeof (CHAR8
);
752 CopyMem (FloatingPointer
, UnitTest
->Log
, LogSize
);
753 FloatingPointer
+= LogSize
;
757 // Update the size once the structure is complete.
758 // NOTE: Should this be a straight cast without validation?
760 TestSaveData
->Size
= (UINT32
)(FloatingPointer
- (UINT8
*)TestSaveData
);
765 // If there is a context to save, let's do that now.
767 if (ContextToSave
!= NULL
&& Framework
->CurrentTest
!= NULL
) {
768 TestSaveContext
= (UNIT_TEST_SAVE_CONTEXT
*)FloatingPointer
;
769 TestSaveContext
->Size
= (UINT32
)ContextToSaveSize
+ sizeof (UNIT_TEST_SAVE_CONTEXT
);
770 CopyMem (&TestSaveContext
->Fingerprint
[0], &Framework
->CurrentTest
->Fingerprint
[0], UNIT_TEST_FINGERPRINT_SIZE
);
771 CopyMem (((UINT8
*)TestSaveContext
+ sizeof (UNIT_TEST_SAVE_CONTEXT
)), ContextToSave
, ContextToSaveSize
);
772 Header
->HasSavedContext
= TRUE
;
779 Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're
780 a framework author) to save the state of the executing framework along with
781 any allocated data so that the test may be resumed upon reentry. A test case
782 should pass any needed context (which, to prevent an infinite loop, should be
783 at least the current execution count) which will be saved by the framework and
784 passed to the test case upon resume.
786 Generally called from within a test case prior to quitting or rebooting.
788 @param[in] FrameworkHandle A handle to the current running framework that
789 dispatched the test. Necessary for recording
790 certain test events with the framework.
791 @param[in] ContextToSave A buffer of test case-specific data to be saved
792 along with framework state. Will be passed as
793 "Context" to the test case upon resume. This
794 is an optional parameter that may be NULL.
795 @param[in] ContextToSaveSize Size of the ContextToSave buffer.
797 @retval EFI_SUCCESS The framework state and context were saved.
798 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
799 @retval EFI_INVALID_PARAMETER ContextToSave is not NULL and
800 ContextToSaveSize is 0.
801 @retval EFI_INVALID_PARAMETER ContextToSave is >= 4GB.
802 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to
803 save the framework and context state.
804 @retval EFI_DEVICE_ERROR The framework and context state could not be
805 saved to a persistent storage device due to a
811 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
,
812 IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL
,
813 IN UINTN ContextToSaveSize
817 UNIT_TEST_SAVE_HEADER
*Header
;
822 // First, let's not make assumptions about the parameters.
824 if (FrameworkHandle
== NULL
||
825 (ContextToSave
!= NULL
&& ContextToSaveSize
== 0) ||
826 ContextToSaveSize
> MAX_UINT32
) {
827 return EFI_INVALID_PARAMETER
;
831 // Now, let's package up all the data for saving.
833 Header
= SerializeState (FrameworkHandle
, ContextToSave
, ContextToSaveSize
);
834 if (Header
== NULL
) {
835 return EFI_OUT_OF_RESOURCES
;
839 // All that should be left to do is save it using the associated persistence lib.
841 Status
= SaveUnitTestCache (FrameworkHandle
, Header
);
842 if (EFI_ERROR (Status
)) {
843 DEBUG ((DEBUG_ERROR
, "%a - Could not save state! %r\n", __FUNCTION__
, Status
));
844 Status
= EFI_DEVICE_ERROR
;
848 // Free data that was used.