# unit_test.h ## Overview
Interface for unit tests.
## Index
`tm_unit_test_runner_o`

`struct tm_unit_test_runner_i`
`inst`
`test_file()`
`test_custom()`
`test_disk()`
`test_network()`
`test_slow_paths()`
`record()`
`expect_error()`

`struct tm_unit_test_i`
`name`
`test()`

`TM_UNIT_TEST_INTERFACE_NAME`
`tm_basic_unit_test_runner`
`TM_UNIT_TEST()`
`TM_UNIT_TESTF()`
`TM_EXPECT_ERROR()`
## API
### `tm_unit_test_runner_o`
~~~c typedef struct tm_unit_test_runner_o tm_unit_test_runner_o; ~~~ User data for `tm_unit_test_runner_i`.
### `struct tm_unit_test_runner_i`
`tm_unit_test_runner_i` defines an interface for *Unit Test Runners* -- objects capable of running unit tests. A codebase may have multiple unit test runners. One runner might log the results to the command line, while another uploads it to a web server, etc. #### `inst` ~~~c tm_unit_test_runner_o *inst; ~~~ User data for callback functions. #### `test_file()` ~~~c bool (*test_file)(tm_unit_test_runner_o *inst, const char *name); ~~~ Returns `true` if the tests in the file named `name` should run. You can use this to configure a runner to only run a subset of the tests. #### `test_custom()` ~~~c bool (*test_custom)(tm_unit_test_runner_o *inst, const char *name); ~~~ Returns `true` if the custom test with the specified `name` should be run. Custom tests are tests that don't run in every build (typically because they are expensive to run). #### `test_disk()` ~~~c bool (*test_disk)(tm_unit_test_runner_o *inst); ~~~ Returns `true` if the unit tests are allowed to touch the disk. If it returns `false`, disk tests should be skipped. #### `test_network()` ~~~c bool (*test_network)(tm_unit_test_runner_o *inst); ~~~ Returns `true` if the unit tests are allowed to access the network. If it returns `false`, network tests should be skipped. #### `test_slow_paths()` ~~~c bool (*test_slow_paths)(tm_unit_test_runner_o *inst); ~~~ Returns `true` if "slow" tests should run. The entire test suite of The Machinery should finish in a fraction of a section. If you have complicated tests that take longer, you should only run them when slow test paths are enabled. #### `record()` ~~~c bool (*record)(tm_unit_test_runner_o *inst, bool pass, const char *test_str, const char *file, uint32_t line); ~~~ Records the result of a unit test with the runner. * `pass` specifies if the test succeeded or not. * `test_str` is a string describing the test that will be printed in test reports. * `file` is the `__FILE__` where the test is located. * `line` is the `__LINE__` where the test is located. Returns the value of `pass`. #### `expect_error()` ~~~c void (*expect_error)(tm_unit_test_runner_o *inst, const char *err, const char *file, uint32_t line); ~~~ Tells the test runner to expect the error message `err`. Normally, a test runner does not expect any errors to occurs, so if a test logs an error (using `tm_error_i->errorf()`), the test is considered to have failed. However, sometimes you want to test that the error handling works and that an API produces a certain error when called in a certain way. To do that, you first call `expect_error()` with the error you expect and then run the specific unit test that should produce the error message. If the expected error message is written to `tm_error_i` before the next call to `record()`, the test is considered to have succeeded (produced the expected error message), otherwise, the test is considered to have failed (not produced the right error message). Note that to make this work, the unit test runner has to set up the `tm_error_api->def` interface to call into the unit test runner code. That way, it can intercept the `tm_error_i->errorf()` call and check if the error matches the expectations or not. For a sample implementation of how this can work, see `unit_test/unit_test.c`.
### `struct tm_unit_test_i`
Interface for unit tests. Plugins that want to implement a set of unit tests can register them using this interface. To find all unit test, query the API registry for `TM_UNIT_TEST_INTERFACE_NAME` implementations. !!! TIP Typically a plugin would register a single `tm_unit_test_i`, that runs all the unit tests for the plugin. You don't have to register a separate `tm_unit_test_i` for each individual unit test in the plugin. #### `name` ~~~c const char *name; ~~~ Name of this unit test. Typically, this is identical to the name of the plugin. #### `test()` ~~~c void (*test)(tm_unit_test_runner_i *tr, struct tm_allocator_i *a); ~~~ Callback that runs the unit tests, using the specified test runner. The supplied allocator can be used for any allocations that the unit test needs to make.
### `TM_UNIT_TEST_INTERFACE_NAME`
~~~c #define TM_UNIT_TEST_INTERFACE_NAME "tm_unit_test_i" ~~~
### `tm_basic_unit_test_runner`
A basic unit test runner that logs failed tests using the log system. ~~~c extern struct tm_unit_test_runner_i tm_basic_unit_test_runner; ~~~
### `TM_UNIT_TEST()`
~~~c #define TM_UNIT_TEST(tr, assertion) ~~~ Unit test macro. Tests the `assertion` using the test runner `tr`. In case of an error, a stringified version of the `assertion` is logged.
### `TM_UNIT_TESTF()`
~~~c #define TM_UNIT_TESTF(tr, assertion, format, ...) ~~~ As `TM_UNIT_TEST()`, but records a formatted string in case of error.
### `TM_EXPECT_ERROR()`
~~~c #define TM_EXPECT_ERROR(tr, error) ~~~ Macro for calling `expect_error()` with current `__FILE__` and `__LINE__`.