Make the reporter reusable and document it

Author: zoubin

README.md

@@ -1,20 +1,18 @@
 # tap-summary
-Summarize TAP.
-
 [![version](https://img.shields.io/npm/v/tap-summary.svg)](https://www.npmjs.org/package/tap-summary)
 [![status](https://travis-ci.org/zoubin/tap-summary.svg?branch=master)](https://travis-ci.org/zoubin/tap-summary)
 [![dependencies](https://david-dm.org/zoubin/tap-summary.svg)](https://david-dm.org/zoubin/tap-summary)
 [![devDependencies](https://david-dm.org/zoubin/tap-summary/dev-status.svg)](https://david-dm.org/zoubin/tap-summary#info=devDependencies)
 
-## Usage
+A reporter for TAP.
 
-```javascript
-var reporter = require('tap-summary')()
+## Example
 
-```
+![summary](example/clip.gif)
 
-or in `package.json`
+## Usage
 
+### package.json
 ```json
 {
   "scripts": {
@@ -30,6 +28,84 @@ or in `package.json`
   --no-progress    Disable progress output during tests
 ```
 
-## Example
+### API
 
-![summary](example/clip.gif)
+```js
+var summarize = require('tap-summary')
+
+var fs = require('fs')
+fs.createReadStream('test.tap')
+  .pipe(summarize({
+    ansi: true,
+    progress: true,
+  }))
+  .pipe(process.stdout)
+
+```
+
+Also, the default formatter could be replaced with custom ones.
+
+```js
+var reporter = require('tap-summary').reporter()
+
+var fs = require('fs')
+fs.createReadStream('test.tap')
+  .pipe(customize(reporter))
+  .pipe(process.stdout)
+
+```
+
+The `reporter` is a `Duplex`,
+which consumes the TAP input and output nothing by default.
+However, it emits the following events during the process,
+so that `customize` could listen to them and add something into the output.
+
+* reporter.on('test.start', test => {}).
+  Fired when a new test detected.
+* reporter.on('test.end', test => {}).
+  Fired when the end of a test reached.
+* reporter.on('test.assert', (assertion, test) => {}).
+  Fired when a new assertion found.
+* reporter.on('summary', (stats, fails, comments) => {}). 
+  Fired when all TAP input has been processed.
+
+Details about the `test` and `assertion` object could be found [here][tap-out].
+
+The `stats` object:
+```js
+var stats = {
+  // the total time (ms) it takes
+  duration: duration,
+  // the total number of assertions planned
+  planned: res.plans.reduce(function (p, c) {
+    return c.to - c.from + 1 + p;
+  }, 0),
+  // the actual total number of assertions found
+  assertions: res.asserts.length,
+  // the number of successful assertions
+  pass: res.pass.length,
+  // the number of failed assertions
+  fail: res.fail.length,
+  // the number of comments found
+  comments: res.comments.length,
+}
+
+```
+
+`fails` will be `null` unless `stats.fail > 0`:
+```js
+{ 
+  testName: [failedAssertion]
+}
+
+```
+
+`comments` will be `null` unless `stats.comments > 0`:
+```js
+{ 
+  testName: [comment]
+}
+
+```
+
+[tap-out]: https://github.com/scottcorgan/tap-out

example/unnamed-test.js

@@ -2,9 +2,7 @@ var reporter = require('./lib/reporter')
 var Formatter = require('./lib/formatter')
 
 module.exports = function (opts) {
-  return reporter(new Formatter(opts))
+  return new Formatter(opts).init(reporter())
 }
-module.exports.Formatter = Formatter
 module.exports.reporter = reporter
-module.exports.parser = require('./lib/parser')
-
+module.exports.Formatter = Formatter

index.js

@@ -16,11 +16,9 @@ Formatter.prototype.init = function (reporter) {
   var self = this
 
   reporter.push(LF + this.splitter(' Tests '))
-
   reporter.on('test.start', function (test) {
     Object.defineProperty(test, 'title', { get: getTitle })
   })
-
   function getTitle() {
     return this.name + ' [' +
       'pass: ' + this.pass + ', fail: ' + this.fail +
@@ -32,15 +30,24 @@ Formatter.prototype.init = function (reporter) {
     reporter.on('test.start', function (test) {
       this.push(LF + self.format('# ' + test.title, 'cha.eraseLine'))
     })
-
-    reporter.on('test.pass', function (test) {
-      this.push(self.format('# ' + test.title, 'cha.eraseLine'))
-    })
-
-    reporter.on('test.fail', function (test) {
+    reporter.on('test.assert', function (assertion, test) {
       this.push(self.format('# ' + test.title, 'cha.eraseLine'))
     })
   }
+
+  reporter.on('test.end', function (test) {
+    this.push(self.test(test))
+  })
+  reporter.on('summary', function (stats, fails, comments) {
+    this.push(self.summary(stats))
+    if (fails) {
+      this.push(self.fail(fails))
+    }
+    if (comments) {
+      this.push(self.comment(comments))
+    }
+  })
+  return reporter
 }
 
 Formatter.prototype.summary = function (summary) {