From 86aff9c79f3d1776a162c119428dc67f22e4fb89 Mon Sep 17 00:00:00 2001 From: Muthu Kumar Date: Mon, 17 Sep 2018 13:28:26 +0530 Subject: [PATCH] [docs] Update docs to version 0.9.4 --- DOCUMENTATION.md | 95 +++++++++++++++++++++++++++++++++++--------------------- README.md | 17 +++++----- package.json | 2 +- src/gunner.js | 2 +- 4 files changed, 70 insertions(+), 46 deletions(-) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index b1a4dc0..d1672cd 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -27,57 +27,74 @@ Creates a new Gunner instance. #### Options -- **`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. #### Example ```JavaScript -gunner.test('sum should equal 3', expect => { +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: + +```JavaScript +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: ```JavaScript -gunner.test('multiple expects should be true', expect => { +const { Gunner, expect, expectMany } = require('@klenty/gunner'); + +gunner.test('multiple expects should be true', () => { + const a = 1 + 2; const b = 'Hello World'; - return ([ + return expectMany( expect(a).equal(3), expect(b).equal('Goodbye World'), - ]); + ); + }); ``` Asynchronous tests: ```JavaScript -gunner.test('asynchronous test', async expect => { +gunner.test('asynchronous test', async () => { const response = await axios.post(url, request); const userObject = await db.find('userdetails', { username }); - return [ - expect(response.status).equal(200); - expect(userObject).deepEquals(testUser); - ]; + await expect(response.status).equal(200); + await expect(userObject).deepEquals(testUser); }) ``` @@ -86,7 +103,7 @@ gunner.test('asynchronous test', async expect => { ### 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. +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 () => { // Clear db before test - return db.remove('users', { username: 'mkrhere' }); + await db.remove('users', { username: 'mkrhere' }); }); -gunner.test('insert to db should not error', expect => { +gunner.test('insert to db should not error', async () => { const user = await db.insert({ username: 'mkrhere', firstname: 'muthu', }); - return expect(user).hasPair('firstname', 'muthu'); + + await expect(user).hasPair('firstname', 'muthu'); }); ``` @@ -172,9 +190,9 @@ gunner.run(options); > `[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. +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,30 +202,35 @@ 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]; + // 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; + const testUser = await db.insert('users', { + username: 'mkrhere', + firstname: 'muthu', + }); + 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 }); return expect(user).hasPair('firstname', 'muthu'); diff --git a/README.md b/README.md index 1ff1e87..c7973fc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Gunner -Django Unchained +Django Unchained #### _Tiny, but fully loaded._ @@ -13,11 +13,12 @@ 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. ```JavaScript +const { Gunner, expect } = require('@klenty/gunner'); // Create new instance const gunner = new Gunner(); // Define tests -gunner.test('arrays are equal', expect => { +gunner.test('arrays are equal', () => { return expect([1, 2,]).deepEqual([1 ,2]); }); @@ -28,19 +29,19 @@ gunner.run(); ## Documentation - ### `Class`: - - #### [`Gunner.constructor`](DOCUMENTATION.md#new-gunner-options) + - #### [`Gunner.constructor`](https://github.com/klenty/Gunner/blob/master/DOCUMENTATION.md#new-gunner-options) - ### `Methods`: - - #### [`Gunner#test`](DOCUMENTATION.md#gunnertest-title-implementation) - - #### [`Gunner#before`](DOCUMENTATION.md#gunnerbefore-title-implementation) - - #### [`Gunner#after`](DOCUMENTATION.md#gunnerafter-title-implementation) - - #### [`Gunner#run`](DOCUMENTATION.md#gunnerrun-options) + - #### [`Gunner#test`](https://github.com/klenty/Gunner/blob/master/DOCUMENTATION.md#gunnertest-title-implementation) + - #### [`Gunner#before`](https://github.com/klenty/Gunner/blob/master/DOCUMENTATION.md#gunnerbefore-title-implementation) + - #### [`Gunner#after`](https://github.com/klenty/Gunner/blob/master/DOCUMENTATION.md#gunnerafter-title-implementation) + - #### [`Gunner#run`](https://github.com/klenty/Gunner/blob/master/DOCUMENTATION.md#gunnerrun-options) - ### `Constants`: - #### `[Gunner.Start]` - #### `[Gunner.End]` -- ### [`State and Advanced Usage`](DOCUMENTATION.md#state) +- ### [`State and Advanced Usage`](https://github.com/klenty/Gunner/blob/master/DOCUMENTATION.md#state) ## Credits diff --git a/package.json b/package.json index 2cf50ca..51f4778 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@klenty/gunner", - "version": "0.9.3", + "version": "0.9.4", "description": "Zero magic, fast test-runner and assertion framework. No magic globals.", "main": "index.js", "repository": { diff --git a/src/gunner.js b/src/gunner.js index 6bd058b..59f7d13 100644 --- a/src/gunner.js +++ b/src/gunner.js @@ -92,8 +92,8 @@ class Gunner { } module.exports = Gunner; -module.exports.Gunner = Gunner; module.exports.expect = expect; module.exports.expectMany = expect.expectMany; module.exports.Start = symbols.Start; module.exports.End = symbols.End; +module.exports.Gunner = module.exports;