npm package: @prantlf/faucet
Description: Human-readable TAP reporter/formatter.
Author: Ferdinand Prantl
Latest version: 1.0.1

# @prantlf/faucet

[![Latest version](https://img.shields.io/npm/v/@prantlf/faucet)
 ![Dependency status](https://img.shields.io/librariesio/release/npm/@prantlf/faucet)
](https://www.npmjs.com/package/@prantlf/faucet)
[![Code coverage](https://codecov.io/gh/prantlf/faucet/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/faucet)

Human-readable TAP reporter/formatter.

This fork fixes issues [24] and [30] and includes the following changes:

* Trim too long assert messages to prevent line overflow
* Add `-v|--verbose` command line parameter and option to print succeeding assertions too
* Print total count of passed, failed, todo and skipped tests only if they are non-zero
* Print also todo and skipped tests, mismatch between planned and executed test count and bail-out message
* Format error information on multiple lines
* Fail the tests if no TAP output is printed on the console
* Switch `sprintf` out for `sprintf-js` (Chris Apparicio \<chris@apparicio.me\>)
* Upgrade the TAP parser
* Upgrade the rest of npm module dependencies

**Warning**: The upgraded TAP parser isn't compatible with the original version. The "comment" event is triggered with the comment including the "# " prefix. The "results" event was renamed to "complete". Further optimisations of the formatted output reduce unnecessary text and render errors in a more legible way.

# Examples

Pipe TAP text into the `faucet` command, get back pretty results:

![piping tap](images/test.gif)

You can use any runner you want to generate the TAP output. Here we'll use
[tape]:

![tape runner](images/falafel.gif)

You can give the `faucet` command a list of files:

![list of files](images/gutter.gif)

or if you just type `faucet`, any js files in `test/` or `tests/` will be run
using the `tape` command internally:

![implicit test/ directory](images/dnode.gif)

# Installation

To get the `faucet` command, with [npm], [pnpm] or [yarn] do:

```
npm i -g @prantlf/faucet
pnpm i -g @prantlf/faucet
yarn add -g @prantlf/faucet
```

# Generating TAP

The great thing about TAP is that it's inherently serializable on stdout, so you
can use whichever libraries you wish to generate it.

Many test libraries have ways to get TAP output.

[tape] and [tap] will give you TAP output by default.
Others like [mocha] or [tehanu] include reporters printing the TAP output.

With a [tape] test, you would just write a `test.js` like:

``` js
var test = require('tape');

test('beep boop', t => {
  t.plan(2);

  t.equal(1 + 1, 2);
  setTimeout(() => t.deepEqual('ABC'.toLowerCase().split(''), ['a','b','c']));
});
```

and then just run the file with `node test.js` to get the TAP output:

```
TAP version 13
# beep boop
ok 1 should be equal
ok 2 should be equivalent

1..2
# tests 2
# pass  2

# ok
```

or if you have a directory of files, you can use the `tape` command that you get
when you `npm i -g tape`:

```
$ tape test/*.js
TAP version 13
# stream in a stream
ok 1 should be equivalent
# expand a streams1 stream
ok 2 should be equivalent
# expand a streams2 stream
ok 3 should be equivalent
# expand a streams2 stream with delay
ok 4 should be equivalent

1..4
# tests 4
# pass  4

# ok

```

To get TAP out of [mocha], do `mocha -R tap`:

```
$ mocha -R tap
1..17
ok 1  shim found
ok 2  core shim not found
ok 3  false file
ok 4  false module
ok 5  local
ok 6  index.js of module dir
ok 7  alternate main
ok 8  string browser field as main
ok 9  string browser field as main - require subfile
ok 10  object browser field as main
ok 11  object browser field replace file
ok 12  object browser field replace file - no paths
ok 13  replace module in browser field object
ok 14  replace module in object browser field with subdirectory
ok 15  replace module in object browser field with subdirectory containing
package.json
ok 16  replace module in object browser field with subdirectory containing
package.json with string browser field as main
ok 17  replace module in object browser field with subdirectory containing
package.json with object browser field as main
# tests 17
# pass 17
# fail 0
```

Once you've got a way to get TAP out of your tests, just pipe into `faucet`:

![mocha pipe](images/mocha.gif)

# Usage

```
faucet [-v|--verbose] [-w|--width=<number>] [FILES]
command | faucet [-v|--verbose] [-w|--width=<number>]
```

## Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.

## License

Copyright (C) 2013-2019 James Halliday<br>
Copyright (C) 2019-2022 Ferdinand Prantl

Licensed under the [MIT License].

[MIT License]: http://en.wikipedia.org/wiki/MIT_License
[24]: https://github.com/substack/faucet/issues/24
[30]: https://github.com/substack/faucet/issues/30
[npm]: https://npmjs.org
[pnpm]: https://pnpm.io/
[yarn]: https://yarnpkg.com/
[tape]: https://npmjs.org/package/tape
[tap]: https://npmjs.org/package/tap
[mocha]: https://npmjs.org/package/mocha
[tehanu]: https://npmjs.org/package/tehanu