UnitTestFrameworkPkg/Test: Add unit test samples

https://bugzilla.tianocore.org/show_bug.cgi?id=2505

Add an implementation of a sample unit test that
demonstrates the use of the UnitTestLib services and
macros and supports being built for execution in a
host environment or for execution on a target in PEI,
DXE, SMM, or UEFI Shell.

Cc: Sean Brogan <sean.brogan@microsoft.com>
Cc: Bret Barkelew <Bret.Barkelew@microsoft.com>
Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com>
Reviewed-by: Bret Barkelew <Bret.Barkelew@microsoft.com>

diff --git a/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTest.c b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTest.c
new file mode 100644 (file)
index 0000000..37d5747
--- /dev/null
+++ b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTest.c
@@ -0,0 +1,289 @@
+/** @file\r
+  This is a sample to demostrate the usage of the Unit Test Library that\r
+  supports the PEI, DXE, SMM, UEFI SHell, and host execution environments.\r
+\r
+  Copyright (c) Microsoft Corporation.<BR>\r
+  SPDX-License-Identifier: BSD-2-Clause-Patent\r
+\r
+**/\r
+#include <PiPei.h>\r
+#include <Uefi.h>\r
+#include <Library/UefiLib.h>\r
+#include <Library/DebugLib.h>\r
+#include <Library/UnitTestLib.h>\r
+#include <Library/PrintLib.h>\r
+\r
+#define UNIT_TEST_NAME     "Sample Unit Test"\r
+#define UNIT_TEST_VERSION  "0.1"\r
+\r
+///\r
+/// Global variables used in unit tests\r
+///\r
+BOOLEAN  mSampleGlobalTestBoolean  = FALSE;\r
+VOID     *mSampleGlobalTestPointer = NULL;\r
+\r
+/**\r
+  Sample Unit-Test Prerequisite Function that checks to make sure the global\r
+  pointer used in the test is already set to NULL.\r
+\r
+  Functions with this prototype are registered to be dispatched by the unit test\r
+  framework prior to a given test case. If this prereq function returns\r
+  UNIT_TEST_ERROR_PREREQUISITE_NOT_MET, the test case will be skipped.\r
+\r
+  @param[in]  Context    [Optional] An optional parameter that enables:\r
+                         1) test-case reuse with varied parameters and\r
+                         2) test-case re-entry for Target tests that need a\r
+                         reboot.  This parameter is a VOID* and it is the\r
+                         responsibility of the test author to ensure that the\r
+                         contents are well understood by all test cases that may\r
+                         consume it.\r
+\r
+  @retval  UNIT_TEST_PASSED                      Unit test case prerequisites\r
+                                                 are met.\r
+  @retval  UNIT_TEST_ERROR_PREREQUISITE_NOT_MET  Test case should be skipped.\r
+\r
+**/\r
+UNIT_TEST_STATUS\r
+EFIAPI\r
+MakeSureThatPointerIsNull (\r
+  IN UNIT_TEST_CONTEXT  Context\r
+  )\r
+{\r
+  UT_ASSERT_EQUAL ((UINTN)mSampleGlobalTestPointer, (UINTN)NULL);\r
+  return UNIT_TEST_PASSED;\r
+}\r
+\r
+/**\r
+  Sample Unit-Test Cleanup (after) function that resets the global pointer to\r
+  NULL.\r
+\r
+  Functions with this prototype are registered to be dispatched by the\r
+  unit test framework after a given test case. This will be called even if the\r
+  test case returns an error, but not if the prerequisite fails and the test is\r
+  skipped.  The purpose of this function is to clean up any global state or\r
+  test data.\r
+\r
+  @param[in]  Context    [Optional] An optional parameter that enables:\r
+                         1) test-case reuse with varied parameters and\r
+                         2) test-case re-entry for Target tests that need a\r
+                         reboot.  This parameter is a VOID* and it is the\r
+                         responsibility of the test author to ensure that the\r
+                         contents are well understood by all test cases that may\r
+                         consume it.\r
+\r
+  @retval  UNIT_TEST_PASSED                Test case cleanup succeeded.\r
+  @retval  UNIT_TEST_ERROR_CLEANUP_FAILED  Test case cleanup failed.\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+ClearThePointer (\r
+  IN UNIT_TEST_CONTEXT  Context\r
+  )\r
+{\r
+  mSampleGlobalTestPointer = NULL;\r
+}\r
+\r
+/**\r
+  Sample unit test that verifies the expected result of an unsigned integer\r
+  addition operation.\r
+\r
+  @param[in]  Context    [Optional] An optional parameter that enables:\r
+                         1) test-case reuse with varied parameters and\r
+                         2) test-case re-entry for Target tests that need a\r
+                         reboot.  This parameter is a VOID* and it is the\r
+                         responsibility of the test author to ensure that the\r
+                         contents are well understood by all test cases that may\r
+                         consume it.\r
+\r
+  @retval  UNIT_TEST_PASSED             The Unit test has completed and the test\r
+                                        case was successful.\r
+  @retval  UNIT_TEST_ERROR_TEST_FAILED  A test case assertion has failed.\r
+**/\r
+UNIT_TEST_STATUS\r
+EFIAPI\r
+OnePlusOneShouldEqualTwo (\r
+  IN UNIT_TEST_CONTEXT  Context\r
+  )\r
+{\r
+  UINTN  A;\r
+  UINTN  B;\r
+  UINTN  C;\r
+\r
+  A = 1;\r
+  B = 1;\r
+  C = A + B;\r
+\r
+  UT_ASSERT_EQUAL (C, 2);\r
+\r
+  return UNIT_TEST_PASSED;\r
+}\r
+\r
+/**\r
+  Sample unit test that verifies that a global BOOLEAN is updatable.\r
+\r
+  @param[in]  Context    [Optional] An optional parameter that enables:\r
+                         1) test-case reuse with varied parameters and\r
+                         2) test-case re-entry for Target tests that need a\r
+                         reboot.  This parameter is a VOID* and it is the\r
+                         responsibility of the test author to ensure that the\r
+                         contents are well understood by all test cases that may\r
+                         consume it.\r
+\r
+  @retval  UNIT_TEST_PASSED             The Unit test has completed and the test\r
+                                        case was successful.\r
+  @retval  UNIT_TEST_ERROR_TEST_FAILED  A test case assertion has failed.\r
+**/\r
+UNIT_TEST_STATUS\r
+EFIAPI\r
+GlobalBooleanShouldBeChangeable (\r
+  IN UNIT_TEST_CONTEXT  Context\r
+  )\r
+{\r
+  mSampleGlobalTestBoolean = TRUE;\r
+  UT_ASSERT_TRUE (mSampleGlobalTestBoolean);\r
+\r
+  mSampleGlobalTestBoolean = FALSE;\r
+  UT_ASSERT_FALSE (mSampleGlobalTestBoolean);\r
+\r
+  return UNIT_TEST_PASSED;\r
+}\r
+\r
+/**\r
+  Sample unit test that logs a warning message and verifies that a global\r
+  pointer is updatable.\r
+\r
+  @param[in]  Context    [Optional] An optional parameter that enables:\r
+                         1) test-case reuse with varied parameters and\r
+                         2) test-case re-entry for Target tests that need a\r
+                         reboot.  This parameter is a VOID* and it is the\r
+                         responsibility of the test author to ensure that the\r
+                         contents are well understood by all test cases that may\r
+                         consume it.\r
+\r
+  @retval  UNIT_TEST_PASSED             The Unit test has completed and the test\r
+                                        case was successful.\r
+  @retval  UNIT_TEST_ERROR_TEST_FAILED  A test case assertion has failed.\r
+**/\r
+UNIT_TEST_STATUS\r
+EFIAPI\r
+GlobalPointerShouldBeChangeable (\r
+  IN UNIT_TEST_CONTEXT  Context\r
+  )\r
+{\r
+  //\r
+  // Example of logging.\r
+  //\r
+  UT_LOG_WARNING ("About to change a global pointer! Current value is 0x%X\n", mSampleGlobalTestPointer);\r
+\r
+  mSampleGlobalTestPointer = (VOID *)-1;\r
+  UT_ASSERT_EQUAL ((UINTN)mSampleGlobalTestPointer, (UINTN)((VOID *)-1));\r
+  return UNIT_TEST_PASSED;\r
+}\r
+\r
+/**\r
+  Initialize the unit test framework, suite, and unit tests for the\r
+  sample unit tests and run the unit tests.\r
+\r
+  @retval  EFI_SUCCESS           All test cases were dispatched.\r
+  @retval  EFI_OUT_OF_RESOURCES  There are not enough resources available to\r
+                                 initialize the unit tests.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+UefiTestMain (\r
+  VOID\r
+  )\r
+{\r
+  EFI_STATUS                  Status;\r
+  UNIT_TEST_FRAMEWORK_HANDLE  Framework;\r
+  UNIT_TEST_SUITE_HANDLE      SimpleMathTests;\r
+  UNIT_TEST_SUITE_HANDLE      GlobalVarTests;\r
+\r
+  Framework = NULL;\r
+\r
+  DEBUG(( DEBUG_INFO, "%a v%a\n", UNIT_TEST_NAME, UNIT_TEST_VERSION ));\r
+\r
+  //\r
+  // Start setting up the test framework for running the tests.\r
+  //\r
+  Status = InitUnitTestFramework (&Framework, UNIT_TEST_NAME, gEfiCallerBaseName, UNIT_TEST_VERSION);\r
+  if (EFI_ERROR (Status)) {\r
+    DEBUG((DEBUG_ERROR, "Failed in InitUnitTestFramework. Status = %r\n", Status));\r
+    goto EXIT;\r
+  }\r
+\r
+  //\r
+  // Populate the SimpleMathTests Unit Test Suite.\r
+  //\r
+  Status = CreateUnitTestSuite (&SimpleMathTests, Framework, "Simple Math Tests", "Sample.Math", NULL, NULL);\r
+  if (EFI_ERROR (Status)) {\r
+    DEBUG ((DEBUG_ERROR, "Failed in CreateUnitTestSuite for SimpleMathTests\n"));\r
+    Status = EFI_OUT_OF_RESOURCES;\r
+    goto EXIT;\r
+  }\r
+  AddTestCase (SimpleMathTests, "Adding 1 to 1 should produce 2", "Addition", OnePlusOneShouldEqualTwo, NULL, NULL, NULL);\r
+\r
+  //\r
+  // Populate the GlobalVarTests Unit Test Suite.\r
+  //\r
+  Status = CreateUnitTestSuite (&GlobalVarTests, Framework, "Global Variable Tests", "Sample.Globals", NULL, NULL);\r
+  if (EFI_ERROR (Status)) {\r
+    DEBUG ((DEBUG_ERROR, "Failed in CreateUnitTestSuite for GlobalVarTests\n"));\r
+    Status = EFI_OUT_OF_RESOURCES;\r
+    goto EXIT;\r
+  }\r
+  AddTestCase (GlobalVarTests, "You should be able to change a global BOOLEAN", "Boolean", GlobalBooleanShouldBeChangeable, NULL, NULL, NULL);\r
+  AddTestCase (GlobalVarTests, "You should be able to change a global pointer", "Pointer", GlobalPointerShouldBeChangeable, MakeSureThatPointerIsNull, ClearThePointer, NULL);\r
+\r
+  //\r
+  // Execute the tests.\r
+  //\r
+  Status = RunAllTestSuites (Framework);\r
+\r
+EXIT:\r
+  if (Framework) {\r
+    FreeUnitTestFramework (Framework);\r
+  }\r
+\r
+  return Status;\r
+}\r
+\r
+/**\r
+  Standard PEIM entry point for target based unit test execution from PEI.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+PeiEntryPoint (\r
+  IN EFI_PEI_FILE_HANDLE     FileHandle,\r
+  IN CONST EFI_PEI_SERVICES  **PeiServices\r
+  )\r
+{\r
+  return UefiTestMain ();\r
+}\r
+\r
+/**\r
+  Standard UEFI entry point for target based unit test execution from DXE, SMM,\r
+  UEFI Shell.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+DxeEntryPoint (\r
+  IN EFI_HANDLE        ImageHandle,\r
+  IN EFI_SYSTEM_TABLE  *SystemTable\r
+  )\r
+{\r
+  return UefiTestMain ();\r
+}\r
+\r
+/**\r
+  Standard POSIX C entry point for host based unit test execution.\r
+**/\r
+int\r
+main (\r
+  int argc,\r
+  char *argv[]\r
+  )\r
+{\r
+  return UefiTestMain ();\r
+}\r

