@ryniaubenpm/maxime-error-temporibus
Version:
[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
386 lines (267 loc) ā¢ 15.3 kB
Markdown
# š¼ 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
[](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) | [](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) | [](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-tap) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-time`](/packages/formatter-time) | [](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-time) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-fail`](/packages/formatter-fail) | [](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-fail) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-short`](/packages/formatter-short) | [](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-short) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-progress-bar`](/packages/formatter-progress-bar) | [](https://www.npmjs.com/package/@@ryniaubenpm/maxime-error-temporibus/formatter-progress-bar) |
| [`@@ryniaubenpm/maxime-error-temporibus/formatter-json-lines`](/packages/formatter-json-lines) | [](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