doc/coverageintro.txt

   1 HEAD- Fault coverage checking;;
   2
   3 CAUTION: Fault coverage checking is an 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 a former run. It can be used to provide information on whether a
   8 particular error is adequately treated in an application. Fault coverage
   9 checking is only available in ALPHA builds; it is optimized out in all other
  10 builds.
  11
  12 NOTE: This kind of testing is very expensive on performance.
  13
  14 HEAD~ How Does Automatic Fault Injection Work?;;
  15
  16 First, NoBug checks if the `NOBUG_COVERAGE` environment variable is set. If it
  17 is set, it must contain a space, comma or a semicolon separated list of
  18 filenames which are the logs from a previous run. These logs are then parsed
  19 storing the old state in a lookup tree.
  20
  21 The application will then proceed to run as usual. When an instrumented
  22 coverage point is hit, its status is checked against all states that have been
  23 recorded previously. Any failure point that is encountered for a first time
  24 causes a fault to be injected; the last seen but previously failed point will
  25 now be passed, all other fault injection points behave as in their previous
  26 run. This ensures that each successive run of the application changes only one
  27 injection point and, thus, permutes through all possible code paths.
  28
  29 Fault injection points are identified by a 64bit hash over the backtrace
  30 (return addresses on the stack) leading to it. This means each unique way to
  31 reach an injection point is recorded. Parameters and threads are intentionally
  32 not considered in this calculation.
  33
  34
  35 HEAD~ How to Invoke Fault-Coverage Checking;;
  36
  37 Each fault-injection point emits a logging message about its identity and
  38 state, this logging uses the normal NoBug logging facilities. Thus, one can
  39 control logging with the `NOBUG_LOG` environment variable. Furthermore, fault
  40 coverage checking is only active when the `NOBUG_COVERAGE` environment
  41 variable has been set to point to log files which are the results from a
  42 previous run. NoBug comes with a `tests/coverage.sh` example script which
  43 permutes through all possible error paths.
  44