diff --git a/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestDxe.inf b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestDxe.inf
new file mode 100644 (file)
index 0000000..e253cf6
--- /dev/null
+++ b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestDxe.inf
@@ -0,0 +1,36 @@
+## @file\r
+# Sample UnitTest built for execution in DXE.\r
+#\r
+# Copyright (c) Microsoft Corporation.<BR>\r
+# SPDX-License-Identifier: BSD-2-Clause-Patent\r
+##\r
+\r
+[Defines]\r
+  INF_VERSION    = 0x00010006\r
+  BASE_NAME      = SampleUnitTestDxe\r
+  FILE_GUID      = 96BB18BD-FF2B-4B51-B683-0DC9A4BF12CF\r
+  MODULE_TYPE    = DXE_DRIVER\r
+  VERSION_STRING = 1.0\r
+  ENTRY_POINT    = DxeEntryPoint\r
+\r
+#\r
+# The following information is for reference only and not required by the build tools.\r
+#\r
+#  VALID_ARCHITECTURES           = IA32 X64\r
+#\r
+\r
+[Sources]\r
+  SampleUnitTest.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+\r
+[LibraryClasses]\r
+  UefiDriverEntryPoint\r
+  BaseLib\r
+  DebugLib\r
+  UnitTestLib\r
+  PrintLib\r
+\r
+[Depex]\r
+  TRUE\r

