supertape
v10.7.3
Published
๐ผ Supertape simplest high speed test runner with superpowers
Downloads
2,438
Maintainers
Readme
๐ผ Supertape
Tape-inspired TAP
-compatible simplest high speed test runner with superpowers.
๐ผ Supertape is a fast, minimal test runner with the soul of tape. 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 (take a look at mock-import for mocking and ๐ฉESCover for coverage)
a number of built-in pretty output formatters
the ability to extend
showing colored diff when using the
t.equal()
andt.deepEqual()
assertion operatorsdetailed stack traces for
async
functionsmultiple
test.only
'ssmart timeouts for long running tests ๐โโ๏ธ
more natural assertions:
expected, result
->result, expected
:t.equal(error.message, 'hello world', `expected error.message to be 'hello world'`);
๐ผ Supertape doesn't contain:
- assertion aliases, making the available operators far more concise
es3 code
and lot's of ponyfills;t.throws()
,t.doesNotThrow()
- use tryCatch or tryToCatch witht.equal()
instead;t.plan()
;
For a list of all built-in assertions, see Operators.
How ๐ผSupertape test looks like?
You can use both CommonJS and ESM, here is ESM example:
import {test} from 'supertape';
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 supertape -D
Usage
Usage: supertape [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 to3000
(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 to0
, exit with status code;SUPERTAPE_LOAD_LOOP_TIMEOUT
- timeout for load tests, defaults to5ms
, when mocha used as runner -50ms
optimal;
test('tape: error', (t) => {
t.equal(error.code, 'ENOENT');
t.end();
});
๐คท How to migrate from tape
?
You can convert your codebase from tape
to ๐ผSupertape
with help of ๐Putout
, which has built-in @putout/plugin-tape,
which has a lot of rules that helps to write tests.
Here is result example.
ESLint
rules
eslint-plugin-putout
has rules for ๐ผSupertape
:
Operators
The assertion methods of ๐ผ Supertape are heavily influenced by tape. However, to keep a minimal core of assertions, there are no aliases and some superfluous operators have been removed (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. To add custom assertion operators, see Extending.
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 loosely 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 deepEqual() algorithm with strict comparisons (===
) on leaf nodes
t.notDeepEqual(result: any, expected: any, message?: string)
Asserts that result
and expected
not loosely 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 deepEqual() algorithm with strict comparisons (===
) on leaf nodes
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()
)
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 |
|--------|-------|
| @supertape/operator-stub
| |
Formatters
There is a list of built-int formatters
to customize output:
| Package | Version |
|--------|-------|
| @supertape/formatter-tap
| |
| @supertape/formatter-fail
| |
| @supertape/formatter-short
| |
| @supertape/formatter-progress-bar
| |
| @supertape/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 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?)
Generate a new test that will be skipped over.
test.extend(extensions)
Extend base assertions with more:
const {extend} = require('supertape');
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
const test = require('supertape');
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",
+ }
`;
๐ชExit Codes
๐ผSupertape can have one of next exit codes:
| Code | Name | Description |
|------|------|-----------------|
| 0 | OK
| no errors found |
| 1 | FAIL
| test failed |
| 2 | WAS_STOP
| test was halted by user |
| 3 | UNHANDLED
| unhandled exception occurred |
| 4 | INVALID_OPTION
| wrong option provided |
| 5 | SKIPED
| works only with SUPERTAPE_CHECK_SKIPED
env variable when skiped files 1 and more |
Here is how exit code can look like:
import {SKIPED} from 'supertape/exit-codes';
const env = {
ESCOVER_SUCCESS_EXIT_CODE: SKIPED,
SUPERTAPE_CHECK_SKIPED: 1,
};
export default {
test: () => [env, `escover tape 'test/**/*.js' 'lib/**/*.spec.js'`],
};
License
MIT