diff options
| -rw-r--r-- | README.md | 70 |
1 files changed, 62 insertions, 8 deletions
@@ -10,11 +10,20 @@ source code. usage ----- -The function `lily_init()` must be called exactly once before any other lily -functions may be called. +Tests are any function with the signature `void (void)`, and are run with the macro `lily_run_test(test)`. +Tests are intended to be run inside of suite functions, which have the same signature as a test. +To add suite setup or teardown operations, just do them inside the suite function. +Suites are run with the `lily_run_suite(suite)` macro. -Tests are simply functions with the signature `void ()`. Each test can contain -any of the following assertion messages: +Tests can contain assertions! You should not try to use these assertions outside of tests run with +`lily_run_test()` because you'll probably just crash your program. Tests, if they fail, generate +error messages that detail the mismatch between their expected and actual results and also indicate +the file and line of the failed assertion. On some compilers `__FILE__` is the complete path of the +file (i.e. all the way from root), so lily lets you trim N characters from the front of it by +defining a `SOURCE_PATH_SIZE` macro whose value is N. (I usually define this from within my build tool +so that it'll still work if other people download the software). + +The following assertions are available: * `lily_assert_true(bool)` * `lily_assert_false(bool)` @@ -31,12 +40,57 @@ any of the following assertion messages: * `lily_assert_memory_equal(void *, void *, size_t size)` * `lily_assert_memory_not_equal(void *, void *, size_t size)` -Tests are run via the macro `lily_run_test(test_func)`. A test suite is simply a `void ()` -function that runs some tests. Suites can be called via the macro `lily_run_suite(suite_func)`. +lily also provides some features to make mocking functions a little nicer. First, +there is the `lily_queue_t` object, which contains a FIFO queue for arbitrary data. +They support the following operations: + +* `lily_queue_t * lily_queue_create()` - create a new queue +* `lily_queue_destroy(lily_queue_t *)` - destroy a queue +* `lily_enqueue(lily_queue_t*, TYPE, value)` - enqueue some value. Any type can be queued; just be careful to dequeue the same data types in the same order! +* `lily_dequeue(lily_queue_t*, TYPE, ptr)` - pops a value from the queue into a pointer of **an appropriate type**. Be careful not to dequeue data types in the same order you queued them! + +This system is intended to allow you to control the behavior/return types of mock functions +by queueing things before a call that the mock will dequeue. + +lily also provides the `lily_mock_t` object, which uses these queues to easily store the arguments +of a call to a function. + +* `lily_mock_t * lily_mock_create()` - create a new mock object +* `lily_mock_destroy(lily_mock_t *)` - destroy a mock object +* `lily_mock_call(lily_mock_t*, struct lily_mock_arg_t*)` - store arguments (see below) +* `lily_get_call(lily_mock_t*, struct lily_mock_arg_t*, int)` - store arguments (see below) + +Each `struct lily_mock_arg_t` contains a size and void pointer, so storing a set of arguments +looks something like this: + +``` +lily_mock_t *m; // initialized somewhere +void some_func(int a, const char *b) +{ + struct lily_mock_arg_t args[] = { + { sizeof(int), &a }, + { sizeof(const char *), &b }, + }; + lily_mock_call(m, args); + /* ... */ +} +``` + +Retrieving calls looks much the same, except the pointers in the array are to destinations +and not sources. (You also need to specify the zero-indexed number of the call -- that's the `int` argument). + + + +~ the future ~ +-------------- + +Some features I'd like to add: -A small script, called `prepare-tests.sh` is provided. It will automatically scan +A `prepare-tests.sh` script that will automatically scan the given source root for all files matching `*.test.c` and qenerate a header file, main function, and Makefile to run all of the functions matching `void ()` in those test files. (If you want a utility function or something, just make it `static`). -This script relies on POSIX utilities -- sorry, Windows users. :l +It might be nice to switch to an stb-style header-only library, where the contents of +`lily-test.c` are put inside of a macro gate, and the user just has to `#define LILY_IMPLEMENTATION` +in some file that includes `lily-test.h`. |