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