@kogs/test

@kogs/test

@kogs/test is a simple unit testing library for Node.js. Import the library and use the test.run() function to execute your tests. When you're done, call test.results() to get a summary of the results.

Installation

npm install @kogs/test

To run the tests with npm test, add a test script to your package.json file. For example:

"scripts": {
	"test": "node test.mjs"
}

Usage

import test from '@kogs/test';
// or
import { run, results, capture } from '@kogs/test';

// test.run() returns a promise which you can await to
// execute each test in series.
await test.run(() => {
	throw new Error('This test will fail.');
});

// If you want to run multiple tests in parallel, you don't
// need to await each one.
test.run(async () => {
	// The internal function can be asynchronous too.
	await someAsyncFunction();
});

// By default, the tests will be named "Test #1", "Test #2", etc. If you provide a named function, the name will be used instead.
test.run(function myTest() {
	// This test will appear as "myTest" in the results.
});

// You can also provide a name as a second argument.
test.run(() => {
	// This test will appear as "My Other Test" in the results.
}, 'My Other Test');

// `test.results()` returns a promise which resolves when all tests have completed and writes a final summary to the console.
await test.results();

// > [x] Test #1 failed after 0ms :: This test will fail. (at test.mjs:6:8)
// > [✓] Test #2 passed after 3ms.
// > [✓] myTest passed after 1ms.
// > [✓] My Other Test passed after 1ms.
// >
// > 3 passed, 1 failed after 5ms.

For some testing, it may be beneficial to capture the console output. You can do this using the test.capture() function, which takes a function as an argument.

The provided function will receive two arguments: stdout and stderr. These are arrays which chunks written to process.stdout and process.stderr will be pushed to. You can use these to verify that your code is logging the correct messages.

Note: While tests can be run in parallel, it's recommended to run them in series when using test.capture(), otherwise the output may be mixed up.

await test.run(async () => {
	await test.capture((stdout, stderr) => {
		console.log('This will be captured.');
		
		let a = stdout.pop();
		// a -> 'This will be captured.\n'

		console.log('This will be captured too.');
		let b = stdout.pop();
		// b -> 'This will be captured too.\n'

		console.error('This will go to stderr');
		let c = stderr.pop();
		// c -> 'This will go to stderr\n'
	});
});

Alternatively, instead of checking the arrays inside the capture function, they are also returned from the test.capture() function so you can process them later.

await test.run(() => {
	// The capture function can also be asynchronous.
	const { stdout, stderr } = await test.capture(async () => {
		await someAsyncFunction();
		console.log('This will be captured.');
		console.error('This will go to stderr');
	});

	// stdout -> ['This will be captured.\n']
	// stderr -> ['This will go to stderr\n']
});

License

The code in this repository is licensed under the ISC license. See the LICENSE file for more information.