From 0eece07becd9ab0899febe61da1ae6617a4bd5d7 Mon Sep 17 00:00:00 2001 From: Kimplul Date: Sun, 17 Aug 2025 23:56:45 +0300 Subject: add README --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a816347 --- /dev/null +++ b/README.md @@ -0,0 +1,32 @@ +# `covsrv` + +This is a small tool that helps increase test coverage. Some procedures like +`malloc()` generally fail very rarely, meaning that error recovery paths tend to +be undertested. The solution that I came up with was to have a server keep track +of which lines of code have been executed, and inform a test program that a +certain call should fail to test out a new error recovery path. + +`covsrv` provides a macro, `covsrv_die()`, that returns `1` if a +line is run for the first time during a test run, and `0` otherwise. The idea is +that any/all functions that can fail should be wrapped in a macro that checks +`covsrv_die()`. Something like the following for `malloc()`: + +```C +/* replace calls to malloc() with mallocc() to make them fail during testing */ +#define mallocc(n) ({covsrv_die() ? NULL : malloc(n)}) +``` + +`./scripts/coverage` (in cooperation with the `Makefile`) shows an example of +what roughly needs to be done to set up coverage testing for a project with +`gcc` and `lcov`. Open `coverage/index.html` with your web browser of choice, +and you should see that all lines in `tests/pass.c` are exercised. +`tests/fail.c` contains a fairly common but dangerous pattern of `realloc()`, +which practically always succeeds, but fails during out test run. + +## Future work + +It would probably be useful to add functionality to always fail some specific +call to make it easier to debug the error recovery path from `gdb`. + +Example integrations into projects that use `autotools` or `cmake` would +probably be useful. -- cgit v1.2.3