diff --git a/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestHost.inf b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestHost.inf
new file mode 100644 (file)
index 0000000..59a367c
--- /dev/null
+++ b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestHost.inf
@@ -0,0 +1,30 @@
+## @file\r
+# Sample UnitTest built for execution on a Host/Dev machine.\r
+#\r
+# Copyright (c) Microsoft Corporation.<BR>\r
+# SPDX-License-Identifier: BSD-2-Clause-Patent\r
+##\r
+\r
+[Defines]\r
+  INF_VERSION    = 0x00010005\r
+  BASE_NAME      = SampleUnitTestHost\r
+  FILE_GUID      = CC0EA77E-BF2D-4134-B419-0C02E15CE08E\r
+  MODULE_TYPE    = HOST_APPLICATION\r
+  VERSION_STRING = 1.0\r
+\r
+#\r
+# The following information is for reference only and not required by the build tools.\r
+#\r
+#  VALID_ARCHITECTURES           = IA32 X64\r
+#\r
+\r
+[Sources]\r
+  SampleUnitTest.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+\r
+[LibraryClasses]\r
+  BaseLib\r
+  DebugLib\r
+  UnitTestLib\r

diff --git a/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestPei.inf b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestPei.inf
new file mode 100644 (file)
index 0000000..60f5252
--- /dev/null
+++ b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestPei.inf
@@ -0,0 +1,36 @@
+## @file\r
+# Sample UnitTest built for execution in PEI.\r
+#\r
+# Copyright (c) Microsoft Corporation.<BR>\r
+# SPDX-License-Identifier: BSD-2-Clause-Patent\r
+##\r
+\r
+[Defines]\r
+  INF_VERSION    = 0x00010006\r
+  BASE_NAME      = SampleUnitTestPei\r
+  FILE_GUID      = B9BD9451-3DC8-48EA-A6F0-55753BF186F1\r
+  MODULE_TYPE    = PEIM\r
+  VERSION_STRING = 1.0\r
+  ENTRY_POINT    = PeiEntryPoint\r
+\r
+#\r
+# The following information is for reference only and not required by the build tools.\r
+#\r
+#  VALID_ARCHITECTURES           = IA32 X64\r
+#\r
+\r
+[Sources]\r
+  SampleUnitTest.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+\r
+[LibraryClasses]\r
+  PeimEntryPoint\r
+  BaseLib\r
+  DebugLib\r
+  UnitTestLib\r
+  PrintLib\r
+\r
+[Depex]\r
+  gEfiPeiMemoryDiscoveredPpiGuid\r

