Yet another javascript testing library. This module was inspired by this article and node-tap. This library has a few subtle differences though based on these tenets.
- Asynchronicity should be supported by default.
- It should run correctly (I'm looking at you blue-tape).
- You shouldn't need a library to test if two things aren't equal.
assert(1 !== 2, 'something is wrong');
will work just fine. If you need to do deep comparisons or things of that nature, there are great utility libraries out there to help you with that. - You shouldn't have to tell the test framework how many tests or asserts you plan on running, and you shouldn't have to tell it when you are finished.
Installation: npm i --save-dev cupping
Say for example, you had the file test.js:
const cup = require('cupping');
// Syncrhonous test case
cup.test('One and one is two', () => {
console.assert(1 + 1 === 2);
});
// Asynchronous test cases
function delay() {
return new Promise(function (resolve) {
setTimeout(resolve, 1000);
});
}
cup.test('Should pass after 1 second', () => delay());
cup.test('Should fail after 1 second', () => (
delay().then(() => {
throw Error('Failed!');
})
));
Then simply call node test.js
. For more examples checkout out test/pass.js and test/fail.js.
Creates a new test case. Will not be run if process.env.CUP_ONLY
is set to a truthy value.
name
: {String}, The name or label for this test case.promise
: {Promise|function}, The code to be tested. The test case will be marked as succeeded or failed ifpromise
resolves or rejects, respectively. Ifpromise
is a function and it throws an error, the test case will be marked as failed. If the function is synchronous and no errors are thrown, the test case is marked as succeeded. Ifpromise
is an async function, it will only be marked as succeeded once it finishes. Ifpromise
is a function that returns a promise, the test case will be marked as succeeded or failed if the promise resolves or rejects, respectively.- returns: A
Promise
that is resolved or rejected if the test passed or failed respectively. In either case, it will resolve or reject with an object describing the result of the test case. The object will have the following keys:name
: {String}, The same as above.succeeded
: {Bool}, Whether or not the test case passed.reason
: {Any}, The reason the test case failed. Usually anError
or string. If the test case passed, it will beundefined
.
Same as test
but will still be run even if process.env.CUP_ONLY
is set to a truthy value.
Creates a new serial test case. Same as test
except that serial test cases with the same key
are run, one after the other, in the order that they are created. Series of test cases with different keys will be run in parallel with one another.
key
: {String}, A key to specify which series of test cases this test case belongs to.
Same as serial
but will still be run if process.env.CUP_ONLY
is set to a truthy value.
Decorator that is designed to wrap test functions that should throw an error synchronously. If fn
does not throw an error or a regex was provided and the error message does not match the provided regex then the test case will be marked as failed. Example Usage:
cup.test('Should pass', cup.shouldThrow(() => {
throw Error();
}));
cup.test('Should fail', cup.shouldThrow(() => null));
fn
: {function}, The test function to be wrapped.regex
: {regex}, Optional regex to ensure the correct error message is thrown.
Similiar to shouldThrow
except that it expects promise
to either be a Promise
or return a Promise
that will be rejected. shouldReject
also has the added caveat that the rejection reason should either be falsey or an instance of Error
.
promise
: {Promise|function}, The test promise to be wrapped.regex
: {regex}, Optional regex to ensure the correct error message is thrown.
An instance of the EventEmitter
class. It can be used to listen to cupping events using the emitter.on
method. All cupping events are passed the name of the test case as the only argument. The events are:
- start
- end
- success
- failure
There are also two environmental variables that can be set to control cupping behavior. Truthy values for environmental variables are considered to be as follows: ['1', 'true', 'True', 'TRUE', true]
. The last value is to allow for process.env.VAR = true;
within the test code.
If this value is truthy then only test cases created with testOnly
or serialOnly
will be run.
If this value is truthy then the process will exit after the first test failure.