DOCUMENTATION.md

Documentation

Index

• Class:

  • Gunner.constructor

• Methods:

  • Gunner#test

  • Gunner#before

  • Gunner#after

  • Gunner#run

• Constants:

  • [Gunner.Start]

  • [Gunner.End]

• State and Advanced Usage

---

API

new Gunner (options)

Creates a new Gunner instance.

Options

• name [default: undefined]: A name for this Gunner instance or suite.

Example

const gunner = new Gunner(name);

INDEX

Gunner#test (title, implementation)

Registers a new test. A test can have multiple expect statements by using expectMany. The first expect to fail will cause the test to fail.

The expect function exported with Gunner is expected to be called and returned, but any assertion module may be used, as long it either throws an error, or you return the rejection. If you use a different assert module such as chai, remember to return Promises properly, else you may have false positives as tests will pass, but failures will become unhandledRejections.

A state object (explained below) is passed into the callback function.

Example

const { Gunner, expect } = require('@klenty/gunner');

gunner.test('sum should equal 3', () => {

	const sum = 1 + 2;
	return expect(sum).equal(3);

});

You can also pass a function with parameters to be called with:

const { Gunner, expect } = require('@klenty/gunner');
const sum = (a, b) => a + b;

gunner.test('sum should equal 3', () => expect(sum, [ 1, 2 ]).equal(3));

Expecting multiple results:

const { Gunner, expect, expectMany } = require('@klenty/gunner');

gunner.test('multiple expects should be true', () => {

	const a = 1 + 2;
	const b = 'Hello World';

	return expectMany(
		expect(a).equal(3),
		expect(b).equal('Goodbye World'),
	);

});

Asynchronous tests:

gunner.test('asynchronous test', async () => {

	const response = await axios.post(url, request);
	const userObject = await db.find('userdetails', { username });

	await expect(response.status).equal(200);
	await expect(userObject).deepEquals(testUser);

})

INDEX

Gunner#before (title, implementation)

Registers a new before hook. before hooks run before the selected test(s). The implementation callback is similar to that of a test. state will accumulate over multiple hooks. The third parameter is a label to store to state. Multiple hooks with the same label will override, and hooks without labels will not contribute to state.

The first argument can be one of:

• title of a test, which causes the hook to run once before the mentioned test

• '*', which causes the hook to run once before every test

• either of the constants: Gunner.Start, and Gunner.End.

gunner.before(Gunner.Start, () => {}) will run once before Gunner starts running any tests. The Gunner.End equivalent will run once after running all tests (before ending).

Example

gunner.before('insert to db should not error', async () => {

	// Clear db before test
	await db.remove('users', { username: 'mkrhere' });

});

gunner.test('insert to db should not error', async () => {
	
	const user = await db.insert({
		username: 'mkrhere',
		firstname: 'muthu',
	});

	await expect(user).hasPair('firstname', 'muthu');

});

INDEX

Gunner#after (title, implementation)

Registers a new after hook. after hooks run after the corresponding test(s). The implementation callback is similar to that of a test, with the exception that no expect object will be passed.

The first argument is similar to Gunner#before, but does not accept Gunner.Start and Gunner.End constants, only '*' or test description.

Example

gunner.test('insert to db should not error', expect => {
	
	const user = await db.insert({
		username: 'mkrhere',
		firstname: 'muthu',
	});
	return expect(user).hasPair('firstname', 'muthu');

});

gunner.after('insert to db should not error', () => {

	// Clear db after test
	return db.remove('users', { username: 'mkrhere' });

});

INDEX

Gunner#run (options)

Starts running Gunner tests. Takes an options object as optional parameter.

Options

• log [default: true]: Turn logs on or off (returns array of results)
• trace [default: false]: Turn stack traces on or off

Example

const options = { logs: true, trace: true };
gunner.run(options);

INDEX

State

[ADVANCED]

Additionally, hooks contribute to the state object with their return values that will be passed down hierarchically to other hooks, and their matching tests. The state object is passed as the first argument to all tests and hooks. State can only be created by hooks, by passing a label as the third argument.

State has four hierarchies:

• '@start' (from the Gunner.Start hooks).
• '@every' (from the '*' hooks).
• '@this' (from the hook registered to this test).
• '@results' (results from all tests, passed only to the Gunner.End hook).

Example

gunner.before(
	Gunner.Start,
	() => DBModule.createDbConnection(),
	'db'
);

gunner.before(
	'test user should exist in db',
	state => {

		// Receives '@start' and '@every' states if exists
		const db = state['@start'].db;

		const testUser = await db.insert('users', {
			username: 'mkrhere',
			firstname: 'muthu',
		});
		return testUser.username;

	},
	'username'
);

gunner.test('test user should exist in db', state => {

	// Receives '@start', '@every', and '@this' states
	// Each state level is an array because multiple hooks may exist per level
	const db = state['@start'].db;
	const username = state['@this'].username;

	const user = await db.find('users', { username });
	return expect(user).hasPair('firstname', 'muthu');

});

gunner.after('test user should exist in db', state => {

	const db = state['@start'][0];
	const db = state['@this'][0];

	return db.remove('users', { username });

});

INDEX

Back to README