Tests

CCAN directories can have a test/ subdirectory. This directory generally contains C files and headers which can be divided into several categories:

• compile_ok*.c: These files are only for compile-checking, not execution. They are compiled to executables, but not run.
• compile_fail*.c: These files are for compile-checking, not execution. Note that they are first compiled without -DFAIL and expected to compile perfectly well, then compiled with -DFAIL and expected to fail. This ensures that the compile failure is caused by the thing being tested, not some random typo or systematic failure.
• run*.c: These files are compiled to executables, then run. Note that they are not linked with the code being tested: you should explicitly include ../<filename>.c. This allows you to unit test static functions within the C files, or test single C files rather than the whole collection of code. They should exit with status 0 if they succeed. Usually ccan/tap is used for the testing infrastructure.
• api*.c: Compiled to executables and run. Unlike run tests, these tests will be linked to the code in the main directory: these serve as usage examples and are expected to pass on future versions of the code. Thus a piece of code with API tests is providing some assurance that the API is stable.
• *.c: Every other C file gets compiled and linked in to every test. This allows you to write common test helper functions.

Note that tests are run in a temporary directory, but test/ is a symlink to the test directory, so you can access files that way.

The best way to run tests is to run ccanlint in the module directory.