VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/MdePkg/Include/Library/UnitTestLib.h

最後變更 在這個檔案是 101291,由 vboxsync 提交於 16 月 前

EFI/FirmwareNew: Make edk2-stable202308 build on all supported platforms (using gcc at least, msvc not tested yet), bugref:4643
  • 屬性 svn:eol-style 設為 native
檔案大小: 35.2 KB
行 
1/** @file
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.
4
5 Copyright (c) Microsoft Corporation.<BR>
6 Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
8**/
9
10#ifndef __UNIT_TEST_LIB_H__
11#define __UNIT_TEST_LIB_H__
12
13///
14/// Unit Test Status
15///
16typedef 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)
24
25///
26/// Declare PcdUnitTestLogLevel bits and UnitTestLog() ErrorLevel parameter.
27///
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
32
33///
34/// Unit Test Framework Handle
35///
36struct UNIT_TEST_FRAMEWORK_OBJECT;
37typedef struct UNIT_TEST_FRAMEWORK_OBJECT *UNIT_TEST_FRAMEWORK_HANDLE;
38
39///
40/// Unit Test Suite Handle
41///
42struct UNIT_TEST_SUITE_OBJECT;
43typedef struct UNIT_TEST_SUITE_OBJECT *UNIT_TEST_SUITE_HANDLE;
44
45///
46/// Unit Test Handle
47///
48struct UNIT_TEST_OBJECT;
49typedef struct UNIT_TEST_OBJECT *UNIT_TEST_HANDLE;
50
51///
52/// Unit Test Context
53///
54typedef VOID *UNIT_TEST_CONTEXT;
55
56/**
57 The prototype for a single UnitTest case function.
58
59 Functions with this prototype are registered to be dispatched by the
60 UnitTest framework, and results are recorded as test Pass or Fail.
61
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
68 consume it.
69
70 @retval UNIT_TEST_PASSED The Unit test has completed and the test
71 case was successful.
72 @retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed.
73
74**/
75typedef
76UNIT_TEST_STATUS
77(EFIAPI *UNIT_TEST_FUNCTION)(
78 IN UNIT_TEST_CONTEXT Context
79 );
80
81/**
82 Unit-Test Prerequisite Function pointer type.
83
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.
87
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
94 consume it.
95
96 @retval UNIT_TEST_PASSED Unit test case prerequisites
97 are met.
98 @retval UNIT_TEST_ERROR_PREREQUISITE_NOT_MET Test case should be skipped.
99
100**/
101typedef
102UNIT_TEST_STATUS
103(EFIAPI *UNIT_TEST_PREREQUISITE)(
104 IN UNIT_TEST_CONTEXT Context
105 );
106
107/**
108 Unit-Test Cleanup (after) function pointer type.
109
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
114 test data.
115
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
122 consume it.
123
124 @retval UNIT_TEST_PASSED Test case cleanup succeeded.
125 @retval UNIT_TEST_ERROR_CLEANUP_FAILED Test case cleanup failed.
126
127**/
128typedef
129VOID
130(EFIAPI *UNIT_TEST_CLEANUP)(
131 IN UNIT_TEST_CONTEXT Context
132 );
133
134/**
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).
139
140 The purpose of this function is to set up any global state or test data.
141**/
142typedef
143VOID
144(EFIAPI *UNIT_TEST_SUITE_SETUP)(
145 VOID
146 );
147
148/**
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.
153
154 The purpose of this function is to clean up any global state or test data.
155**/
156typedef
157VOID
158(EFIAPI *UNIT_TEST_SUITE_TEARDOWN)(
159 VOID
160 );
161
162/**
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.
166
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
170 copied.
171 @param[in] ShortTitle Null-terminated ASCII short string that is the
172 short name of the framework with no spaces.
173 String is copied.
174 @param[in] VersionString Null-terminated ASCII version string for the
175 framework. String is copied.
176
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.
185**/
186EFI_STATUS
187EFIAPI
188InitUnitTestFramework (
189 OUT UNIT_TEST_FRAMEWORK_HANDLE *FrameworkHandle,
190 IN CHAR8 *Title,
191 IN CHAR8 *ShortTitle,
192 IN CHAR8 *VersionString
193 );
194
195/**
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.
199
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
204 copied.
205 @param[in] Name Null-terminated ASCII string that is the short
206 name of the test suite with no spaces. String
207 is copied.
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.
212
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.
220**/
221EFI_STATUS
222EFIAPI
223CreateUnitTestSuite (
224 OUT UNIT_TEST_SUITE_HANDLE *SuiteHandle,
225 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle,
226 IN CHAR8 *Title,
227 IN CHAR8 *Name,
228 IN UNIT_TEST_SUITE_SETUP Setup OPTIONAL,
229 IN UNIT_TEST_SUITE_TEARDOWN Teardown OPTIONAL
230 );
231
232/**
233 Adds test case to Suite
234
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
246 that may be NULL.
247
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.
255**/
256EFI_STATUS
257EFIAPI
258AddTestCase (
259 IN UNIT_TEST_SUITE_HANDLE SuiteHandle,
260 IN CHAR8 *Description,
261 IN CHAR8 *Name,
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
266 );
267
268/**
269 Execute all unit test cases in all unit test suites added to a Framework.
270
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.
274
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.
278
279 @retval EFI_SUCCESS All test cases were dispatched.
280 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
281**/
282EFI_STATUS
283EFIAPI
284RunAllTestSuites (
285 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
286 );
287
288/**
289 Cleanup a test framework.
290
291 After tests are run, this will teardown the entire framework and free all
292 allocated data within.
293
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.
297
298 @retval EFI_SUCCESS All resources associated with framework were
299 freed.
300 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
301**/
302EFI_STATUS
303EFIAPI
304FreeUnitTestFramework (
305 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
306 );
307
308/**
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.
315
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.
318
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.
324
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
334 device error.
335**/
336EFI_STATUS
337EFIAPI
338SaveFrameworkState (
339 IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL,
340 IN UINTN ContextToSaveSize
341 );
342
343/**
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.
347
348 @param[in] Expression Expression to be evaluated for TRUE.
349**/
350#define UT_ASSERT_TRUE(Expression) \
351 if(!UnitTestAssertTrue ((Expression), __func__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \
352 return UNIT_TEST_ERROR_TEST_FAILED; \
353 }
354
355/**
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.
359
360 @param[in] Expression Expression to be evaluated for FALSE.
361**/
362#define UT_ASSERT_FALSE(Expression) \
363 if(!UnitTestAssertFalse ((Expression), __func__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \
364 return UNIT_TEST_ERROR_TEST_FAILED; \
365 }
366
367/**
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.
371
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).
374**/
375#define UT_ASSERT_EQUAL(ValueA, ValueB) \
376 if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __func__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \
377 return UNIT_TEST_ERROR_TEST_FAILED; \
378 }
379
380/**
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.
384
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.
388**/
389#define UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length) \
390 if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __func__, DEBUG_LINE_NUMBER, __FILE__, #BufferA, #BufferB)) { \
391 return UNIT_TEST_ERROR_TEST_FAILED; \
392 }
393
394/**
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.
398
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).
401**/
402#define UT_ASSERT_NOT_EQUAL(ValueA, ValueB) \
403 if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __func__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \
404 return UNIT_TEST_ERROR_TEST_FAILED; \
405 }
406
407/**
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.
411
412 @param[in] Status EFI_STATUS value to check.
413**/
414#define UT_ASSERT_NOT_EFI_ERROR(Status) \
415 if(!UnitTestAssertNotEfiError ((Status), __func__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \
416 return UNIT_TEST_ERROR_TEST_FAILED; \
417 }
418
419/**
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.
423
424 @param[in] Status EFI_STATUS values to compare for equality.
425 @param[in] Expected EFI_STATUS values to compare for equality.
426**/
427#define UT_ASSERT_STATUS_EQUAL(Status, Expected) \
428 if(!UnitTestAssertStatusEqual ((Status), (Expected), __func__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \
429 return UNIT_TEST_ERROR_TEST_FAILED; \
430 }
431
432/**
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.
436
437 @param[in] Pointer Pointer to be checked against NULL.
438**/
439#define UT_ASSERT_NOT_NULL(Pointer) \
440 if(!UnitTestAssertNotNull ((Pointer), __func__, DEBUG_LINE_NUMBER, __FILE__, #Pointer)) { \
441 return UNIT_TEST_ERROR_TEST_FAILED; \
442 }
443
444/**
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.
451
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.
454
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.
458**/
459#if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED)
460 #include <Library/BaseLib.h>
461
462///
463/// Pointer to jump buffer used with SetJump()/LongJump() to test if a
464/// function under test generates an expected ASSERT() condition.
465///
466extern BASE_LIBRARY_JUMP_BUFFER *gUnitTestExpectAssertFailureJumpBuffer;
467
468#define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) \
469 do { \
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) { \
476 FunctionCall; \
477 UnitTestJumpStatus = UNIT_TEST_ERROR_TEST_FAILED; \
478 } else { \
479 UnitTestJumpStatus = UNIT_TEST_PASSED; \
480 } \
481 gUnitTestExpectAssertFailureJumpBuffer = NULL; \
482 } \
483 if (!UnitTestExpectAssertFailure ( \
484 UnitTestJumpStatus, \
485 __func__, DEBUG_LINE_NUMBER, __FILE__, \
486 #FunctionCall, Status)) { \
487 return UNIT_TEST_ERROR_TEST_FAILED; \
488 } \
489 } while (FALSE)
490#else
491#define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) FunctionCall;
492#endif
493
494/**
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.
499
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
507 evaluated.
508
509 @retval TRUE Expression is TRUE.
510 @retval FALSE Expression is FALSE.
511**/
512BOOLEAN
513EFIAPI
514UnitTestAssertTrue (
515 IN BOOLEAN Expression,
516 IN CONST CHAR8 *FunctionName,
517 IN UINTN LineNumber,
518 IN CONST CHAR8 *FileName,
519 IN CONST CHAR8 *Description
520 );
521
522/**
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.
527
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
535 evaluated.
536
537 @retval TRUE Expression is FALSE.
538 @retval FALSE Expression is TRUE.
539**/
540BOOLEAN
541EFIAPI
542UnitTestAssertFalse (
543 IN BOOLEAN Expression,
544 IN CONST CHAR8 *FunctionName,
545 IN UINTN LineNumber,
546 IN CONST CHAR8 *FileName,
547 IN CONST CHAR8 *Description
548 );
549
550/**
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.
555
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.
564
565 @retval TRUE Status is not an EFI_ERROR().
566 @retval FALSE Status is an EFI_ERROR().
567**/
568BOOLEAN
569EFIAPI
570UnitTestAssertNotEfiError (
571 IN EFI_STATUS Status,
572 IN CONST CHAR8 *FunctionName,
573 IN UINTN LineNumber,
574 IN CONST CHAR8 *FileName,
575 IN CONST CHAR8 *Description
576 );
577
578/**
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.
583
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
592 of ValueA.
593 @param[in] DescriptionB Null-terminated ASCII string that is a description
594 of ValueB.
595
596 @retval TRUE ValueA is equal to ValueB.
597 @retval FALSE ValueA is not equal to ValueB.
598**/
599BOOLEAN
600EFIAPI
601UnitTestAssertEqual (
602 IN UINT64 ValueA,
603 IN UINT64 ValueB,
604 IN CONST CHAR8 *FunctionName,
605 IN UINTN LineNumber,
606 IN CONST CHAR8 *FileName,
607 IN CONST CHAR8 *DescriptionA,
608 IN CONST CHAR8 *DescriptionB
609 );
610
611/**
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.
617
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
627 of BufferA.
628 @param[in] DescriptionB Null-terminated ASCII string that is a description
629 of BufferB.
630
631 @retval TRUE The contents of BufferA are identical to the contents of
632 BufferB.
633 @retval FALSE The contents of BufferA are not identical to the contents of
634 BufferB.
635**/
636BOOLEAN
637EFIAPI
638UnitTestAssertMemEqual (
639 IN VOID *BufferA,
640 IN VOID *BufferB,
641 IN UINTN Length,
642 IN CONST CHAR8 *FunctionName,
643 IN UINTN LineNumber,
644 IN CONST CHAR8 *FileName,
645 IN CONST CHAR8 *DescriptionA,
646 IN CONST CHAR8 *DescriptionB
647 );
648
649/**
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.
654
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
663 of ValueA.
664 @param[in] DescriptionB Null-terminated ASCII string that is a description
665 of ValueB.
666
667 @retval TRUE ValueA is not equal to ValueB.
668 @retval FALSE ValueA is equal to ValueB.
669**/
670BOOLEAN
671EFIAPI
672UnitTestAssertNotEqual (
673 IN UINT64 ValueA,
674 IN UINT64 ValueB,
675 IN CONST CHAR8 *FunctionName,
676 IN UINTN LineNumber,
677 IN CONST CHAR8 *FileName,
678 IN CONST CHAR8 *DescriptionA,
679 IN CONST CHAR8 *DescriptionB
680 );
681
682/**
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.
687
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
690 under test.
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
697 of Status.
698
699 @retval TRUE Status is equal to Expected.
700 @retval FALSE Status is not equal to Expected.
701**/
702BOOLEAN
703EFIAPI
704UnitTestAssertStatusEqual (
705 IN EFI_STATUS Status,
706 IN EFI_STATUS Expected,
707 IN CONST CHAR8 *FunctionName,
708 IN UINTN LineNumber,
709 IN CONST CHAR8 *FileName,
710 IN CONST CHAR8 *Description
711 );
712
713/**
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.
718
719 @param[in] Pointer Pointer value to be checked against NULL.
720 @param[in] Expected The expected EFI_STATUS return value from a function
721 under test.
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
728 of Pointer.
729
730 @retval TRUE Pointer is not equal to NULL.
731 @retval FALSE Pointer is equal to NULL.
732**/
733BOOLEAN
734EFIAPI
735UnitTestAssertNotNull (
736 IN VOID *Pointer,
737 IN CONST CHAR8 *FunctionName,
738 IN UINTN LineNumber,
739 IN CONST CHAR8 *FileName,
740 IN CONST CHAR8 *PointerName
741 );
742
743/**
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.
753
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.
767
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.
771**/
772BOOLEAN
773EFIAPI
774UnitTestExpectAssertFailure (
775 IN UNIT_TEST_STATUS UnitTestStatus,
776 IN CONST CHAR8 *FunctionName,
777 IN UINTN LineNumber,
778 IN CONST CHAR8 *FileName,
779 IN CONST CHAR8 *FunctionCall,
780 OUT UNIT_TEST_STATUS *ResultStatus OPTIONAL
781 );
782
783/**
784 Test logging macro that records an ERROR message in the test framework log.
785 Record is associated with the currently executing test case.
786
787 @param[in] Format Formatting string following the format defined in
788 MdePkg/Include/Library/PrintLib.h.
789 @param[in] ... Print args.
790**/
791#define UT_LOG_ERROR(Format, ...) \
792 UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__)
793
794/**
795 Test logging macro that records a WARNING message in the test framework log.
796 Record is associated with the currently executing test case.
797
798 @param[in] Format Formatting string following the format defined in
799 MdePkg/Include/Library/PrintLib.h.
800 @param[in] ... Print args.
801**/
802#define UT_LOG_WARNING(Format, ...) \
803 UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, Format, ##__VA_ARGS__)
804
805/**
806 Test logging macro that records an INFO message in the test framework log.
807 Record is associated with the currently executing test case.
808
809 @param[in] Format Formatting string following the format defined in
810 MdePkg/Include/Library/PrintLib.h.
811 @param[in] ... Print args.
812**/
813#define UT_LOG_INFO(Format, ...) \
814 UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, Format, ##__VA_ARGS__)
815
816/**
817 Test logging macro that records a VERBOSE message in the test framework log.
818 Record is associated with the currently executing test case.
819
820 @param[in] Format Formatting string following the format defined in
821 MdePkg/Include/Library/PrintLib.h.
822 @param[in] ... Print args.
823**/
824#define UT_LOG_VERBOSE(Format, ...) \
825 UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, Format, ##__VA_ARGS__)
826
827/**
828 Test logging function that records a messages in the test framework log.
829 Record is associated with the currently executing test case.
830
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.
835**/
836VOID
837EFIAPI
838UnitTestLog (
839 IN UINTN ErrorLevel,
840 IN CONST CHAR8 *Format,
841 ...
842 );
843
844#endif
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette