UnitTestFrameworkPkg/Library/UnitTestLib/AssertCmocka.c

   1 /** @file
   2   Implement UnitTestLib assert services using cmocka services
   3
   4   Copyright (c) 2019 - 2020, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6 **/
   7
   8 #include <stdio.h>
   9 #include <string.h>
  10 #include <stdarg.h>
  11 #include <stddef.h>
  12 #include <setjmp.h>
  13 #include <cmocka.h>
  14
  15 #include <Uefi.h>
  16 #include <Library/BaseMemoryLib.h>
  17 #include <Library/UnitTestLib.h>
  18
  19 #define MAX_STRING_SIZE  1025
  20
  21 /**
  22   If Expression is TRUE, then TRUE is returned.
  23   If Expression is FALSE, then an assert is triggered and the location of the
  24   assert provided by FunctionName, LineNumber, FileName, and Description are
  25   recorded and FALSE is returned.
  26
  27   @param[in]  Expression    The BOOLEAN result of the expression evaluation.
  28   @param[in]  FunctionName  Null-terminated ASCII string of the function
  29                             executing the assert macro.
  30   @param[in]  LineNumber    The source file line number of the assert macro.
  31   @param[in]  FileName      Null-terminated ASCII string of the filename
  32                             executing the assert macro.
  33   @param[in]  Description   Null-terminated ASCII string of the expression being
  34                             evaluated.
  35
  36   @retval  TRUE   Expression is TRUE.
  37   @retval  FALSE  Expression is FALSE.
  38 **/
  39 BOOLEAN
  40 EFIAPI
  41 UnitTestAssertTrue (
  42   IN BOOLEAN      Expression,
  43   IN CONST CHAR8  *FunctionName,
  44   IN UINTN        LineNumber,
  45   IN CONST CHAR8  *FileName,
  46   IN CONST CHAR8  *Description
  47   )
  48 {
  49   CHAR8  TempStr[MAX_STRING_SIZE];
  50
  51   snprintf (TempStr, sizeof (TempStr), "UT_ASSERT_TRUE(%s:%x)", Description, Expression);
  52   _assert_true (Expression, TempStr, FileName, (INT32)LineNumber);
  53
  54   return Expression;
  55 }
  56
  57 /**
  58   If Expression is FALSE, then TRUE is returned.
  59   If Expression is TRUE, then an assert is triggered and the location of the
  60   assert provided by FunctionName, LineNumber, FileName, and Description are
  61   recorded and FALSE is returned.
  62
  63   @param[in]  Expression    The BOOLEAN result of the expression evaluation.
  64   @param[in]  FunctionName  Null-terminated ASCII string of the function
  65                             executing the assert macro.
  66   @param[in]  LineNumber    The source file line number of the assert macro.
  67   @param[in]  FileName      Null-terminated ASCII string of the filename
  68                             executing the assert macro.
  69   @param[in]  Description   Null-terminated ASCII string of the expression being
  70                             evaluated.
  71
  72   @retval  TRUE   Expression is FALSE.
  73   @retval  FALSE  Expression is TRUE.
  74 **/
  75 BOOLEAN
  76 EFIAPI
  77 UnitTestAssertFalse (
  78   IN BOOLEAN      Expression,
  79   IN CONST CHAR8  *FunctionName,
  80   IN UINTN        LineNumber,
  81   IN CONST CHAR8  *FileName,
  82   IN CONST CHAR8  *Description
  83   )
  84 {
  85   CHAR8  TempStr[MAX_STRING_SIZE];
  86
  87   snprintf (TempStr, sizeof (TempStr), "UT_ASSERT_FALSE(%s:%x)", Description, Expression);
  88   _assert_true (!Expression, TempStr, FileName, (INT32)LineNumber);
  89
  90   return !Expression;
  91 }
  92
  93 /**
  94   If Status is not an EFI_ERROR(), then TRUE is returned.
  95   If Status is an EFI_ERROR(), then an assert is triggered and the location of
  96   the assert provided by FunctionName, LineNumber, FileName, and Description are
  97   recorded and FALSE is returned.
  98
  99   @param[in]  Status        The EFI_STATUS value to evaluate.
 100   @param[in]  FunctionName  Null-terminated ASCII string of the function
 101                             executing the assert macro.
 102   @param[in]  LineNumber    The source file line number of the assert macro.
 103   @param[in]  FileName      Null-terminated ASCII string of the filename
 104                             executing the assert macro.
 105   @param[in]  Description   Null-terminated ASCII string of the status
 106                             expression being evaluated.
 107
 108   @retval  TRUE   Status is not an EFI_ERROR().
 109   @retval  FALSE  Status is an EFI_ERROR().
 110 **/
 111 BOOLEAN
 112 EFIAPI
 113 UnitTestAssertNotEfiError (
 114   IN EFI_STATUS   Status,
 115   IN CONST CHAR8  *FunctionName,
 116   IN UINTN        LineNumber,
 117   IN CONST CHAR8  *FileName,
 118   IN CONST CHAR8  *Description
 119   )
 120 {
 121   CHAR8  TempStr[MAX_STRING_SIZE];
 122
 123   snprintf (TempStr, sizeof (TempStr), "UT_ASSERT_NOT_EFI_ERROR(%s:%p)", Description, (void *)Status);
 124   _assert_true (!EFI_ERROR (Status), TempStr, FileName, (INT32)LineNumber);
 125
 126   return !EFI_ERROR (Status);
 127 }
 128
 129 /**
 130   If ValueA is equal ValueB, then TRUE is returned.
 131   If ValueA is not equal to ValueB, then an assert is triggered and the location
 132   of the assert provided by FunctionName, LineNumber, FileName, DescriptionA,
 133   and DescriptionB are recorded and FALSE is returned.
 134
 135   @param[in]  ValueA        64-bit value.
 136   @param[in]  ValueB        64-bit value.
 137   @param[in]  FunctionName  Null-terminated ASCII string of the function
 138                             executing the assert macro.
 139   @param[in]  LineNumber    The source file line number of the assert macro.
 140   @param[in]  FileName      Null-terminated ASCII string of the filename
 141                             executing the assert macro.
 142   @param[in]  DescriptionA  Null-terminated ASCII string that is a description
 143                             of ValueA.
 144   @param[in]  DescriptionB  Null-terminated ASCII string that is a description
 145                             of ValueB.
 146
 147   @retval  TRUE   ValueA is equal to ValueB.
 148   @retval  FALSE  ValueA is not equal to ValueB.
 149 **/
 150 BOOLEAN
 151 EFIAPI
 152 UnitTestAssertEqual (
 153   IN UINT64       ValueA,
 154   IN UINT64       ValueB,
 155   IN CONST CHAR8  *FunctionName,
 156   IN UINTN        LineNumber,
 157   IN CONST CHAR8  *FileName,
 158   IN CONST CHAR8  *DescriptionA,
 159   IN CONST CHAR8  *DescriptionB
 160   )
 161 {
 162   CHAR8  TempStr[MAX_STRING_SIZE];
 163
 164   snprintf (TempStr, sizeof (TempStr), "UT_ASSERT_EQUAL(%s:%llx, %s:%llx)", DescriptionA, ValueA, DescriptionB, ValueB);
 165   _assert_true ((ValueA == ValueB), TempStr, FileName, (INT32)LineNumber);
 166
 167   return (ValueA == ValueB);
 168 }
 169
 170 /**
 171   If the contents of BufferA are identical to the contents of BufferB, then TRUE
 172   is returned.  If the contents of BufferA are not identical to the contents of
 173   BufferB, then an assert is triggered and the location of the assert provided
 174   by FunctionName, LineNumber, FileName, DescriptionA, and DescriptionB are
 175   recorded and FALSE is returned.
 176
 177   @param[in]  BufferA       Pointer to a buffer for comparison.
 178   @param[in]  BufferB       Pointer to a buffer for comparison.
 179   @param[in]  Length        Number of bytes to compare in BufferA and BufferB.
 180   @param[in]  FunctionName  Null-terminated ASCII string of the function
 181                             executing the assert macro.
 182   @param[in]  LineNumber    The source file line number of the assert macro.
 183   @param[in]  FileName      Null-terminated ASCII string of the filename
 184                             executing the assert macro.
 185   @param[in]  DescriptionA  Null-terminated ASCII string that is a description
 186                             of BufferA.
 187   @param[in]  DescriptionB  Null-terminated ASCII string that is a description
 188                             of BufferB.
 189
 190   @retval  TRUE   The contents of BufferA are identical to the contents of
 191                   BufferB.
 192   @retval  FALSE  The contents of BufferA are not identical to the contents of
 193                   BufferB.
 194 **/
 195 BOOLEAN
 196 EFIAPI
 197 UnitTestAssertMemEqual (
 198   IN VOID         *BufferA,
 199   IN VOID         *BufferB,
 200   IN UINTN        Length,
 201   IN CONST CHAR8  *FunctionName,
 202   IN UINTN        LineNumber,
 203   IN CONST CHAR8  *FileName,
 204   IN CONST CHAR8  *DescriptionA,
 205   IN CONST CHAR8  *DescriptionB
 206   )
 207 {
 208   CHAR8    TempStr[MAX_STRING_SIZE];
 209   BOOLEAN  Result;
 210
 211   Result = (CompareMem (BufferA, BufferB, Length) == 0);
 212
 213   snprintf (TempStr, sizeof (TempStr), "UT_ASSERT_MEM_EQUAL(%s:%p, %s:%p)", DescriptionA, BufferA, DescriptionB, BufferB);
 214   _assert_true (Result, TempStr, FileName, (INT32)LineNumber);
 215
 216   return Result;
 217 }
 218
 219 /**
 220   If ValueA is not equal ValueB, then TRUE is returned.
 221   If ValueA is equal to ValueB, then an assert is triggered and the location
 222   of the assert provided by FunctionName, LineNumber, FileName, DescriptionA
 223   and DescriptionB are recorded and FALSE is returned.
 224
 225   @param[in]  ValueA        64-bit value.
 226   @param[in]  ValueB        64-bit value.
 227   @param[in]  FunctionName  Null-terminated ASCII string of the function
 228                             executing the assert macro.
 229   @param[in]  LineNumber    The source file line number of the assert macro.
 230   @param[in]  FileName      Null-terminated ASCII string of the filename
 231                             executing the assert macro.
 232   @param[in]  DescriptionA  Null-terminated ASCII string that is a description
 233                             of ValueA.
 234   @param[in]  DescriptionB  Null-terminated ASCII string that is a description
 235                             of ValueB.
 236
 237   @retval  TRUE   ValueA is not equal to ValueB.
 238   @retval  FALSE  ValueA is equal to ValueB.
 239 **/
 240 BOOLEAN
 241 EFIAPI
 242 UnitTestAssertNotEqual (
 243   IN UINT64       ValueA,
 244   IN UINT64       ValueB,
 245   IN CONST CHAR8  *FunctionName,
 246   IN UINTN        LineNumber,
 247   IN CONST CHAR8  *FileName,
 248   IN CONST CHAR8  *DescriptionA,
 249   IN CONST CHAR8  *DescriptionB
 250   )
 251 {
 252   CHAR8  TempStr[MAX_STRING_SIZE];
 253
 254   snprintf (TempStr, sizeof (TempStr), "UT_ASSERT_NOT_EQUAL(%s:%llx, %s:%llx)", DescriptionA, ValueA, DescriptionB, ValueB);
 255   _assert_true ((ValueA != ValueB), TempStr, FileName, (INT32)LineNumber);
 256
 257   return (ValueA != ValueB);
 258 }
 259
 260 /**
 261   If Status is equal to Expected, then TRUE is returned.
 262   If Status is not equal to Expected, then an assert is triggered and the
 263   location of the assert provided by FunctionName, LineNumber, FileName, and
 264   Description are recorded and FALSE is returned.
 265
 266   @param[in]  Status        EFI_STATUS value returned from an API under test.
 267   @param[in]  Expected      The expected EFI_STATUS return value from an API
 268                             under test.
 269   @param[in]  FunctionName  Null-terminated ASCII string of the function
 270                             executing the assert macro.
 271   @param[in]  LineNumber    The source file line number of the assert macro.
 272   @param[in]  FileName      Null-terminated ASCII string of the filename
 273                             executing the assert macro.
 274   @param[in]  Description   Null-terminated ASCII string that is a description
 275                             of Status.
 276
 277   @retval  TRUE   Status is equal to Expected.
 278   @retval  FALSE  Status is not equal to Expected.
 279 **/
 280 BOOLEAN
 281 EFIAPI
 282 UnitTestAssertStatusEqual (
 283   IN EFI_STATUS   Status,
 284   IN EFI_STATUS   Expected,
 285   IN CONST CHAR8  *FunctionName,
 286   IN UINTN        LineNumber,
 287   IN CONST CHAR8  *FileName,
 288   IN CONST CHAR8  *Description
 289   )
 290 {
 291   CHAR8  TempStr[MAX_STRING_SIZE];
 292
 293   snprintf (TempStr, sizeof (TempStr), "UT_ASSERT_STATUS_EQUAL(%s:%p)", Description, (VOID *)Status);
 294   _assert_true ((Status == Expected), TempStr, FileName, (INT32)LineNumber);
 295
 296   return (Status == Expected);
 297 }
 298
 299 /**
 300   If Pointer is not equal to NULL, then TRUE is returned.
 301   If Pointer is equal to NULL, then an assert is triggered and the location of
 302   the assert provided by FunctionName, LineNumber, FileName, and PointerName
 303   are recorded and FALSE is returned.
 304
 305   @param[in]  Pointer       Pointer value to be checked against NULL.
 306   @param[in]  Expected      The expected EFI_STATUS return value from a function
 307                             under test.
 308   @param[in]  FunctionName  Null-terminated ASCII string of the function
 309                             executing the assert macro.
 310   @param[in]  LineNumber    The source file line number of the assert macro.
 311   @param[in]  FileName      Null-terminated ASCII string of the filename
 312                             executing the assert macro.
 313   @param[in]  PointerName   Null-terminated ASCII string that is a description
 314                             of Pointer.
 315
 316   @retval  TRUE   Pointer is not equal to NULL.
 317   @retval  FALSE  Pointer is equal to NULL.
 318 **/
 319 BOOLEAN
 320 EFIAPI
 321 UnitTestAssertNotNull (
 322   IN VOID         *Pointer,
 323   IN CONST CHAR8  *FunctionName,
 324   IN UINTN        LineNumber,
 325   IN CONST CHAR8  *FileName,
 326   IN CONST CHAR8  *PointerName
 327   )
 328 {
 329   CHAR8  TempStr[MAX_STRING_SIZE];
 330
 331   snprintf (TempStr, sizeof (TempStr), "UT_ASSERT_NOT_NULL(%s:%p)", PointerName, Pointer);
 332   _assert_true ((Pointer != NULL), TempStr, FileName, (INT32)LineNumber);
 333
 334   return (Pointer != NULL);
 335 }
 336
 337 /**
 338   If UnitTestStatus is UNIT_TEST_PASSED, then log an info message and return
 339   TRUE because an ASSERT() was expected when FunctionCall was executed and an
 340   ASSERT() was triggered. If UnitTestStatus is UNIT_TEST_SKIPPED, then log a
 341   warning message and return TRUE because ASSERT() macros are disabled.  If
 342   UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED, then log an error message and
 343   return FALSE because an ASSERT() was expected when FunctionCall was executed,
 344   but no ASSERT() conditions were triggered.  The log messages contain
 345   FunctionName, LineNumber, and FileName strings to provide the location of the
 346   UT_EXPECT_ASSERT_FAILURE() macro.
 347
 348   @param[in]  UnitTestStatus  The status from UT_EXPECT_ASSERT_FAILURE() that
 349                               is either pass, skipped, or failed.
 350   @param[in]  FunctionName    Null-terminated ASCII string of the function
 351                               executing the UT_EXPECT_ASSERT_FAILURE() macro.
 352   @param[in]  LineNumber      The source file line number of the the function
 353                               executing the UT_EXPECT_ASSERT_FAILURE() macro.
 354   @param[in]  FileName        Null-terminated ASCII string of the filename
 355                               executing the UT_EXPECT_ASSERT_FAILURE() macro.
 356   @param[in]  FunctionCall    Null-terminated ASCII string of the function call
 357                               executed by the UT_EXPECT_ASSERT_FAILURE() macro.
 358   @param[out] ResultStatus    Used to return the UnitTestStatus value to the
 359                               caller of UT_EXPECT_ASSERT_FAILURE().  This is
 360                               optional parameter that may be NULL.
 361
 362   @retval  TRUE   UnitTestStatus is UNIT_TEST_PASSED.
 363   @retval  TRUE   UnitTestStatus is UNIT_TEST_SKIPPED.
 364   @retval  FALSE  UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED.
 365 **/
 366 BOOLEAN
 367 EFIAPI
 368 UnitTestExpectAssertFailure (
 369   IN  UNIT_TEST_STATUS  UnitTestStatus,
 370   IN  CONST CHAR8       *FunctionName,
 371   IN  UINTN             LineNumber,
 372   IN  CONST CHAR8       *FileName,
 373   IN  CONST CHAR8       *FunctionCall,
 374   OUT UNIT_TEST_STATUS  *ResultStatus  OPTIONAL
 375   )
 376 {
 377   CHAR8  TempStr[MAX_STRING_SIZE];
 378
 379   if (ResultStatus != NULL) {
 380     *ResultStatus = UnitTestStatus;
 381   }
 382
 383   if (UnitTestStatus == UNIT_TEST_PASSED) {
 384     UT_LOG_INFO (
 385       "[ASSERT PASS] %a:%d: UT_EXPECT_ASSERT_FAILURE(%a) detected expected assert\n",
 386       FileName,
 387       LineNumber,
 388       FunctionCall
 389       );
 390   }
 391
 392   if (UnitTestStatus == UNIT_TEST_SKIPPED) {
 393     UT_LOG_WARNING (
 394       "[ASSERT WARN] %a:%d: UT_EXPECT_ASSERT_FAILURE(%a) disabled\n",
 395       FileName,
 396       LineNumber,
 397       FunctionCall
 398       );
 399   }
 400
 401   if (UnitTestStatus == UNIT_TEST_ERROR_TEST_FAILED) {
 402     snprintf (TempStr, sizeof (TempStr), "UT_EXPECT_ASSERT_FAILURE(%s) did not trigger ASSERT()", FunctionCall);
 403     _assert_true (FALSE, TempStr, FileName, (INT32)LineNumber);
 404   }
 405
 406   return (UnitTestStatus != UNIT_TEST_ERROR_TEST_FAILED);
 407 }