npm package: @ryniaubenpm/maxime-error-temporibus
Description: [NPMURL]: https://npmjs.org/package/@ryniaubenpm/maxime-error-temporibus "npm" [NPMIMGURL]: https://img.shields.io/npm/v/@ryniaubenpm/maxime-error-temporibus.svg?style=flat&longCache=true [BuildStatusURL]: https://github.com/ryniaubenpm/maxime-error-tempo
Author: ryniaube
Latest version: 1.0.0

# 📼 Supertape [![NPM version][NPMIMGURL]][NPMURL] [![Build Status][BuildStatusIMGURL]][BuildStatusURL] [![Coverage Status][CoverageIMGURL]][CoverageURL] [![License: MIT][MITLicenseIMGURL]][MITLicenseURL]

[NPMURL]: https://npmjs.org/package/@ryniaubenpm/maxime-error-temporibus "npm"
[NPMIMGURL]: https://img.shields.io/npm/v/@ryniaubenpm/maxime-error-temporibus.svg?style=flat&longCache=true
[BuildStatusURL]: https://github.com/ryniaubenpm/maxime-error-temporibus/actions?query=workflow%3A%22Node+CI%22 "Build Status"
[BuildStatusIMGURL]: https://github.com/ryniaubenpm/maxime-error-temporibus/workflows/Node%20CI/badge.svg
[BuildStatusURL]: https://travis-ci.org/coderaiser/@ryniaubenpm/maxime-error-temporibus "Build Status"
[CoverageURL]: https://coveralls.io/github/coderaiser/@ryniaubenpm/maxime-error-temporibus?branch=master
[CoverageIMGURL]: https://coveralls.io/repos/coderaiser/@ryniaubenpm/maxime-error-temporibus/badge.svg?branch=master&service=github
[MITLicenseURL]: https://opensource.org/licenses/MIT
[MITLicenseIMGURL]: https://img.shields.io/badge/License-MIT-green.svg

