- **`name`** [default: undefined]: A name for this Gunner instance.
- **`name`** [default: undefined]: A name for this Gunner instance or suite.
#### Example
```JavaScript
const gunner = new Gunner(options);
const gunner = new Gunner(name);
```
[`INDEX`](#index)
### Gunner#test (title, implementation)
Registers a new test. An `expect` object is passed into the implementation callback as the first argument. A test can have multiple expect statements. They should be returned as an array. The first expect to fail will cause the test to fail.
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` object is passed in as first argument, but any assertion module may be used, as long it either throws an error, or rejects. If you use a different assert module such as `chai`, remember to return Promises properly, else some Promises will be lost, just like in regular JavaScript.
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)](#state) is passed into the callback function.
Registers a new `before` hook. `before` hooks run before the selected test(s). The implementation callback is similar to that of a test, with the exception that no expect object will be passed.
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:
@ -101,20 +118,21 @@ The first argument can be one of:
#### Example
```JavaScript
gunner.before('insert to db should not error', () => {
gunner.before('insert to db should not error', async () => {
Additionally, `before` hooks create state objects from returned values that will be passed down hierarchically to other `before` and `after`hooks, and their matching tests. The state object is passed as second argument to tests. Hooks will also receive as the first argument state from hooks above itself.
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.
This has four levels:
State has four hierarchies:
- `'@start'` (from the `Gunner.Start` hooks).
- `'@every'` (from the `'*'` hooks).
@ -184,15 +202,18 @@ This has four levels:
#### Example
```JavaScript
gunner.before(Gunner.Start, () => {
const db = DBModule.createDbConnection();
return db;
});
gunner.before(
Gunner.Start,
() => DBModule.createDbConnection(),
'db'
);
gunner.before('test user should exist in db', state => {
gunner.before(
'test user should exist in db',
state => {
// Receives '@start' and '@every' states if exists
const db = state['@start'][0];
const db = state['@start'].db;
const testUser = await db.insert('users', {
username: 'mkrhere',
@ -200,14 +221,16 @@ gunner.before('test user should exist in db', state => {
});
return testUser.username;
});
},
'username'
);
gunner.test('test user should exist in db', (expect, state) => {
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'][0];
const username = state['@this'][0];
const db = state['@start'].db;
const username = state['@this'].username;
const user = await db.find('users', { username });
Create a new `Gunner` instance and simply write your tests. The assertion methods are passed in as the callback as an `expect` object to the test function.
