feat: add support for ignoring lines, functions, and blocks (bcoe#87)

Author: Benjamin E. Coe

README.md

@@ -44,20 +44,47 @@ To check thresholds on a per-file basis run:
 c8 check-coverage --lines 95 --per-file
 ```
 
+## Ignoring Uncovered Lines, Functions, and Blocks
+
+Sometimes you might find yourself wanting to ignore uncovered portions of your
+codebase. For example, perhaps you run your tests on Linux, but
+there's some logic that only executes on Windows.
+
+To ignore lines, blocks, and functions, use the special comment:
+
+`/* c8 ignore next */`.
+
+### Ignoring the next element
+
+```js
+const myVariable = 99
+/* c8 ignore next */
+if (process.platform === 'win32') console.info('hello world')
+```
+
+### Ignoring the next N elements
+
+```js
+const myVariable = 99
+/* c8 ignore next 3 */
+if (process.platform === 'win32') {
+  console.info('hello world')
+}
+```
+
+### Ignoring a block on the current line
+
+```js
+const myVariable = 99
+const os = process.platform === 'darwin' ? 'OSXy' /* c8 ignore next */ : 'Windowsy' 
+```
+
 ## Supported Node.js Versions
 
 c8 uses
 [bleeding edge Node.js features](https://github.com/nodejs/node/pull/22527),
 make sure you're running Node.js `>= 10.12.0`.
 
-## Goals of the Project
-
-A fully functional code coverage solution using only V8's native coverage
-features and minimal user-land modules, so that we fit these constraints:
-
-* No parsing of JavaScript code.
-* No mucking with Node.js' runtime environment.
-
 ## Contributing to `c8`
 
 See the [contributing guide here](./CONTRIBUTING.md).

package-lock.json

@@ -41,7 +41,7 @@
     "istanbul-reports": "^2.0.0",
     "rimraf": "^2.6.2",
     "test-exclude": "^5.0.0",
-    "v8-to-istanbul": "^3.0.1",
+    "v8-to-istanbul": "^3.1.1",
     "yargs": "^13.1.0",
     "yargs-parser": "^10.1.0"
   },

package.json

@@ -0,0 +1,22 @@
+const a = 99
+const b = true ? 1 /* c8 ignore next */ : 2
+if (true) {
+  console.info('covered')
+/* c8 ignore next 3 */
+} else {
+  console.info('uncovered')
+}
+
+/* c8 ignore next */
+if (false) console.info('uncovered')
+
+/* c8 ignore next 3 */
+function notExecuted () {
+
+}
+
+if (true) {
+  console.info('covered')
+} else { /* c8 ignore next */
+  console.info('uncovered')
+}

test/fixtures/c8-ignore-next.js

@@ -172,6 +172,20 @@ describe('c8', () => {
     })
   })
 
+  describe('/* c8 ignore next */', () => {
+    it('ignores lines with special comment', () => {
+      const { output } = spawnSync(nodePath, [
+        c8Path,
+        '--exclude="test/*.js"',
+        '--clean=false',
+        '--temp-directory=tmp/normal',
+        nodePath,
+        require.resolve('./fixtures/c8-ignore-next.js')
+      ])
+      output.toString('utf8').should.matchSnapshot()
+    })
+  })
+
   describe('source-maps', () => {
     beforeEach(cb => rimraf('tmp/source-map', cb))
 

test/integration.js

@@ -1,5 +1,19 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`c8 /* c8 ignore next */ ignores lines with special comment 1`] = `
+",covered
+covered
+-------------------|----------|----------|----------|----------|-------------------|
+File               |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
+-------------------|----------|----------|----------|----------|-------------------|
+All files          |    86.21 |    91.67 |    66.67 |    86.21 |                   |
+ async.js          |      100 |      100 |      100 |      100 |                   |
+ c8-ignore-next.js |    90.91 |      100 |      100 |    90.91 |             21,22 |
+ normal.js         |       75 |    66.67 |    33.33 |       75 | 14,15,16,18,19,20 |
+-------------------|----------|----------|----------|----------|-------------------|
+,"
+`;
+
 exports[`c8 ESM Modules collects coverage for ESM modules 1`] = `
 ",bar foo
 ------------|----------|----------|----------|----------|-------------------|