substack/tape — pull request #99 by malandrew (2014-08-15 00:30:45+00:00)
Title: Added t.diag() method to print yaml metadata

This pull requests implements a `t.diag()` method that takes JSON and can print out the json as a YAML block. FWIW this adds jeremyfa/yaml.js as a new dependency, but that dependency works in browsers.

This would close #91 but before we do, I think it may be worth discussing this a bit.

The [TAP specification](http://testanything.org/tap-version-13-specification.html) states:
```
After a test line a block of lines starting with '---' and ending with '...' will be interpreted as an inline YAML document providing extended diagnostic information about the preceding test.
```

This seems to imply that extended diagnostic information should be attached to the preceding test. Having a standalone `diag()` method in a way implies that the diagnostic information to be printed is standalone information.

Now, the way I see it, there are three options here:
* Keep this pull request the way it is. The downside is that the diagnostic information is not "attached" to the assertion in question. The upside is that this frees someone up to print that diagnostic information later, but before the next assertion is executed. The reasons for this may be that the diagnostic information is not available at the time the assertion is executed.
* Permit someone to add diagnostic information as a third argument, so that you could do `t.ok(true, 'Some message', someDiagnosticJSONObj)`. However, his approach would require quite a bit of reworking of `tape` since tape uses the third argument internally as an `extra` argument. This means that you'd have to do some whitelisting of the `extra` property object when you print it out.
* Allow both approaches.

Lastly, should we allow people to pass in YAML content directly into the `diag` method? AFAICT, the only thing necessary to do this is to check if the argument to `diag()` is a string or a plain old javascript object, and handle it accordingly.

Anyone have any strong thoughts here?

(FWIW I also looked into using `YAML.stringify` in the [`errorYAML` function](https://github.com/malandrew/tape/blob/87a882c83459c065e299fee1f27c31097897992c/lib/results.js#L149), but that didn't really work because it would YAMLize the `actual` and `expected` properties, even if they were JSON objects.)