le_test.h

    1 /**
    2  * @page c_test Unit Testing API
    3  *
    4  * @subpage le_test.h "API Reference"
    5  *
    6  * <HR>
    7  *
    8  * Unit testing is an important aspect of a quantifiable quality assurance methodology.  Although
    9  * unit testing requires some extra overhead (the writing of the unit tests) during the development
   10  * process it can provide enormous benefits during the project life cycle.
   11  *
   12  * One benefit of writing unit tests is that it gets the developer using the interface to the
   13  * unit they designed. This forces the developer to think about, and hopefully design for,
   14  * usability of the interface early in the development cycle.
   15  *
   16  * Another major benefit to unit testing is that it provides a documented and verifiable level of
   17  * correctness for the designed unit. This allows the developer to refactor the code more
   18  * aggressively and to quickly verify its correctness.  Unit tests can also be used to perform
   19  * regression testing when adding new features.
   20  *
   21  * Despite the benefits of unit testing, unit tests are often omitted because of the initial
   22  * overhead of writing the tests and the complexity of testing frameworks.  Legato's Unit Test
   23  * Framework is simple to use and very flexible and lightweight consisting of some
   24  * handy macros.
   25  *
   26  * The Legato test framework outputs test results to the log in TAP format (prefixed by "TAP |")
   27  * This allows test results to be processed with many test harnasses.
   28  *
   29  * @section c_test_setup Setting Up the Test Framework
   30  *
   31  * To setup the Legato Test Framework, call the @c LE_TEST_PLAN macro, once before any tests
   32  * are started. The macro takes the total number of planned tests as single argument.
   33  *
   34  * @section c_test_testing Performing Tests
   35  *
   36  * To perform tests, call the @c LE_TEST_OK macro.  The first argument is whether the
   37  * test passed (true or false).  The second argument is the name of the test.
   38  *
   39  * For example:
   40  *
   41  * @code
   42  * #include "legato.h"
   43  *
   44  * // Returns true if the test passes, otherwise returns false.
   45  * bool ComplexTest(void)
   46  * {
   47  *     int expectedValue;
   48  *
   49  *     // Do some initializations and/or calculations.
   50  *     ...
   51  *
   52  *     // Call one of the unit-under-test's interface function and check it's return value against
   53  *     // an expected value that was calculated earlier.
   54  *     return (unitUnderTest_foo2() == expectedValue);
   55  * }
   56  *
   57  *
   58  * int main (void)
   59  * {
   60  *     // Setup the Legato Test Framework.
   61  *     LE_TEST_PLAN(2);
   62  *
   63  *     // Run the tests.
   64  *     // Do some initializations and/or calculations.
   65  *     ...
   66  *
   67  *     LE_TEST_OK(TestFunction(arguments) == EXPECTED_VALUE, "simple test");
   68  *     LE_TEST_OK(ComplexTest(), "complex test");
   69  *
   70  *     // Exit with the number of failed tests as the exit code.
   71  *     LE_TEST_EXIT;
   72  * }
   73  * @endcode
   74  *
   75  * @section c_test_exit Exiting a Test Program
   76  *
   77  * When a test program is finished executing tests and needs to exit, it should exit
   78  * using the LE_TEST_EXIT macro.
   79  *
   80  * If a test suite needs to exit early it should use the LE_TEST_FATAL() macro.  This will
   81  * log a message indicating the test suite has been aborted.  LE_ASSERT()
   82  * and LE_FATAL() macros should not be used as they will not print this message.
   83  *
   84  * As a convenience you can also use the LE_TEST_ASSERT() macro which will abort the test suite
   85  * if the test fails.  This is useful if running further test cases is pointless after this failure.
   86  *
   87  * @section c_test_result Test Results
   88  *
   89  * The LE_TEST_EXIT macro will cause the process to exit with the number of failed tests as the exit
   90  * code.
   91  *
   92  * @note The log message format depends on the current log settings.
   93  *
   94  * @section c_test_multiThread Multi-Threaded Tests
   95  *
   96  * For unit tests that contain multiple threads run the various tests, these macros can still
   97  * be used.  However your test program should ensure that only one thread uses the unit test
   98  * API at a time.
   99  *
  100  * <HR>
  101  *
  102  * Copyright (C) Sierra Wireless Inc.
  103  */
  104 
  105 //--------------------------------------------------------------------------------------------------
  106 /** @file le_test.h
  107  *
  108  * Legato @ref c_test include file.
  109  *
  110  * Copyright (C) Sierra Wireless Inc.
  111  */
  112 
  113 #ifndef LEGATO_TEST_INCLUDE_GUARD
  114 #define LEGATO_TEST_INCLUDE_GUARD
  115 
  116 
  117 //--------------------------------------------------------------------------------------------------
  118 /**
  119  * @name Local definitions that should not be used directly.
  120  *
  121  * @{
  122  */
  123 //--------------------------------------------------------------------------------------------------
  124 void _le_test_Init(int testCount);
  125 void _le_test_Exit(void) __attribute__((noreturn));
  126 bool _le_test_CheckNeedsPlan(void);
  127 void _le_test_Fail(void);
  128 int _le_test_NumberTest(void);
  129 int _le_test_GetNumTests(void);
  130 int _le_test_GetNumFailures(void);
  131 bool _le_test_SetTodo(bool todo);
  132 void _le_test_Skip(int count);
  133 bool _le_test_IsSkipping(void);
  134 const char* _le_test_GetTag(void);
  135 #define LE_TEST_OUTPUT(format, ...) LE_INFO("TAP | " format, ##__VA_ARGS__)
  136 // @}
  137 
  138 //--------------------------------------------------------------------------------------------------
  139 /**
  140  * Indicate the number of tests is not known in advance.
  141  */
  142 //--------------------------------------------------------------------------------------------------
  143 #define LE_TEST_NO_PLAN   -1
  144 
  145 //--------------------------------------------------------------------------------------------------
  146 /**
  147  * Initializes a test plan.  Must be called once before any tests are performed.
  148  *
  149  * @param testCount  Number of tests expected in this test case.
  150  */
  151 //--------------------------------------------------------------------------------------------------
  152 #define LE_TEST_PLAN(testCount) do {                                    \
  153         if (testCount >= 0) { LE_TEST_OUTPUT("1..%d", testCount); }     \
  154         _le_test_Init(testCount);                                       \
  155     } while(0)
  156 
  157 
  158 //--------------------------------------------------------------------------------------------------
  159 /**
  160  * Initializes the testing framework.  Must be called once before any tests are performed.
  161  *
  162  * Obselete synonym for LE_TEST_PLAN(LE_TEST_NO_PLAN)
  163  */
  164 //--------------------------------------------------------------------------------------------------
  165 #define LE_TEST_INIT                LE_TEST_PLAN(LE_TEST_NO_PLAN)
  166 
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * Perform the test
  171  */
  172 //--------------------------------------------------------------------------------------------------
  173 #define LE_TEST_OK(test, testName, ...) do {                            \
  174         if (test)                                                       \
  175         {                                                               \
  176             LE_TEST_OUTPUT("ok %d - " testName "%s",                    \
  177                            _le_test_NumberTest(),                       \
  178                            ##__VA_ARGS__,                               \
  179                            _le_test_GetTag());                          \
  180         }                                                               \
  181         else                                                            \
  182         {                                                               \
  183             LE_TEST_OUTPUT("not ok %d - " testName "%s",                \
  184                            _le_test_NumberTest(),                       \
  185                            ##__VA_ARGS__,                               \
  186                            _le_test_GetTag());                          \
  187             _le_test_Fail();                                            \
  188         }                                                               \
  189     } while(0)
  190 
  191 //--------------------------------------------------------------------------------------------------
  192 /**
  193  * Performs the test.
  194  *
  195  * For new tests, LE_TEST_OK is preferred which gives an option to set the test name.
  196  */
  197 //--------------------------------------------------------------------------------------------------
  198 #define LE_TEST(testResult) LE_TEST_OK((testResult), #testResult)
  199 
  200 
  201 //--------------------------------------------------------------------------------------------------
  202 /**
  203  * Bail out of a test suite early.
  204  *
  205  * Using this instead of LE_FATAL ensures the test harness is notified the test suite is
  206  * exiting abnormally.
  207  */
  208 //--------------------------------------------------------------------------------------------------
  209 #define LE_TEST_FATAL(...) do {                         \
  210         LE_TEST_OUTPUT("Bail out! " __VA_ARGS__);       \
  211         _le_test_Exit();                                \
  212     } while(0)
  213 
  214 //--------------------------------------------------------------------------------------------------
  215 /**
  216  * Perform a test, and bail out if the test fails.
  217  *
  218  * This should only be used if a test suite cannot continue if this test fails.  Generally
  219  * LE_TEST_OK should be used instead.
  220  */
  221 //--------------------------------------------------------------------------------------------------
  222 #define LE_TEST_ASSERT(test, testName, ...) do {                            \
  223         if (test)                                                       \
  224         {                                                               \
  225             LE_TEST_OUTPUT("ok %d - " testName "%s",                    \
  226                            _le_test_NumberTest(),                       \
  227                            ##__VA_ARGS__,                               \
  228                            _le_test_GetTag());                          \
  229         }                                                               \
  230         else                                                            \
  231         {                                                               \
  232             LE_TEST_OUTPUT("not ok %d - " testName "%s",                \
  233                            _le_test_NumberTest(),                       \
  234                            ##__VA_ARGS__,                               \
  235                            _le_test_GetTag());                          \
  236             _le_test_Fail();                                            \
  237             LE_TEST_FATAL();                                            \
  238         }                                                               \
  239     } while(0)
  240 
  241 
  242 //--------------------------------------------------------------------------------------------------
  243 /**
  244  * Ouptut some diagnostic information.  In tests this should be used instead of LE_INFO so
  245  * the output appears in the test results
  246  */
  247 //--------------------------------------------------------------------------------------------------
  248 #define LE_TEST_INFO(...) LE_TEST_OUTPUT("# " __VA_ARGS__)
  249 
  250 //--------------------------------------------------------------------------------------------------
  251 /**
  252  * Mark a test as not yet implemented.  Todo tests will still be run, but are expected to fail.
  253  *
  254  * Begins a block which must be terminated by LE_TEST_END_TODO()
  255  */
  256 //--------------------------------------------------------------------------------------------------
  257 #define LE_TEST_BEGIN_TODO(cond) do {                                   \
  258         bool _le_test_OldTodo = _le_test_SetTodo(cond);                 \
  259 
  260 //--------------------------------------------------------------------------------------------------
  261 /**
  262  * End a block of tests which may not be implemented yet.
  263  */
  264 //--------------------------------------------------------------------------------------------------
  265 #define LE_TEST_END_TODO()                          \
  266         _le_test_SetTodo(_le_test_OldTodo);         \
  267     } while(0)
  268 
  269 
  270 //--------------------------------------------------------------------------------------------------
  271 /**
  272  * Mark a test as skipped.  Skipped tests will not be run, and will always pass.
  273  *
  274  * Begins a block which must be terminated by LE_TEST_END_SKIP()
  275  */
  276 //--------------------------------------------------------------------------------------------------
  277 #define LE_TEST_BEGIN_SKIP(cond, count) do {                            \
  278           if (cond)                                                     \
  279           {                                                             \
  280               _le_test_Skip(count);                                     \
  281               break;                                                    \
  282           }
  283 
  284 //--------------------------------------------------------------------------------------------------
  285 /**
  286  * End a block of tests which may not be implemented yet.
  287  */
  288 //--------------------------------------------------------------------------------------------------
  289 #define LE_TEST_END_SKIP()                              \
  290     } while(0)
  291 
  292 
  293 //--------------------------------------------------------------------------------------------------
  294 /**
  295  * Exits the process and returns the number of failed tests.
  296  */
  297 //--------------------------------------------------------------------------------------------------
  298 #define LE_TEST_EXIT do {                                       \
  299         if (_le_test_CheckNeedsPlan())                          \
  300         {                                                       \
  301             LE_TEST_OUTPUT("1..%d", _le_test_GetNumTests());    \
  302         }                                                       \
  303         _le_test_Exit();                                        \
  304     } while(0)
  305 
  306 /// <b> *DEPRECATED* </b> old name for LE_TEST_EXIT.
  307 #define LE_TEST_SUMMARY LE_TEST_EXIT
  308 
  309 
  310 #endif // LEGATO_TEST_INCLUDE_GUARD