UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTest.c

   1 /** @file
   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.
   4
   5   Copyright (c) Microsoft Corporation.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9 #include <PiPei.h>
  10 #include <Uefi.h>
  11 #include <Library/UefiLib.h>
  12 #include <Library/DebugLib.h>
  13 #include <Library/UnitTestLib.h>
  14 #include <Library/PrintLib.h>
  15
  16 #define UNIT_TEST_NAME     "Sample Unit Test"
  17 #define UNIT_TEST_VERSION  "0.1"
  18
  19 ///
  20 /// Global variables used in unit tests
  21 ///
  22 BOOLEAN  mSampleGlobalTestBoolean  = FALSE;
  23 VOID     *mSampleGlobalTestPointer = NULL;
  24
  25 /**
  26   Sample Unit-Test Prerequisite Function that checks to make sure the global
  27   pointer used in the test is already set to NULL.
  28
  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.
  32
  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
  39                          consume it.
  40
  41   @retval  UNIT_TEST_PASSED                      Unit test case prerequisites
  42                                                  are met.
  43   @retval  UNIT_TEST_ERROR_PREREQUISITE_NOT_MET  Test case should be skipped.
  44
  45 **/
  46 UNIT_TEST_STATUS
  47 EFIAPI
  48 MakeSureThatPointerIsNull (
  49   IN UNIT_TEST_CONTEXT  Context
  50   )
  51 {
  52   UT_ASSERT_EQUAL ((UINTN)mSampleGlobalTestPointer, (UINTN)NULL);
  53   return UNIT_TEST_PASSED;
  54 }
  55
  56 /**
  57   Sample Unit-Test Cleanup (after) function that resets the global pointer to
  58   NULL.
  59
  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
  64   test data.
  65
  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
  72                          consume it.
  73
  74   @retval  UNIT_TEST_PASSED                Test case cleanup succeeded.
  75   @retval  UNIT_TEST_ERROR_CLEANUP_FAILED  Test case cleanup failed.
  76
  77 **/
  78 VOID
  79 EFIAPI
  80 ClearThePointer (
  81   IN UNIT_TEST_CONTEXT  Context
  82   )
  83 {
  84   mSampleGlobalTestPointer = NULL;
  85 }
  86
  87 /**
  88   Sample unit test that verifies the expected result of an unsigned integer
  89   addition operation.
  90
  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
  97                          consume it.
  98
  99   @retval  UNIT_TEST_PASSED             The Unit test has completed and the test
 100                                         case was successful.
 101   @retval  UNIT_TEST_ERROR_TEST_FAILED  A test case assertion has failed.
 102 **/
 103 UNIT_TEST_STATUS
 104 EFIAPI
 105 OnePlusOneShouldEqualTwo (
 106   IN UNIT_TEST_CONTEXT  Context
 107   )
 108 {
 109   UINTN  A;
 110   UINTN  B;
 111   UINTN  C;
 112
 113   A = 1;
 114   B = 1;
 115   C = A + B;
 116
 117   UT_ASSERT_EQUAL (C, 2);
 118
 119   return UNIT_TEST_PASSED;
 120 }
 121
 122 /**
 123   Sample unit test that verifies that a global BOOLEAN is updatable.
 124
 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
 131                          consume it.
 132
 133   @retval  UNIT_TEST_PASSED             The Unit test has completed and the test
 134                                         case was successful.
 135   @retval  UNIT_TEST_ERROR_TEST_FAILED  A test case assertion has failed.
 136 **/
 137 UNIT_TEST_STATUS
 138 EFIAPI
 139 GlobalBooleanShouldBeChangeable (
 140   IN UNIT_TEST_CONTEXT  Context
 141   )
 142 {
 143   mSampleGlobalTestBoolean = TRUE;
 144   UT_ASSERT_TRUE (mSampleGlobalTestBoolean);
 145
 146   mSampleGlobalTestBoolean = FALSE;
 147   UT_ASSERT_FALSE (mSampleGlobalTestBoolean);
 148
 149   return UNIT_TEST_PASSED;
 150 }
 151
 152 /**
 153   Sample unit test that logs a warning message and verifies that a global
 154   pointer is updatable.
 155
 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
 162                          consume it.
 163
 164   @retval  UNIT_TEST_PASSED             The Unit test has completed and the test
 165                                         case was successful.
 166   @retval  UNIT_TEST_ERROR_TEST_FAILED  A test case assertion has failed.
 167 **/
 168 UNIT_TEST_STATUS
 169 EFIAPI
 170 GlobalPointerShouldBeChangeable (
 171   IN UNIT_TEST_CONTEXT  Context
 172   )
 173 {
 174   //
 175   // Example of logging.
 176   //
 177   UT_LOG_WARNING ("About to change a global pointer! Current value is 0x%X\n", mSampleGlobalTestPointer);
 178
 179   mSampleGlobalTestPointer = (VOID *)-1;
 180   UT_ASSERT_EQUAL ((UINTN)mSampleGlobalTestPointer, (UINTN)((VOID *)-1));
 181   return UNIT_TEST_PASSED;
 182 }
 183
 184 /**
 185   Initialize the unit test framework, suite, and unit tests for the
 186   sample unit tests and run the unit tests.
 187
 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.
 191 **/
 192 EFI_STATUS
 193 EFIAPI
 194 UefiTestMain (
 195   VOID
 196   )
 197 {
 198   EFI_STATUS                  Status;
 199   UNIT_TEST_FRAMEWORK_HANDLE  Framework;
 200   UNIT_TEST_SUITE_HANDLE      SimpleMathTests;
 201   UNIT_TEST_SUITE_HANDLE      GlobalVarTests;
 202
 203   Framework = NULL;
 204
 205   DEBUG(( DEBUG_INFO, "%a v%a\n", UNIT_TEST_NAME, UNIT_TEST_VERSION ));
 206
 207   //
 208   // Start setting up the test framework for running the tests.
 209   //
 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));
 213     goto EXIT;
 214   }
 215
 216   //
 217   // Populate the SimpleMathTests Unit Test Suite.
 218   //
 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;
 223     goto EXIT;
 224   }
 225   AddTestCase (SimpleMathTests, "Adding 1 to 1 should produce 2", "Addition", OnePlusOneShouldEqualTwo, NULL, NULL, NULL);
 226
 227   //
 228   // Populate the GlobalVarTests Unit Test Suite.
 229   //
 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;
 234     goto EXIT;
 235   }
 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);
 238
 239   //
 240   // Execute the tests.
 241   //
 242   Status = RunAllTestSuites (Framework);
 243
 244 EXIT:
 245   if (Framework) {
 246     FreeUnitTestFramework (Framework);
 247   }
 248
 249   return Status;
 250 }
 251
 252 /**
 253   Standard PEIM entry point for target based unit test execution from PEI.
 254 **/
 255 EFI_STATUS
 256 EFIAPI
 257 PeiEntryPoint (
 258   IN EFI_PEI_FILE_HANDLE     FileHandle,
 259   IN CONST EFI_PEI_SERVICES  **PeiServices
 260   )
 261 {
 262   return UefiTestMain ();
 263 }
 264
 265 /**
 266   Standard UEFI entry point for target based unit test execution from DXE, SMM,
 267   UEFI Shell.
 268 **/
 269 EFI_STATUS
 270 EFIAPI
 271 DxeEntryPoint (
 272   IN EFI_HANDLE        ImageHandle,
 273   IN EFI_SYSTEM_TABLE  *SystemTable
 274   )
 275 {
 276   return UefiTestMain ();
 277 }
 278
 279 /**
 280   Standard POSIX C entry point for host based unit test execution.
 281 **/
 282 int
 283 main (
 284   int argc,
 285   char *argv[]
 286   )
 287 {
 288   return UefiTestMain ();
 289 }