third_party/nlunit-test/repo/src/nlunit-test.h

   1 /**
   2  *    Copyright 2020 Project nlunit-test Authors. All Rights Reserved.
   3  *    Copyright 2012-2017 Nest Labs Inc. All Rights Reserved.
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 /**
  19  *    @file
  20  *      This file defines macros, constants, data structures, and
  21  *      functions that effect a simple, portable unit test suite
  22  *      framework.
  23  *
  24  */
  25
  26 #ifndef __NLUNIT_TEST_H_INCLUDED__
  27 #define __NLUNIT_TEST_H_INCLUDED__
  28
  29 #include <stdbool.h>
  30 #include <stdint.h>
  31 #include <stdio.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #else
  36 #endif /* __cplusplus */
  37
  38 /**
  39  * @addtogroup typedef Type Definitions
  40  *
  41  * @{
  42  *
  43  */
  44
  45 struct _nlTestSuite;
  46
  47 /**
  48  * This defines a function entry point for a test in a test suite.
  49  *
  50  * @param[inout]  inSuite     A pointer to the test suite being run.
  51  * @param[inout]  inContext   A pointer to test suite-specific context
  52  *                            provided by the test suite driver.
  53  *
  54  */
  55 typedef void (*nlTestFunction)(struct _nlTestSuite* inSuite, void* inContext);
  56
  57 /**
  58  * This structure is used to define a single test for use in a test suite.
  59  *
  60  */
  61 typedef struct _nlTest
  62 {
  63     const char*    name;                /**< Brief descriptive name of the test */
  64     nlTestFunction function;            /**< Function entry point for the test */
  65 } nlTest;
  66
  67 /**
  68  * This structure is used to define the test suite, an array of tests
  69  * for a given module.
  70  *
  71  * It has a name for the suite, the array of tests, as well as a setup function which
  72  * is called before the execution of the test suite and a teardown function which is
  73  * called after all tests in the suite are complete. It also contains pointers to an
  74  * initialize function which is called before each individual test, and a terminate
  75  * function which is called after each individual test.
  76  *
  77  */
  78 typedef struct _nlTestSuite
  79 {
  80     /* Public Members */
  81     const char*    name;                /**< Brief descriptive name of the test suite */
  82     const nlTest*  tests;               /**< Array of tests in the suite */
  83
  84     /**
  85      * This function is responsible for, if non-NULL, performing
  86      * initial setup for the entire test suite, before running any
  87      * tests in the suite.
  88      *
  89      * @param[inout]  inContext   A pointer to test suite-specific context
  90      *                            provided by the test suite driver.
  91      *
  92      */
  93     int            (*setup)(void *inContext);
  94
  95     /**
  96      * This function is responsible for, if non-NULL, performing
  97      * tear down for the entire test suite, after every test in the suite.
  98      *
  99      * @param[inout]  inContext   A pointer to test suite-specific context
 100      *                            provided by the test suite driver.
 101      *
 102      */
 103     int            (*tear_down)(void *inContext);
 104
 105     /**
 106      * This function is responsible for, if non-NULL, performing
 107      * initialization for the test, before running the test.
 108      *
 109      * @param[inout]  inContext   A pointer to test suite-specific context
 110      *                            provided by the test suite driver.
 111      *
 112      */
 113     int            (*initialize)(void *inContext);
 114
 115     /**
 116      * This function is responsible for, if non-NULL, performing
 117      * final tear down for the test, after running the test.
 118      *
 119      * @param[inout]  inContext   A pointer to test suite-specific context
 120      *                            provided by the test suite driver.
 121      *
 122      */
 123     int            (*terminate)(void *inContext);
 124
 125     int            runTests;            /**< Total number of tests performed in the suite */
 126     int            failedTests;         /**< Total number of tests failed in the suite */
 127     int            performedAssertions; /**< Total number of test assertions performed in the suite */
 128     int            failedAssertions;    /**< Total number of test assertions failed in the suite */
 129
 130     /* Private Members */
 131     bool           flagError;
 132 } nlTestSuite;
 133
 134 /**
 135  * Output style for tests and test summaries.
 136  */
 137 typedef enum _nlTestOutputStyle
 138 {
 139     OUTPUT_DEF = 0,   /**< Generate human-readable output (default). */
 140     OUTPUT_CSV = 1,   /**< Generate machine-readable, comma-separated value (CSV) output. */
 141 } nlTestOutputStyle;
 142
 143 /**
 144  * This structure contains function pointers for functions that output
 145  * the test suite name as well as the status of:
 146  *
 147  *   * Test suite setup and teardown functions.
 148  *   * Tests and result functions (failed tests, failed assertions).
 149  *
 150  * All functions take a pointer to the test suite along with
 151  * additional parameters, as needed, for the particular function.
 152  *
 153  * Custom instances of this structure may be instantiated and
 154  * populated with custom output functions and then globally set via
 155  * nlTestSetLogger.
 156  *
 157  */
 158 typedef struct _nlTestOutputLogger {
 159     /**
 160      * This function is responsible for rendering the name of the test
 161      * suite.
 162      *
 163      *  @param[in]    inSuite      A pointer to the test suite for which
 164      *                             the name should be rendered.
 165      *
 166      */
 167     void (*PrintName)(struct _nlTestSuite*inSuite);
 168
 169     /**
 170      * This function is responsible for rendering the status of the
 171      * individual test initialization.
 172      *
 173      *  @param[in]    inSuite      A pointer to the test suite for which
 174      *                             the test suite setup status should be
 175      *                             rendered.
 176      *  @param[in]    inResult     The status of the test suite setup to
 177      *                             be rendered.
 178      *  @param[in]    inWidth      The maximum width, in characters,
 179      *                             allowed for rendering the setup name
 180      *                             or phase.
 181      *
 182      */
 183      void (*PrintInitialize)(struct _nlTestSuite * inSuite, int inResult, int inWidth);
 184
 185     /**
 186      * This function is responsible for rendering the status of the
 187      * individual test termination
 188      *
 189      *  @param[in]    inSuite      A pointer to the test suite for which
 190      *                             the test suite setup status should be
 191      *                             rendered.
 192      *  @param[in]    inResult     The status of the test suite setup to
 193      *                             be rendered.
 194      *  @param[in]    inWidth      The maximum width, in characters,
 195      *                             allowed for rendering the setup name
 196      *                             or phase.
 197      *
 198      */
 199     void (*PrintTerminate)(struct _nlTestSuite * inSuite, int inResult, int inWidth);
 200
 201     /**
 202      * This function is responsible for rendering the status of the test
 203      * suite setup.
 204      *
 205      *  @param[in]    inSuite      A pointer to the test suite for which
 206      *                             the test suite setup status should be
 207      *                             rendered.
 208      *  @param[in]    inResult     The status of the test suite setup to
 209      *                             be rendered.
 210      *  @param[in]    inWidth      The maximum width, in characters,
 211      *                             allowed for rendering the setup name
 212      *                             or phase.
 213      *
 214      */
 215     void (*PrintSetup)(struct _nlTestSuite*inSuite, int inResult, int inWidth);
 216
 217     /**
 218      * This function is responsible for rendering the summary of a test
 219      * run, indicating success or failure of that test.
 220      *
 221      *  @param[in]    inSuite      A pointer to the test suite for which
 222      *                             the test run status summary should be
 223      *                             rendered.
 224      *  @param[in]    inWidth      The maximum width, in characters,
 225      *                             allowed for rendering the test name.
 226      *  @param[in]    inIndex      The index of the test in the suite
 227      *                             for which to render the summary of the
 228      *                             test run.
 229      *
 230      */
 231     void (*PrintTest)(struct _nlTestSuite*inSuite, int inWidth, int inIndex);
 232
 233     /**
 234      * This function is responsible for rendering the status of the test
 235      * suite teardown.
 236      *
 237      *  @param[in]    inSuite      A pointer to the test suite for which
 238      *                             the test suite teardown status should be
 239      *                             rendered.
 240      *  @param[in]    inResult     The status of the test suite setup to
 241      *                             be rendered.
 242      *  @param[in]    inWidth      The maximum width, in characters,
 243      *                             allowed for rendering the setup name
 244      *                             or phase.
 245      *
 246      */
 247     void (*PrintTeardown)(struct _nlTestSuite*inSuite, int inResult, int inWidth);
 248
 249     /**
 250      * This function is responsible for rendering the test suite run
 251      * statistics, including the number of failed tests and the total
 252      * number of tests run.
 253      *
 254      *  @param[in]    inSuite      A pointer to the test suite for which
 255      *                             the test suite test statistics should be
 256      *                             rendered.
 257      *
 258      */
 259     void (*PrintStatTests)(struct _nlTestSuite*inSuite);
 260
 261     /**
 262      * This function is responsible for rendering the test suite assertion
 263      * statistics, including the number of failed assertions and the total
 264      * number of assertions evaluated.
 265      *
 266      *  @param[in]    inSuite      A pointer to the test suite for which
 267      *                             the test suite assertion statistics should
 268      *                             be rendered.
 269      *
 270      */
 271     void (*PrintStatAsserts)(struct _nlTestSuite*inSuite);
 272 } nlTestOutputLogger;
 273
 274 /**
 275  *  @}
 276  *
 277  */
 278
 279 /**
 280  *  @addtogroup cpp Preprocessor Definitions and Macros
 281  *
 282  *  @{
 283  */
 284
 285 /**
 286  *  @def kTestSuiteMaxTests
 287  *
 288  *  @brief
 289  *    Defines the maximum number of tests allowed in a single test suite.
 290  *
 291  */
 292 #define kTestSuiteMaxTests (64)
 293
 294 /**
 295  *  @def SUCCESS
 296  *
 297  *  @brief
 298  *    Defines successful return status from test suite functions
 299  *
 300  */
 301 #define SUCCESS 0
 302
 303 /**
 304  *  @def FAILURE
 305  *
 306  *  @brief
 307  *    Defines failed return status from test suite functions
 308  *
 309  */
 310 #define FAILURE -1
 311
 312 #ifdef __cplusplus
 313 #define _NL_TEST_ASSIGN(field, value) value
 314 #else
 315 #define _NL_TEST_ASSIGN(field, value) .field = value
 316 #endif /* __cplusplus */
 317
 318 /**
 319  *  @def NL_TEST_DEF(inName, inFunction)
 320  *
 321  *  @brief
 322  *    This macro makes an test assignment in a test suite, associating
 323  *    the specified function @a inFunction with the provided string @a
 324  *    inName.
 325  *
 326  *  @param[in]    inName       A pointer to a NULL-terminated C string
 327  *                             briefly describing the test.
 328  *  @param[in]    inFunction   A pointer to the function entry point for
 329  *                             the test.
 330  *
 331  */
 332 #define NL_TEST_DEF(inName, inFunction)               \
 333 {                                                     \
 334     _NL_TEST_ASSIGN(name, inName),                    \
 335     _NL_TEST_ASSIGN(function, inFunction)             \
 336 }
 337
 338 /**
 339  *  @def NL_TEST_SENTINEL()
 340  *
 341  *  @brief
 342  *    This macro must be used as the final entry to terminate an array
 343  *    of test assignments to a test suite.
 344  *
 345  */
 346 #define NL_TEST_SENTINEL()                            NL_TEST_DEF(NULL, NULL)
 347
 348 /**
 349  *  @def NL_TEST_ASSERT(inSuite, inCondition)
 350  *
 351  *  @brief
 352  *    This is used to assert the results of a conditional check
 353  *    through out a test in a test suite.
 354  *
 355  *  @param[in]    inSuite      A pointer to the test suite the assertion
 356  *                             should be accounted against.
 357  *  @param[in]    inCondition  Code for the logical predicate to be checked
 358  *                             for truth. If the condition fails, the
 359  *                             assertion fails.
 360  *
 361  */
 362 #define NL_TEST_ASSERT(inSuite, inCondition)            \
 363     do {                                                \
 364         (inSuite)->performedAssertions += 1;            \
 365                                                         \
 366         if (!(inCondition))                             \
 367         {                                               \
 368             printf("%s:%u: assertion failed: \"%s\"\n", \
 369                    __FILE__, __LINE__, #inCondition);   \
 370             (inSuite)->failedAssertions += 1;           \
 371             (inSuite)->flagError = true;                \
 372         }                                               \
 373     } while (0)
 374
 375 #define NL_TEST_ASSERT_LOOP(inSuite, iteration, inCondition)     \
 376 do {                                                             \
 377     (inSuite)->performedAssertions += 1;                         \
 378     if ( !(inCondition) )                                        \
 379     {                                                            \
 380         printf("%s:%u: loop iter %d assertion failed: \"%s\"\n", \
 381                __FILE__, __LINE__, iteration, #inCondition);     \
 382         (inSuite)->failedAssertions += 1;                        \
 383         (inSuite)->flagError = true;                             \
 384     }                                                            \
 385 } while (0)
 386
 387 /**
 388  * @}
 389  *
 390  */
 391
 392 /**
 393  * This runs all the functions for each test specified in the current
 394  * suite and outputs the results for each function using the
 395  * currently-set logger methods.
 396  *
 397  * @param[inout]  inSuite     A pointer to the test suite being run.
 398  * @param[inout]  inContext   A pointer to test suite-specific context
 399  *                            that will be provided to each test invoked
 400  *                            within the suite.
 401  *
 402  */
 403 extern void nlTestRunner(struct _nlTestSuite* inSuite, void* inContext);
 404
 405 /**
 406  * This summarizes the number of run and failed tests as well as the
 407  * number of performed and failed assertions for the suite using the
 408  * currently-set logger methods.
 409  *
 410  * @param[inout]  inSuite     A pointer to the test suite being run.
 411  *
 412  * @returns SUCCESS on success; otherwise, FAILURE.
 413  */
 414 extern int  nlTestRunnerStats(struct _nlTestSuite* inSuite);
 415
 416 /**
 417  * This globally sets the output style to be used for summarizing a
 418  * suite test run.
 419  *
 420  * @note This supports selecting among built-in logger methods. Custom
 421  *       logger methods may be set through the nlTestSetLogger() interface.
 422  *
 423  * @param[in]     inStyle     The style to be used for summarizing a
 424  *                            suite test run.
 425  *
 426  */
 427 extern void nlTestSetOutputStyle(nlTestOutputStyle inStyle);
 428
 429 /**
 430  * This globally sets the logger methods to be used for summarizing a
 431  * suite test run.
 432  *
 433  * @param[in]     inLogger    A pointer to the logger methods to be used
 434  *                            for summarizing a suite test run.
 435  *
 436  */
 437 extern void nlTestSetLogger(const nlTestOutputLogger* inLogger);
 438
 439 /**
 440  *  @addtogroup compat Compatibility Types and Interfaces
 441  *
 442  *  Deprecated legacy types and interfaces. New usage of these types
 443  *  and interfaces is discouraged.
 444  *
 445  *  @{
 446  */
 447
 448 /**
 449  * Legacy type for output style for tests and test summaries.
 450  *
 451  */
 452 typedef nlTestOutputStyle  nl_test_outputStyle;
 453
 454 /**
 455  * Legacy type for output functions.
 456  *
 457  */
 458 typedef nlTestOutputLogger nl_test_output_logger_t;
 459
 460 /**
 461  *  @def nl_test_set_output_style(inStyle)
 462  *
 463  *  @note See nlTestSetOutputStyle() for the equivalent non-deprecated
 464  *        interface.
 465  *
 466  *  @brief
 467  *    This globally sets the output style to be used for summarizing a
 468  *    suite test run.
 469  *
 470  *  @param[in]    inStyle     The style to be used for summarizing a
 471  *                            suite test run.
 472  *
 473  */
 474 #define nl_test_set_output_style(inStyle) nlTestSetOutputStyle(inStyle)
 475
 476 /**
 477  *  @def nl_test_set_logger(inLogger)
 478  *
 479  *  @note See nlTestSetLogger() for the equivalent non-deprecated
 480  *        interface.
 481  *
 482  *  @brief
 483  *    This globally sets the output style to be used for summarizing a
 484  *    suite test run.
 485  *
 486  *  @param[in]    inLogger    A pointer to the logger methods to be used
 487  *                            for summarizing a suite test run.
 488  *
 489  */
 490 #define nl_test_set_logger(inLogger)      nlTestSetLogger(inLogger)
 491
 492 /**
 493  *  @}
 494  *
 495  */
 496
 497 #ifdef __cplusplus
 498 }
 499 #endif /* __cplusplus */
 500
 501 #endif /* __NLUNIT_TEST_H_INCLUDED__ */