diff options
| author | sanine <sanine.not@pm.me> | 2022-12-30 21:22:50 -0600 |
|---|---|---|
| committer | sanine <sanine.not@pm.me> | 2022-12-30 21:22:50 -0600 |
| commit | bf71f069d4861ba2285c96dd98bdf1bbe0322fc2 (patch) | |
| tree | 454cdcd335a408b8a4c1c1b038b152363335dcc2 /doc/02-writing-tests.html | |
| parent | b8c647c9250b514a5daa11ea731691b19944aa4e (diff) | |
begin documentation and add lily_begin() and lily_finish()
Diffstat (limited to 'doc/02-writing-tests.html')
| -rw-r--r-- | doc/02-writing-tests.html | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/doc/02-writing-tests.html b/doc/02-writing-tests.html new file mode 100644 index 0000000..152ccac --- /dev/null +++ b/doc/02-writing-tests.html @@ -0,0 +1,119 @@ +<!DOCTYPE HTML> +<html> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <link rel="stylesheet" href="style.css"> + <title>Writing Tests | lily-test</title> +</head> +<body> + <div id="flex-root"> + <iframe id="toc" src="table-of-contents.html"></iframe> + <div id="content"> + + <h1>Writing Tests</h1> + + <p>A basic unit test file looks like this:</p> + + <pre><code> +#include "lily-test.h" + +LILY_FILE_BEGIN(example_file) + + +LILY_TEST("example test 1") +{ + CHECK_EQ(1+1, 2, "%d"); +} +#include LILY_PUSH_TEST() + + +LILY_TEST("example test 2") +{ + CHECK_LT(3.0, 4.0, "%0.2f"); +} +#include LILY_PUSH_TEST() + + +#define LILY_FILE_END +#include LILY_REGISTER_TESTS() + </code></pre> + + <p>This will define a function pointer <code>example_file</code> with signature <code>void ()</code> that, when called, will execute the two tests and display to stderr any errors that they generate. While there is more boilerplate than in comparable C++ libraries, this means that lily-test supports test auto-registration. To add a new test, just use the <code>LILY_TEST</code> macro as shown, and then follow the function body with <code>#include LILY_PUSH_TEST()</code> to register it. These macros will only work correctly when used between a <code>LILY_FILE_BEGIN</code> and <code>LILY_FILE_END</code> block, and only when used <em>together</em>; using <code>LILY_TEST</code> without a <code>LILY_PUSH_TEST</code> is probably going to throw up a ton of compile errors.</p> + + <h2>Using a single file</h2> + + <p>For very small projects, you may be able to get away with using only a single unit test file. In this case, you should set it up along the following lines:</p> + + <pre><code> +#define LILY_IMPLEMENTATION +#include "lily-test.h" + +/* any includes or code to get your tests working */ + +LILY_FILE_BEGIN(tests) + +/* test definitions... */ + +#define LILY_FILE_END +#include LILY_REGISTER_TESTS() + +int main() +{ + lily_begin(); + tests(); + lily_finish(); + return 0; +} + </code></pre> + + However, in most cases you will want to have multiple test files. + + + <h2>Multiple test files</h2> + + <p>You will need, in addition to your unit test files, a header file that contains extern declarations of the function pointers defined by your files and a main C source file that contains a <code>main</code> function to run all of the function pointers. A nice way to set this up is to use X-macros, like this:</p> + + <pre><code> +/* tests.h */ + +#define TESTS \ + X(suite_1) \ + X(suite_2) \ + X(suite_3) \ + + +#define X(suite) extern void (*suite)(); +TESTS +#undef X + </code></pre> + + <pre><code> +/* tests_main.c */ + +#define LILY_IMPLEMENTATION +#include "lily-test.h" + +int main() +{ + lily_begin(); + #define X(suite) suite(); + TESTS + #undef X + lily_finish(); + return 0; +} + </code></pre> + + <p>This is convenient, because it means that when you add a new test file you need only add a single line to the definition of the <code>TESTS</code> macro in <code>tests.h</code> and all of the other relevant code is added for you automatically.<p> + + <p>Note that exactly ONE file should define <code>LILY_IMPLEMENTATION</code>. I find it reasonable to make this the same file with the implementation of <code>main</code> but YMMV.</p> + + </div> + </div> + <div id="footer"> + <a id="prev" href="01-introduction.html">⇐ Previous</a> + <a id="next" href="03-assertions.html">Next ⇒</a> + </div> +</body> +</html> |