gotwarlost/istanbul — pull request #130 by gotwarlost (2013-12-19 03:47:26+00:00)
Title: Allow parts of code to be skipped for the purposes of coverage reporting

1. Coverage can be explicitly skipped using comments. There is no automatic pattern match of expressions to determine if they should be skipped for coverage.
2. A coverage skip hint looks like `/* istanbul ignore [non-word] [optional-docs] */`
3. For `if` conditions you can say `/* istanbul ignore if */` or `/* istanbul ignore else */` and that will end up ignoring whichever path was required to be ignored.
4. For all other cases, the Swiss army knife `/* istanbul ignore next */` may be used which skips the "next thing" in the source code
5. The "next" thing may be, among other things:
* A JS statement (including assignments, ifs, loops, switches, functions) in which case all of the the statement is ignored for all forms of coverage.
* A switch case statement, in which case the particular case is ignored for branch coverage and its contents ignored for all forms
* A conditional inside a ternary expression in which case the branch is ignored
* A part of a logical expression in which case that part of the expression is ignored for branch coverage
6. It is up to the caller to scope this as narrowly as possible. For example, if you have a source file that is wrapped in a function expression, adding `/* istanbul ignore next */` at the top of the file will ignore the whole file!

When some part of the JS is considered skipped, nothing actually happens in terms of changes to the instrumentation. Everything is calculated as though nothing was skipped - all that changes is that there is a `skip` attribute added to the metadata of the statement, function or branch as applicable.

Coverage reporting however takes the `skip` attribute into account and artificially increments counts, when 0 and skipped to pretend that the thing in question was covered. The HTML report shows the coverage after taking skips into account but at the same time colors the skipped statements with a gray color for easy visual scan.

The HTML and text summary reports shows ignore counts for completeness.