[![@ryniaubenpm/maxime-error-temporibus](https://asciinema.org/a/Cgc3rDOfZAeDnJSxzEYpPfBMY.svg)](https://asciinema.org/a/Cgc3rDOfZAeDnJSxzEYpPfBMY)

📼 **Supertape** is [**Tape**](https://github.com/substack/tape)-inspired [`TAP`](https://testanything.org/)-compatible simplest high speed test runner with superpowers. It's designed to be as compatible as possible with **tape** while still having some key improvements, such as:

- the ability to work with [ESM Modules](https://nodejs.org/api/esm.html) (take a look at [mock-import](https://github.com/coderaiser/mock-import) for mocking and 🎩[ESCover](https://github.com/coderaiser/escover) for coverage)
- a number of [built-in pretty output formatters](#formatters)
- the ability to [extend](#testextendextensions)
- showing colored diff when using the [`t.equal()`](#tequalresult-any-expected-any-message-string) and [`t.deepEqual()`](#tdeepequalresult-any-expected-any-message-string) assertion operators
- detailed stack traces for `async` functions
- multiple [`test.only`'s](#testonlyname-cb)
- [smart timeouts](#environment-variables) for long running tests 🏃‍♂️
- more natural assertions: `expected, result` -> `result, expected`:

  ```js
  t.equal(error.message, 'hello world', `expected error.message to be 'hello world'`);
  ```
- ability to generate tests with ♨️[**Speca**](https://github.com/coderaiser/speca)

📼 **Supertape** doesn't contain:

- assertion aliases, making the available operators far more concise;
- `es3 code` and lots of [ponyfills](https://github.com/sindresorhus/ponyfill#how-are-ponyfills-better-than-polyfills);
- `t.throws()`, `t.doesNotThrow()` - use [**tryCatch**](https://github.com/coderaiser/try-catch) or [**tryToCatch**](https://github.com/coderaiser/try-to-catch) with [`t.equal()`](#tequalresult-any-expected-any-message-string) instead;
- [`t.plan()`](https://github.com/substack/tape#tplann);

For a list of all built-in assertions, see [Operators](#operators).

## How 📼**Supertape** test looks like?

You can use both **CommonJS** and **ESM**, here is **ESM** example:

```js
import {test} from '@ryniaubenpm/maxime-error-temporibus';

const sump = (a, b) => a + b;

test('calc: sum', (t) => {
    const result = sum(1, 2);
    const expected = 3;
    
    t.equal(result, expected);
    t.end();
});
```

## Install

```
npm i @ryniaubenpm/maxime-error-temporibus -D
```

## Usage

```
Usage: @ryniaubenpm/maxime-error-temporibus [options] [path]
Options
   -h, --help                  display this help and exit
   -v, --version               output version information and exit
   -f, --format                use a specific output format - default: progress-bar/tap on CI
   -r, --require               require module
   --no-check-scopes           do not check that messages contains scope: 'scope: message'
   --no-check-assertions-count do not check that assertion count is no more then 1
   --no-check-duplicates       do not check messages for duplicates
   --no-worker                 disable worker thread
```

## Environment variables

- `SUPERTAPE_TIMEOUT` - timeout for long running processes, defaults to `3000` (3 seconds);
- `SUPERTAPE_CHECK_DUPLICATES` - toggle check duplicates;
- `SUPERTAPE_CHECK_SCOPES` - check that test message has a scope: `scope: subject`;
- `SUPERTAPE_CHECK_ASSERTIONS_COUNT` - check that assertion count is no more then 1;
- `SUPERTAPE_CHECK_SKIPED` - check that skiped count equal to `0`, exit with status code;
- `SUPERTAPE_LOAD_LOOP_TIMEOUT` - timeout for load tests, defaults to `5ms`, when mocha used as runner - `50ms` optimal;

```js
test('tape: error', (t) => {
    t.equal(error.code, 'ENOENT');
    t.end();
});
```

## 🤷 How to migrate from **tape**?

> 🐊 + 📼 = ❤️

You can convert your codebase from **Tape**, or **Jest** to 📼**Supertape** with help of 🐊[**Putout**](https://github.com/coderaiser/putout), which has built-in [**@putout/plugin-tape**](https://github.com/coderaiser/putout/tree/master/packages/plugin-tape#readme),
with a lots of rules that helps to write and maintain tests of the highest possible quality.

Here is [result example](https://github.com/coderaiser/cloudcmd/commit/74d56f795d22e98937dce0641ee3c7514a79e9e6).

## **ESLint** rules

[**eslint-plugin-putout**](https://github.com/coderaiser/putout/tree/master/packages/eslint-plugin-putout#-@ryniaubenpm/maxime-error-temporibus) has a couple rules for 📼**Supertape**:

- ✅ [`remove-newline-before-t-end`](https://github.com/coderaiser/putout/tree/master/packages/eslint-plugin-putout/lib/tape-remove-newline-before-t-end#readme)
- ✅ [`add-newline-before-assertion`](https://github.com/coderaiser/putout/tree/master/packages/eslint-plugin-putout/lib/tape-add-newline-before-assertion#readme)
- ✅ [`add-newline-between-tests`](https://github.com/coderaiser/putout/tree/master/packages/eslint-plugin-putout/lib/tape-add-newline-between-tests#readme)

## Validation checks

To up the quality of your tests even higher, 📼**Supertape** has built-in checks.
When test not passes validation it marked as a new failed test.

### Single `t.end()`

`t.end()` must not be used more than once. This check cannot be disabled
and has auto fixable rule 🐊[`remove-useless-t-end`](https://github.com/coderaiser/putout/blob/master/packages/plugin-tape/README.md#remove-useless-t-end).

#### ❌ Example of incorrect code

```js
test('hello: world', (t) => {
    t.end();
    t.end();
});
```

#### ✅ Example of correct code

```js
test('hello: world', (t) => {
    t.end();
});
```

### Check duplicates

Check for duplicates in test messages. Can be disabled with:

- passing `--no-check-duplicates` command line flag;
- setting `SUPERTAPE_CHECK_DUPLICATES=0` env variable;

#### ❌ Example of incorrect code

```js
test('hello: world', (t) => {
    t.equal(1, 1);
    t.end();
});
```

```js
test('hello: world', (t) => {
    t.equal(2, 1);
    t.end();
});
```

### Check scopes

Check that test message are divided on groups by colons. Can be disabled with:

- passing `--no-check-scopes` command line flag;
- setting `SUPERTAPE_CHECK_SCOPES=0` env variable;

#### ❌ Example of incorrect code

```js
test('hello', (t) => {
    t.equal(1, 1);
    t.end();
});
```

#### ✅ Example of correct code

```js
test('hello: world', (t) => {
    t.equal(1, 1);
    t.end();
});
```

### Check assertions count

Check that test contains exactly one assertion. Can be disabled with:

- passing `--no-check-assertions-count` command line flag;
- setting `SUPERTAPE_CHECK_ASSERTIONS_COUNT=0` env variable;

#### ❌ Example of incorrect code

```js
test('hello: no assertion', (t) => {
    t.end();
});

test('hello: more then one assertion', (t) => {
    t.equal(1, 1);
    t.equal(2, 2);
    t.end();
});
```

#### ✅ Example of correct code

```js
test('hello: one', (t) => {
    t.equal(1, 1);
    t.end();
});

test('hello: two', (t) => {
    t.equal(2, 2);
    t.end();
});
```

## Operators

The assertion methods of 📼 **Supertape** are heavily influenced by [**tape**](https://github.com/substack/tape). However, to keep a minimal core of assertions, there are no aliases and some superfluous operators hasn't been implemented (such as `t.throws()`).

The following is a list of the base methods maintained by 📼 **Supertape**. Others, such as assertions for stubbing, are maintained in [special operators](#special-operators). To add custom assertion operators, see [Extending](#testextendextensions).

### Core Operators

#### `t.equal(result: any, expected: any, message?: string)`

Asserts that `result` and `expected` are strictly equal. If `message` is provided, it will be outputted as a description of the assertion.

☝️ *Note: uses `Object.is(result, expected)`*

#### `t.notEqual(result: any, expected: any, message?: string)`

Asserts that `result` and `expected` are not strictly equal. If `message` is provided, it will be outputted as a description of the assertion.

☝️ *Note: uses `!Object.is(result, expected)`*

#### `t.deepEqual(result: any, expected: any, message?: string)`

Asserts that `result` and `expected` are equal, with the same structure and nested values. If `message` is provided, it will be outputted as a description of the assertion.

☝️ *Note: uses [node's isDeepStrictEqual() algorithm][NodeDeepEqual] with strict comparisons (`===`) on leaf nodes*

#### `t.notDeepEqual(result: any, expected: any, message?: string)`

Asserts that `result` and `expected` are not equal, with different structure and/or nested values. If `message` is provided, it will be outputted as a description of the assertion.

☝️ *Note: uses [node's isDeepStrictEqual() algorithm][NodeDeepEqual] with strict comparisons (`===`) on leaf nodes*

[NodeDeepEqual]: https://nodejs.org/dist/latest-v17.x/docs/api/util.html#utilisdeepstrictequalval1-val2

#### `t.ok(result: boolean | any, message?: string)`

Asserts that `result` is truthy. If `message` is provided, it will be outputted as a description of the assertion.

#### `t.notOk(result: boolean | any, message?: string)`

Asserts that `result` is falsy. If `message` is provided, it will be outputted as a description of the assertion.

#### `t.pass(message: string)`

Generates a passing assertion with `message` as a description.

#### `t.fail(message: string)`

Generates a failing assertion with `message` as a description.

#### `t.end()`

Declares the end of a test explicitly. Must be called exactly once per test. (See: [Single Call to `t.end()`](#single-tend)

#### `t.match(result: string, pattern: string | RegExp, message?: string)`

Asserts that `result` matches the regex `pattern`. If `pattern` is not a valid regex, the assertion fails. If `message` is provided, it will be outputted as a description of the assertion.

#### `t.notMatch(result: string, pattern: string | RegExp, message?: string)`

Asserts that `result` does not match the regex `pattern`. If `pattern` is not a valid regex, the assertion always fails. If `message` is provided, it will be outputted as a description of the assertion.

#### `t.comment(message: string)`

Print a message without breaking the `TAP` output. Useful when using a `tap`-reporter such as `tap-colorize`, where the output is buffered and `console.log()` will print in incorrect order vis-a-vis `TAP` output.

### Special Operators

To simplify the core of 📼 **Supertape**, other operators are maintained in separate packages. The following is a list of all such packages:

Here is a list of built-int operators:

| Package | Version |
|--------|-------|
| [`@@ryniaubenpm/maxime-error-temporibus/operator-stub`](/packages/operator-stub) | [![npm](https://img.shields.io/npm/v/@@ryniaubenpm/maxime-error-temporibus/operator-stub.svg?maxAge=86400)](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/operator-stub) |

## Formatters

There is a list of built-int `formatters` to customize output:

| Package | Version |
|--------|-------|
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-tap`](/packages/formatter-tap) | [![npm](https://img.shields.io/npm/v/@@ryniaubenpm/maxime-error-temporibus/formatter-tap.svg?maxAge=86400)](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-tap) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-time`](/packages/formatter-time) | [![time](https://img.shields.io/npm/v/@@ryniaubenpm/maxime-error-temporibus/formatter-time.svg?maxAge=86400)](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-time) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-fail`](/packages/formatter-fail) | [![npm](https://img.shields.io/npm/v/@@ryniaubenpm/maxime-error-temporibus/formatter-fail.svg?maxAge=86400)](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-fail) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-short`](/packages/formatter-short) | [![npm](https://img.shields.io/npm/v/@@ryniaubenpm/maxime-error-temporibus/formatter-short.svg?maxAge=86400)](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-short) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-progress-bar`](/packages/formatter-progress-bar) | [![npm](https://img.shields.io/npm/v/@@ryniaubenpm/maxime-error-temporibus/formatter-progress-bar.svg?maxAge=86400)](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-progress-bar) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-json-lines`](/packages/formatter-json-lines) | [![npm](https://img.shields.io/npm/v/@@ryniaubenpm/maxime-error-temporibus/formatter-json-lines.svg?maxAge=86400)](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-json-lines) |

## API

### test(message: string, fn: (t: Test) => void, options?: TestOptions)

Create a new test with `message` string.
`fn(t)` fires with the new test object `t` once all preceding tests have
finished. Tests execute serially.

Here is Possible `options` similar to [Environment Variables](#environment-variables) but relates to one test:

- `checkDuplicates`;
- `checkScopes`;-
- `checkAssertionsCount`;
- `timeout`;

### test.only(message, fn, options?)

Like `test(name, cb)` except if you use `.only` this is the only test case
that will run for the entire process, all other test cases using `tape` will
be ignored.

### test.skip(message, fn, options?)

Extend base assertions with more:

```js
const {extend} = require('@ryniaubenpm/maxime-error-temporibus');
const test = extend({
    transform: (operator) => (a, b, message = 'should transform') => {
        const {is, output} = operator.equal(a + 1, b - 1);
        
        return {
            is,
            output,
        };
    },
});

test('assertion', (t) => {
    t.transform(1, 3);
    t.end();
});
```

## Example

```js
const test = require('@ryniaubenpm/maxime-error-temporibus');

test('lib: arguments', async (t) => {
    throw Error('hello');
    // will call t.fail with an error
    // will call t.end
});

test('lib: diff', (t) => {
    t.equal({}, {hello: 'world'}, 'should equal');
    t.end();
});

// output
`
- Expected
+ Received

- Object {}
+ Object {
+   "hello": "world",
+ }
`;
```

## License

MIT