63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
|
Contents
|
||
|
|
========
|
||
|
|
- [Rationale](#rationale)
|
||
|
|
- [Usage](#usage)
|
||
|
|
- [Writing Tests](#writing_tests)
|
||
|
|
|
||
|
|
## Rationale
|
||
|
|
The purpose of this package is both practical and as a demonstration for just how
|
||
|
|
simple a test harness can be, in order to encourage both more testing in C code
|
||
|
|
as well as the use of simple tools. As such, the **Roadrunner** test runner consists
|
||
|
|
of a test runner written in a single file of highly portable C, totaling 43 lines,
|
||
|
|
and a simple, POSIX compatible Makefile which works with both GNU and BSD make.
|
||
|
|
|
||
|
|
The original version of this project was written entirely in POSIX make, but due to
|
||
|
|
the variations in POSIX shell behavior, especially in regards to the variety of ways
|
||
|
|
that both the built in *echo* command and */bin/echo* screw up sending terminal escape
|
||
|
|
sequences, something more robust and portable was desirable. There were simply too
|
||
|
|
many corner cases to be bothered to find them all.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
The best way to use this is to stuff it into a `test` subdirectory and call it via
|
||
|
|
`make -C test`, or invoke it from your project's `Makefile` as a sub-make. If you
|
||
|
|
are using something other than plain *make* to build your project then you probably
|
||
|
|
don't want this, but also, why? That said, let's not get sidetracked.
|
||
|
|
|
||
|
|
The example Makefile also goes into the `test` subdirectory, and you will want to add
|
||
|
|
the name of the library that you are testing on the appropriate line as well as the
|
||
|
|
names of all of the tests that you wish to run. Add those to the `tests` array.
|
||
|
|
```Makefile
|
||
|
|
tests += my_test
|
||
|
|
```
|
||
|
|
For each member of `tests` there should be a corresponding file `<testname>.c` which
|
||
|
|
will be compiled when you run `make` in this directory, along with the small helper
|
||
|
|
program `runner.c`. Make will then invoke `./runner` with the list of tests as it's
|
||
|
|
arguments. The *runner* program will keep track of successes and failures, as well
|
||
|
|
as skipped tests, giving colored output and a nice summary at the end. If there are
|
||
|
|
no failures the program exits with a value of **0**, otherwise the number of failures
|
||
|
|
is returned.
|
||
|
|
|
||
|
|
Your library will have to be built as a static library and statically linked to each
|
||
|
|
test program. All you have to do (after building the static library) is add it to
|
||
|
|
the `$(LDLIBS)` array in the Makefile.
|
||
|
|
|
||
|
|
## Writing Tests
|
||
|
|
### Return values
|
||
|
|
The return values for each test shouuld follow these conventions.
|
||
|
|
- 0 for success
|
||
|
|
- 255 or -1 indicates this test was skipped
|
||
|
|
- any other value indicates failure
|
||
|
|
|
||
|
|
### Skips
|
||
|
|
If your test requires elevated privileges, you can simply test for uid == 0 and then
|
||
|
|
bail with code 255 if the runner is run by a different user. Similarly, if your test
|
||
|
|
needs the network then you can test programmatically for a working connection and bail
|
||
|
|
with 255 if it isn't available.
|
||
|
|
|
||
|
|
### Don't use *assert*
|
||
|
|
The `assert` function from `assert.h` will not cause your test to fail, because it
|
||
|
|
simply aborts the program after printing a message to stderr. Instead, check for
|
||
|
|
proper results and return an exit code if the test fails. You can also print error
|
||
|
|
messages in your tests, which *runner* will capture, assume it means failure, and
|
||
|
|
print to stderr in the terminal session.
|