document the fault-coverage checker
[nobug] / doc / coverageintro.txt
1 HEAD- Fault coverage checking;;
2
3 CAUTION: Fault coverage checking is a experimental feature!
4
5 Nobug can automatically inject faults at instrumented points and permute
6 through all potential error paths of an application by restarting it with the
7 state from the former run. It can be used to give answers to the question if
8 any possible error is sufficiently handled in the application. Fault coverage
9 checking is only available in ALPHA builds and optimized out otherwise.
10
11 NOTE: This kind of testing is very expensive.
12
13 HEAD~ How does automatic fault injection work;;
14
15 First NoBug checks if the environment variable `NOBUG_COVERAGE` is set, if yes
16 it must contain a space, comma or semicolon separated list of filename which
17 are the logs from the previous run. This logs are then parsed for the states
18 of the previous run, storing these in a lookup tree.
19
20 After that the application proceeds as usual, when it then hits an
21 instrumented coverage point it is checked against the already recorded states.
22 Any so far unseen failure point injects a fault, the last seen but previously
23 failed point will be pass now, all other fault injection points act like on
24 their previous run. This ensures that each successive run of the application
25 changes only one injection point and thus permutes through all possible code
26 paths.
27
28 Fault injection points are identified by a 64bit hash over the backtrace
29 (return addresses on the stack) leading to it. This means each unique way to
30 reach a injection point is recorded. Parameters and threads are intentionally
31 not considered in this calculation.
32
33
34 HEAD~ How to invoke fault-coverage checking;;
35
36 Each fault-injection point emits a logging message about its identity and
37 state, this logging uses the normal NoBug logging facilities. Thus one can
38 control the logging with the `NOBUG_LOG` environment variable. Additionally
39 fault coverage checking is only active when the `NOBUG_COVERAGE` environment
40 variable was set to point some log files which are the results from the
41 previous run. NoBug comes with a `tests/coverage.sh` example script which
42 permutes through all possible error paths.
43