the lightest yet the fastest javascript testing library
npm install zora
The library is a _regular_ Javascript module and can be directly imported from a CDN:
``Javascript
import {test} from 'https://unpkg.com/zora@latest/dist/index.js'
test(hello from zora, ({ok}) => {`
ok(true, 'it worked');
})
(Like in the following codepen)
Or installed via a package manager such NPM by running the command (assuming you have Nodejs installed on your machine):
npm i -D zora
You can then build your testing program by using the exported test function
`Javascript
import {test} from 'zora';
test(my very first test, (assertion) => {
const input = false;
assertion.ok(input, 'input should be truthy');
})
`
You can run the testing program (with node's runtime for example) and it will start reporting its execution into the console
test-output.tap
`TAP
TAP version 13my very first test
not ok 1 - input should be truthy
---
actual: false
expected: "truthy value"
operator: "ok"
at: " file:///path/to/sample.js:5:13"
...
1..1
`
This output format is called TAP (Test Anything Protocol). It is a standard text based format a machine can easily parse. It means there are plenty of reporters you can pipe the standard output stream into (not only in the Javascript world). This will help you to tailor the reporting for your particular needs.
for example, you can use tap-diff:node path/to/testing/program.js | tap-diff
You can even use basic bash command:
node path/to/testing/program.js | grep '^not ok\|^\s' will output a basic, straight to the point test report:
`
not ok 1 - input should be truthy
---
actual: false
expected: "truthy value"
operator: "ok"
at: " file:///path/to/sample.js:5:13"
...
That is the beauty of using different processes to run the testing program and to format its output: it remains very flexible.
When you start a test suite with the test function. The spec functions you pass as argument will get an instance of the Assertion object so you can write a wide range of different expectations.
For the best performances, all the spec functions run concurrently unless you specifically wait for them within an asynchronous function (if for some reason, you want to run some test one after the other, in a serial mode).
control-flow.js
`Javascript
import {test} from 'zora';
let state = 0;
test('test 1', t => {
t.ok(true);
state++;
});
test('test 2', t => {
//Maybe yes maybe no, you have no guarantee ! In this case it will work as everything is sync
t.equal(state, 1);
});
//Same thing here even in nested tests
test('grouped', t => {
let state = 0;
t.test('test 1', t => {
t.ok(true);
state++;
});
t.test('test 2', t => {
//Maybe yes maybe no, you have no guarantee ! In this case it will work as everything is sync
t.equal(state, 1);
});
});
//And
test('grouped', t=>{
let state = 0;
t.test('test 1', async t=>{
t.ok(true);
await wait(100);
state++;
});
test('test 2', t=>{
t.equal(state, 0, 'see the old state value as it will have started to run before test 1 is done');
});
});
//But
test('grouped', async t => {
let state = 0;
//specifically WAIT for the end of this test before moving on !
await t.test('test 1', async t => {
t.ok(true);
await wait(100);
state++;
});
test('test 2', t => {
t.equal(state, 1, 'see the updated value!');
});
});
`
You can _configure_ the testing program with environment variables. With nodejs, simply pass it with the command line:
ZORA_REPORTER=json node path/to/testing/program.js
In the browser, you have to set it as a global before the testing program runs:
`HTML`
By default, the output is a TAP stream; but you can decide to produce a stream defined by the zora json protocol messages if you which to build a custom reporter on top of it.
Beside the test function you can use the only function if you wish to skip all the other tests. However, from the testing program perspective, only is meaningless: it is just a convenience for a developer, locally on its machine.
So if you wish to use only you need to pass the ZORA_ONLY environment variable, otherwise the program will throw an exception to prevent only statement to slip in the remote versioning control system.
Beware that if you want to run only a nested test suite, all the parent test suites must use the only statement:
test-with-only.js
`Javascript
import {only, test} from 'zora';
test('will be skipped', t => {
t.ok(false);
})
only('some test', t => {
// will be skipped as well
t.test('some nested test', t => {
t.ok(false);
});
// will run
t.only('some other nested test', t => {
t.ok(true);
});
});
`
In milliseconds: change the default test timeout value (see below)
If a test hangs or takes too long to complete, it will report a failure. By default, the threshold is 5000ms. You can change that global value thanks to the ZORA_TIMEOUT environment variable.
You can change that value for a given text as well, thanks to the options object:
timeout example
`Javascript`
test(
'broken promise',
({ ok }) => {
return new Promise(() => {}).then(() => {
ok(true);
});
},
{ timeout: 500 }
);
You can skip a test using the root level skip function or within a test suite using the skip method of the assertion object
test-with-skip.js
`Javascript
import {skip, test} from 'zora';
skip('will be skipped', t => {
t.ok(false);
})
test('some test', t => {
// will be skipped as well
t.skip('some nested test', t => {
t.ok(false);
});
// will run
t.test('some other nested test', t => {
t.ok(true);
});
});
``