Add a code coverage guide.

Author: ben-eb

docs/recipes/code-coverage.md

@@ -0,0 +1,122 @@
+# Code coverage
+
+As AVA [spawns the test files][isolated-env], you can't use [`istanbul`] for
+code coverage; instead, you can achieve this with [`nyc`] which is basically
+[`istanbul`] with sub-process support. So, firstly we'll need to install it:
+
+```
+npm i nyc --save-dev
+```
+
+For both ES6 and ES5 environments, don't forget to add `.nyc_output` &
+`coverage` to your `.gitignore`.
+
+
+## ES6 coverage
+
+First, we'll need a babel configuration. This will vary from developer to
+developer but you can use this `.babelrc` as a starting point:
+
+```json
+{
+  "presets": ["es2015"],
+  "plugins": ["transform-runtime"],
+  "ignore": "test.js",
+  "env": {
+    "development": {
+      "sourceMaps": "inline"
+    }
+  }
+}
+```
+
+Note that in development mode, we need to specify a sourcemap when we transpile
+our code, and in production this is unnecessary. So for your production script,
+use an environment other than development; for example:
+
+```json
+{
+	"scripts": {
+		"build": "BABEL_ENV=production babel --out-dir=dist index.js"
+	}
+}
+```
+
+To cover ES6, simply prepend your test script with `nyc` and the `--babel` flag.
+We'll use the `text` reporter to give us a coverage report log after we run the
+tests, and the `lcov` reporter so that we can push the results to a hosted
+code coverage platform. This npm script will then handle our code coverage
+and testing:
+
+```json
+{
+  "scripts": {
+    "test": "nyc --babel --reporter=lcov --reporter=text ava test.js"
+  }
+}
+```
+
+
+## ES5 coverage
+
+To cover ES5, simply prepend your test script with `nyc`. We'll use the `text`
+reporter to give us a coverage report log after we run the tests, and the `lcov`
+reporter so that we can push the results to a hosted code coverage platform.
+This npm script will then handle our code coverage and testing:
+
+```json
+{
+  "scripts": {
+    "test": "nyc --reporter=lcov --reporter=text ava test.js"
+  }
+}
+```
+
+
+## HTML reports
+
+To see a HTML report for either the ES6 or ES5 coverage strategies we have
+outlined, do:
+
+```
+nyc report --reporter html
+```
+
+Or, convert it into an npm script for less typing:
+
+```json
+{
+  "scripts": {
+    "report": "nyc report --reporter html"
+  }
+}
+```
+
+This will output a HTML file to the `coverage` directory.
+
+
+## Hosted coverage
+
+### Travis CI & Coveralls
+
+Add [`coveralls`] as a development dependency:
+
+```
+npm i coveralls --save-dev
+```
+
+Then add the following to your `.travis.yml`:
+
+```
+after_script:
+  - 'cat coverage/lcov.info | ./node_modules/.bin/coveralls'
+```
+
+Your coverage report will then appear on coveralls shortly after the CI
+service completes.
+
+[`babel`]:      https://github.com/babel/babel
+[`coveralls`]:  https://github.com/nickmerwin/node-coveralls
+[isolated-env]: https://github.com/sindresorhus/ava#isolated-environment
+[`istanbul`]:   https://github.com/gotwarlost/istanbul
+[`nyc`]:        https://github.com/bcoe/nyc