diff --git a/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestSmm.inf b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestSmm.inf
new file mode 100644 (file)
index 0000000..324ad26
--- /dev/null
+++ b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestSmm.inf
@@ -0,0 +1,37 @@
+## @file\r
+# Sample UnitTest built for execution in SMM.\r
+#\r
+# Copyright (c) Microsoft Corporation.<BR>\r
+# SPDX-License-Identifier: BSD-2-Clause-Patent\r
+##\r
+\r
+[Defines]\r
+  INF_VERSION              = 0x00010006\r
+  BASE_NAME                = SampleUnitTestSmm\r
+  FILE_GUID                = 389B16DB-F622-424C-9000-9E43C69CBF71\r
+  MODULE_TYPE              = DXE_SMM_DRIVER\r
+  VERSION_STRING           = 1.0\r
+  PI_SPECIFICATION_VERSION = 0x0001000A\r
+  ENTRY_POINT              = DxeEntryPoint\r
+\r
+#\r
+# The following information is for reference only and not required by the build tools.\r
+#\r
+#  VALID_ARCHITECTURES           = IA32 X64\r
+#\r
+\r
+[Sources]\r
+  SampleUnitTest.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+\r
+[LibraryClasses]\r
+  UefiDriverEntryPoint\r
+  BaseLib\r
+  DebugLib\r
+  UnitTestLib\r
+  PrintLib\r
+\r
+[Depex]\r
+  gEfiSmmCpuProtocolGuid\r

