2 changed files with 237 additions and 217 deletions
@ -0,0 +1,229 @@ |
|||||
|
### Documentation |
||||
|
|
||||
|
## Index |
||||
|
|
||||
|
- ### `Class`: |
||||
|
- #### [`Gunner.constructor`](#new-gunner-options) |
||||
|
|
||||
|
- ### `Methods`: |
||||
|
- #### [`Gunner#test`](#gunnertest-title-implementation) |
||||
|
- #### [`Gunner#before`](#gunnerbefore-title-implementation) |
||||
|
- #### [`Gunner#after`](#gunnerafter-title-implementation) |
||||
|
- #### [`Gunner#run`](#gunnerrun-options) |
||||
|
|
||||
|
- ### `Constants`: |
||||
|
- #### `[Gunner.Start]` |
||||
|
- #### `[Gunner.End]` |
||||
|
|
||||
|
- ### [`State and Advanced Usage`](#state) |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## API |
||||
|
|
||||
|
### new Gunner (options) |
||||
|
|
||||
|
Creates a new Gunner instance. |
||||
|
|
||||
|
#### Options |
||||
|
|
||||
|
- **`name`** [default: undefined]: A name for this Gunner instance. |
||||
|
|
||||
|
#### Example |
||||
|
|
||||
|
```JavaScript |
||||
|
const gunner = new Gunner(options); |
||||
|
``` |
||||
|
|
||||
|
[`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. |
||||
|
|
||||
|
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. |
||||
|
|
||||
|
#### Example |
||||
|
|
||||
|
```JavaScript |
||||
|
gunner.test('sum should equal 3', expect => { |
||||
|
const sum = 1 + 2; |
||||
|
return expect(sum).equal(3); |
||||
|
}); |
||||
|
``` |
||||
|
|
||||
|
Expecting multiple results: |
||||
|
|
||||
|
```JavaScript |
||||
|
gunner.test('multiple expects should be true', expect => { |
||||
|
const a = 1 + 2; |
||||
|
const b = 'Hello World'; |
||||
|
|
||||
|
return ([ |
||||
|
expect(a).equal(3), |
||||
|
expect(b).equal('Goodbye World'), |
||||
|
]); |
||||
|
}); |
||||
|
``` |
||||
|
|
||||
|
Asynchronous tests: |
||||
|
|
||||
|
```JavaScript |
||||
|
gunner.test('asynchronous test', async expect => { |
||||
|
|
||||
|
const response = await axios.post(url, request); |
||||
|
const userObject = await db.find('userdetails', { username }); |
||||
|
|
||||
|
return [ |
||||
|
expect(response.status).equal(200); |
||||
|
expect(userObject).deepEquals(testUser); |
||||
|
]; |
||||
|
|
||||
|
}) |
||||
|
``` |
||||
|
|
||||
|
[`INDEX`](#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, with the exception that no expect object will be passed. |
||||
|
|
||||
|
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 |
||||
|
|
||||
|
```JavaScript |
||||
|
gunner.before('insert to db should not error', () => { |
||||
|
|
||||
|
// Clear db before test |
||||
|
return db.remove('users', { username: 'mkrhere' }); |
||||
|
|
||||
|
}); |
||||
|
|
||||
|
gunner.test('insert to db should not error', expect => { |
||||
|
|
||||
|
const user = await db.insert({ |
||||
|
username: 'mkrhere', |
||||
|
firstname: 'muthu', |
||||
|
}); |
||||
|
return expect(user).hasPair('firstname', 'muthu'); |
||||
|
|
||||
|
}); |
||||
|
``` |
||||
|
|
||||
|
[`INDEX`](#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 |
||||
|
|
||||
|
```JavaScript |
||||
|
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`](#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 |
||||
|
|
||||
|
```JavaScript |
||||
|
const options = { logs: true, trace: true }; |
||||
|
gunner.run(options); |
||||
|
``` |
||||
|
|
||||
|
[`INDEX`](#index) |
||||
|
|
||||
|
### State |
||||
|
|
||||
|
> `[ADVANCED]` |
||||
|
|
||||
|
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. |
||||
|
|
||||
|
This has four levels: |
||||
|
|
||||
|
- `'@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 |
||||
|
|
||||
|
```JavaScript |
||||
|
gunner.before(Gunner.Start, () => { |
||||
|
const db = DBModule.createDbConnection(); |
||||
|
return db; |
||||
|
}); |
||||
|
|
||||
|
gunner.before('test user should exist in db', state => { |
||||
|
|
||||
|
// Receives '@start' and '@every' states if exists |
||||
|
const db = state['@start'][0]; |
||||
|
|
||||
|
const testUser = await db.insert('users', { |
||||
|
username: 'mkrhere', |
||||
|
firstname: 'muthu', |
||||
|
}); |
||||
|
return testUser.username; |
||||
|
|
||||
|
}); |
||||
|
|
||||
|
gunner.test('test user should exist in db', (expect, 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 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`](#index) |
||||
|
|
||||
|
[`Back to README`](README.md) |
||||
Loading…
Reference in new issue