Source/lib/utils/tester.h

   1 /**
   2  * @file tester.h
   3  *
   4  * @brief Interface of tester_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Jan Hutter, Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef TESTER_H_
  24 #define TESTER_H_
  25
  26 #include <stdio.h>
  27
  28 #include <types.h>
  29
  30
  31 /* must be defined here cause it is used in test_t */
  32 typedef struct protected_tester_t protected_tester_t;
  33
  34 typedef struct test_t test_t;
  35
  36 /**
  37  * @brief Representing a specified test.
  38  *
  39  * @ingroup utils
  40  */
  41 struct test_t {
  42         /**
  43          * Testfunction called for this test.
  44          *
  45          * @param tester                associated tester_t object
  46          */
  47         void (*test_function) (protected_tester_t * tester);
  48
  49         /**
  50          * Name of the test.
  51          */
  52         char * test_name;
  53 };
  54
  55
  56 typedef struct tester_t tester_t;
  57
  58 /**
  59  * @brief A class to perform tests.
  60  *
  61  * @b Constructors:
  62  *  - tester_create()
  63  *
  64  * @ingroup utils
  65  */
  66 struct tester_t {
  67         /**
  68          * @brief Test all testcases in array tests with specific tester_t object.
  69          *
  70          * @param tester        tester_t object
  71          * @param tests         pointer to an array of test_t-pointers.
  72          *                              The last item has to be NULL to mark end of array.
  73          */
  74         void (*perform_tests) (tester_t *tester,test_t **tests);
  75
  76         /**
  77          * @brief Run a specific test case.
  78          *
  79          * @param this          tester_t object
  80          * @param test          pointer to a test_t object which will be performed
  81          */
  82         void (*perform_test) (tester_t *tester, test_t *test);
  83
  84         /**
  85          * @brief Destroys a tester_t object.
  86          *
  87          * @param tester        tester_t object
  88          */
  89         void (*destroy) (tester_t *tester);
  90 };
  91
  92
  93 /**
  94  * @brief A class used in a specific testcase.
  95  *
  96  * For each testcase an object of this type is passed to the testfunction. The testfunction uses this
  97  * object to check specific asserts with protected_tester_t.assert_true and protected_tester_t.assert_false.
  98  *
  99  * @b Constructors:
 100  *  - tester_create()
 101  *
 102  * @ingroup utils
 103  */
 104 struct protected_tester_t {
 105
 106         /**
 107          * Public functions of a tester_t object
 108          */
 109         tester_t public;
 110
 111         /**
 112          * @brief Is called in a testcase to check a specific situation for TRUE.
 113          *
 114          * Log-Values to the tester output are protected from multiple access.
 115          *
 116          * @param this                  tester_t object
 117          * @param to_be_true    assert which has to be TRUE
 118          * @param assert_name   name of the assertion
 119          */
 120         void (*assert_true) (protected_tester_t *tester, bool to_be_true, char *assert_name);
 121
 122         /**
 123          * @brief Is called in a testcase to check a specific situation for FALSE.
 124          *
 125          * Log-Values to the tester output are protected from multiple access.
 126          *
 127          * @param this                  tester_t object
 128          * @param to_be_false   assert which has to be FALSE
 129          * @param assert_name   name of the assertion
 130          */
 131         void (*assert_false) (protected_tester_t *tester, bool to_be_false, char *assert_name);
 132 };
 133
 134
 135 /**
 136  * @brief Creates a tester_t object used to perform tests with.
 137  *
 138  * @param output                                        test output is written to this output.
 139  * @param display_succeeded_asserts has to be TRUE, if all asserts should be displayed,
 140  *                                                                      FALSE otherwise
 141  *
 142  * @return                                                      tester_t object
 143  *
 144  * @ingroup utils
 145  */
 146 tester_t *tester_create(FILE *output, bool display_succeeded_asserts);
 147
 148 #endif /*TESTER_H_*/