# Tap Monkey

## 🍌️🐒️

![Screencast of Tap Monkey in action. Terminal window. Command: npm -s test. Progress of tests being run is shown by a single-line animation of the emoji monkey heads alternating between see no evil, hear no evil, speak no evil poses as the titles of test collections being run and passing tests are shown alongside. At the end, an emoji banana is shown next to “All tests passing. Total: 163. Passing 163. Failing 0. Duration 14.19 secs.](https://small-tech.org/images/tap-monkey.gif)

A [tap](https://testanything.org/) formatter for [node:test](https://nodejs.org/api/test.html) that’s also a monkey.

Displays test runner status using a static single-line spinner (hint: it’s a monkey) and only fills your screen with text on failures and with your coverage report.

> If you’re looking for a version of Tap Monkey that works with [tape](https://github.com/substack/tape), please see the [1.x branch](https://codeberg.org/small-tech/tap-monkey/src/branch/tape-v1.x).

## Install

```sh
npm i @small-tech/tap-monkey
```

## Use

Pipe your tap test output to tap-monkey:

```sh
node --test --test-reporter test.js | npx tap-monkey
```

Or, as a test task in your _package.json_ file:

```json
"scripts" : {
  "test": "node --test --test-reporter=tap test.js | tap-monkey"
}
```

Or, if you have more than one test file:

```json
"scripts" : {
  "test": "node --test --test-reporter=tap 'tests/*.js' 'tests/lib/*.js' 'tests/routes/*.js' 'tests/middleware/*.js' 'tests/data/*.js' | tap-monkey"
}
```

## Accessibility

For a quieter monkey, use the `--quiet` flag. e.g.,

```json
"scripts" : {
  "test": "tape test/**/*js | tap-monkey --quiet"
}
```

When this flag is passed, only an initial notice is shown that tests are running and no further updates are given unless there are failures or until the final summary and/or coverage report are shown.

This is a general accessibility and usability feature. It might help folks using assistive devices like screen readers who might otherwise get overwhelmed by notifications of running/passing tests as well as anyone else who wants a generally calmer monkey.

## Code coverage

![Screenshot of Tap Monkey running coverage with a lovely coverage report surrounded by a single-line border with rounded corners drawn using box drawing characters.](https://small-tech.org/images/tap-monkey-coverage.png)

> 💡 Note that Node’s coverage support is experimental. Currently, the output doesn’t match Tape’s which means that the coverage reports in Tap Monkey won’t look perfect (the bordres of the table don’t align). I’m going to wait to see if Node fixes their whitespace issues before implementing a workaround as this is purely an aesthetic concern.

Use Tap Monkey for code coverage in exactly the same way as you do for your tests.

```json
"scripts" : {
  "coverage": "node --test --test-reporter=tap --experimental-test-coverage 'tests/*.js' | tap-monkey"
}
```

## Test failures

![Screenshot of Tap Monkey showing a failed test. Full test details, including a stack trace are shown. At the end are the aggregate statistics.](https://small-tech.org/images/tap-monkey-failed-test.png)

While passing tests are displayed ephemerally in the status line so as not to fill up your terminal window with unnecessary information, failed tests are always written in full to the terminal.

(When running tests, we don’t care about passing tests, only failing ones.)

## Debug output

The opposite of `--quiet` is `--debug`.

With this boolean option set, Tap Monkey will display all TAP comments (which are usually hidden).

Any console output that is generated by your program (e.g., from `console.log()` statements) is displayed in full and separate from the current test status line.

This is useful while debugging.

## Testing Tap Monkey

Tap Monkey itself, of course, comes with unit tests displayed by none other than _\*drumroll\*_ Tap Monkey!

### Run tests

```shell
npm run -s test
```

### Run coverage

```shell
npm run -s coverage
```

## Like this? Fund us!

[Small Technology Foundation](https://small-tech.org) is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share [our vision](https://small-tech.org/about/#small-technology) and want to support our work, please [become a patron or donate to us](https://small-tech.org/fund-us) today and help us continue to exist.

## Copyright

© 2021-present [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).

## License

AGPL version 3.0.