test/tinytest.h

   1 /* tinytest.h -- Copyright 2009-2012 Nick Mathewson
   2  *
   3  * Redistribution and use in source and binary forms, with or without
   4  * modification, are permitted provided that the following conditions
   5  * are met:
   6  * 1. Redistributions of source code must retain the above copyright
   7  *    notice, this list of conditions and the following disclaimer.
   8  * 2. Redistributions in binary form must reproduce the above copyright
   9  *    notice, this list of conditions and the following disclaimer in the
  10  *    documentation and/or other materials provided with the distribution.
  11  * 3. The name of the author may not be used to endorse or promote products
  12  *    derived from this software without specific prior written permission.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24  */
  25
  26 #ifndef TINYTEST_H_INCLUDED_
  27 #define TINYTEST_H_INCLUDED_
  28
  29 /** Flag for a test that needs to run in a subprocess. */
  30 #define TT_FORK  (1<<0)
  31 /** Runtime flag for a test we've decided to skip. */
  32 #define TT_SKIP  (1<<1)
  33 /** Internal runtime flag for a test we've decided to run. */
  34 #define TT_ENABLED_  (1<<2)
  35 /** Flag for a test that's off by default. */
  36 #define TT_OFF_BY_DEFAULT  (1<<3)
  37 /** Flag for a test that should be runned again in case of failure (but not
  38  * more then 3 times). */
  39 #define TT_RETRIABLE    (1<<4)
  40 /** If you add your own flags, make them start at this point. */
  41 #define TT_FIRST_USER_FLAG (1<<5)
  42
  43 typedef void (*testcase_fn)(void *);
  44
  45 struct testcase_t;
  46
  47 /** Functions to initialize/teardown a structure for a testcase. */
  48 struct testcase_setup_t {
  49         /** Return a new structure for use by a given testcase. */
  50         void *(*setup_fn)(const struct testcase_t *);
  51         /** Clean/free a structure from setup_fn. Return 1 if ok, 0 on err. */
  52         int (*cleanup_fn)(const struct testcase_t *, void *);
  53 };
  54
  55 /** A single test-case that you can run. */
  56 struct testcase_t {
  57         const char *name; /**< An identifier for this case. */
  58         testcase_fn fn; /**< The function to run to implement this case. */
  59         unsigned long flags; /**< Bitfield of TT_* flags. */
  60         const struct testcase_setup_t *setup; /**< Optional setup/cleanup fns*/
  61         void *setup_data; /**< Extra data usable by setup function */
  62 };
  63 #define END_OF_TESTCASES { NULL, NULL, 0, NULL, NULL }
  64
  65 /** A group of tests that are selectable together. */
  66 struct testgroup_t {
  67         const char *prefix; /**< Prefix to prepend to testnames. */
  68         struct testcase_t *cases; /** Array, ending with END_OF_TESTCASES */
  69 };
  70 #define END_OF_GROUPS { NULL, NULL}
  71
  72 struct testlist_alias_t {
  73         const char *name;
  74         const char **tests;
  75 };
  76 #define END_OF_ALIASES { NULL, NULL }
  77
  78 /** Implementation: called from a test to indicate failure, before logging. */
  79 void tinytest_set_test_failed_(void);
  80 /** Implementation: called from a test to indicate that we're skipping. */
  81 void tinytest_set_test_skipped_(void);
  82 /** Implementation: return 0 for quiet, 1 for normal, 2 for loud. */
  83 int tinytest_get_verbosity_(void);
  84 /** Implementation: Set a flag on tests matching a name; returns number
  85  * of tests that matched. */
  86 int tinytest_set_flag_(struct testgroup_t *, const char *, int set, unsigned long);
  87 /** Implementation: Put a chunk of memory into hex. */
  88 char *tinytest_format_hex_(const void *, unsigned long);
  89
  90 /** Set all tests in 'groups' matching the name 'named' to be skipped. */
  91 #define tinytest_skip(groups, named) \
  92         tinytest_set_flag_(groups, named, 1, TT_SKIP)
  93
  94 /** Run a single testcase in a single group. */
  95 int testcase_run_one(const struct testgroup_t *,const struct testcase_t *);
  96
  97 void tinytest_set_aliases(const struct testlist_alias_t *aliases);
  98
  99 /** Run a set of testcases from an END_OF_GROUPS-terminated array of groups,
 100     as selected from the command line. */
 101 int tinytest_main(int argc, const char **argv, struct testgroup_t *groups);
 102
 103 #endif