assert.h

Single-file assertion library for C
git clone git://git.finwo.net/lib/assert.h
Log | Files | Refs | README

README.md (3320B)

      1 assert.h
      2 ========
      3 
      4 Single-file unit-testing library for C
      5 
      6 Features
      7 --------
      8 
      9 - Single header file, no other library dependencies
     10 - Simple ANSI C. The library should work with virtually every C(++) compiler on
     11   virtually any playform
     12 - Reporting of assertion failures, including the expression and location of the
     13   failure
     14 - Stops test on first failed assertion
     15 - ANSI color output for maximum visibility
     16 - Easily embeddable in applications for runtime tests or separate testing
     17   applications
     18 
     19 Todo
     20 ----
     21 
     22 - Disable assertions on definition, to allow production build without source modifications
     23 
     24 Example Usage
     25 -------------
     26 
     27 ```C
     28 #include "finwo/assert.h"
     29 #include "mylib.h"
     30 
     31 void test_sheep() {
     32   ASSERT("Sheep are cool", are_sheep_cool());
     33   ASSERT_EQUALS(4, sheep.legs);
     34 }
     35 
     36 void test_cheese() {
     37   ASSERT("Cheese is tangy", cheese.tanginess > 0);
     38   ASSERT_STRING_EQUALS("Wensleydale", cheese.name);
     39 }
     40 
     41 int main() {
     42   RUN(test_sheep);
     43   RUN(test_cheese);
     44   return TEST_REPORT();
     45 }
     46 ```
     47 
     48 To run the tests, compile the tests as a binary and run it.
     49 
     50 API
     51 ---
     52 
     53 
     54 ### Macros
     55 
     56 <details>
     57   <summary>ASSERT(msg, expression)</summary>
     58 
     59   Perform an assertion
     60 
     61 ```C
     62 #define ASSERT(msg, expression) if (!tap_assert(__FILE__, __LINE__, (msg), (#expression), (expression) ? 1 : 0)) return
     63 ```
     64 
     65 </details>
     66 <details>
     67   <summary>ASSERT_EQUALS(expected, actual)</summary>
     68 
     69   Perform an equal assertion
     70 
     71 ```C
     72 /* Convenient assertion methods */
     73 /* TODO: Generate readable error messages for assert_equals or assert_str_equals */
     74 #define ASSERT_EQUALS(expected, actual) ASSERT((#actual), (expected) == (actual))
     75 ```
     76 
     77 </details>
     78 <details>
     79   <summary>ASSERT_STRING_EQUALS(expected, actual)</summary>
     80 
     81   Perform an equal string assertion
     82 
     83 ```C
     84 #define ASSERT_STRING_EQUALS(expected, actual) ASSERT((#actual), strcmp((expected),(actual)) == 0)
     85 ```
     86 
     87 </details>
     88 <details>
     89   <summary>RUN(fn)</summary>
     90 
     91   Run a test suite/function containing assertions
     92 
     93 ```C
     94 #define RUN(test_function) tap_execute((#test_function), (test_function))
     95 ```
     96 
     97 </details>
     98 <details>
     99   <summary>TEST_REPORT()</summary>
    100 
    101   Report on the tests that have been run
    102 
    103 ```C
    104 #define TEST_REPORT() tap_report()
    105 ```
    106 
    107 </details>
    108 
    109 Extras
    110 ------
    111 
    112 ### Disable color
    113 
    114 If you want to disable color during the assertions, because you want to
    115 interpret the output for example (it is "tap" format after all), you can
    116 define `NO_COLOR` during compilation to disable color output.
    117 
    118 ```sh
    119 cc -D NO_COLOR source.c -o test
    120 ```
    121 
    122 ### Silent assertions
    123 
    124 You can also fully disable output for assertions by defining the
    125 `ASSERT_SILENT` macro. This will fully disable the printf performed after
    126 the assertion is performed.
    127 
    128 ```sh
    129 cc -D ASSERT_SILENT source.c -o test
    130 ```
    131 
    132 ### Silent reporting
    133 
    134 If you do not want the report to be displayed at the end, you can define the
    135 `REPORT_SILENT` macro. This will disable the printf during reporting and
    136 only keep the return code.
    137 
    138 ```sh
    139 cc -D REPORT_SILENT source.c -o test
    140 ```
    141 
    142 
    143 Credits
    144 -------
    145 
    146 This library was heavily based on the [tinytest][tinytest] library by
    147 [Joe Walnes][joewalnes]. A license reference to his library could not be
    148 found, which is why this reference is in this file. Should I be contacted
    149 about licensing issues, I'll investigate further.
    150 
    151 [joewalnes]: https://github.com/joewalnes
    152 [tinytest]: https://github.com/joewalnes/tinytest