diff --git a/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestUefiShell.inf b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestUefiShell.inf
new file mode 100644 (file)
index 0000000..6e39c22
--- /dev/null
+++ b/UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestUefiShell.inf
@@ -0,0 +1,33 @@
+## @file\r
+# Sample UnitTest built for execution in UEFI Shell.\r
+#\r
+# Copyright (c) Microsoft Corporation.<BR>\r
+# SPDX-License-Identifier: BSD-2-Clause-Patent\r
+##\r
+\r
+[Defines]\r
+  INF_VERSION    = 0x00010006\r
+  BASE_NAME      = SampleUnitTestUefiShell\r
+  FILE_GUID      = 9E8F461A-17E1-4312-B49C-E66F0A88EA8B\r
+  MODULE_TYPE    = UEFI_APPLICATION\r
+  VERSION_STRING = 1.0\r
+  ENTRY_POINT    = DxeEntryPoint\r
+\r
+#\r
+# The following information is for reference only and not required by the build tools.\r
+#\r
+#  VALID_ARCHITECTURES           = IA32 X64\r
+#\r
+\r
+[Sources]\r
+  SampleUnitTest.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+\r
+[LibraryClasses]\r
+  UefiApplicationEntryPoint\r
+  BaseLib\r
+  DebugLib\r
+  UnitTestLib\r
+  PrintLib\r