Update readme

This commit is contained in:
Jonatan Nilsson 2023-08-26 21:10:56 +00:00
parent a2638b671d
commit c2b95f62a8

100
README.md
View file

@ -24,7 +24,7 @@ $ mkdir test
Next in your favourite editor, create `test/test.mjs`: Next in your favourite editor, create `test/test.mjs`:
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
t.describe('Array', function() { t.describe('Array', function() {
@ -81,7 +81,7 @@ Eltro supports any type of asynchronous code testing. It can either be done by a
Example of testing using done: Example of testing using done:
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
t.describe('User', function() { t.describe('User', function() {
@ -99,7 +99,7 @@ t.describe('User', function() {
Alternatively, just use the done() callback directly (which will handle an error argument, if it exists): Alternatively, just use the done() callback directly (which will handle an error argument, if it exists):
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
t.describe('User', function() { t.describe('User', function() {
@ -114,7 +114,7 @@ t.describe('User', function() {
Or another alternative is to use promises and return a promise directly: Or another alternative is to use promises and return a promise directly:
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
t.test('should complete this test', function(done) { t.test('should complete this test', function(done) {
@ -126,7 +126,7 @@ t.test('should complete this test', function(done) {
Which works well with `async/await` like so: Which works well with `async/await` like so:
```node ```javascript
t.test('async test', async function() { t.test('async test', async function() {
let user = await User.find({ username: 'test' }) let user = await User.find({ username: 'test' })
assert.ok(user) assert.ok(user)
@ -137,7 +137,7 @@ t.test('async test', async function() {
Inspired by sinon js, this library comes with pre-built simple sinon-like style spy() and stub() Inspired by sinon js, this library comes with pre-built simple sinon-like style spy() and stub()
```node ```javascript
import { assert, spy, stub } from 'eltro' import { assert, spy, stub } from 'eltro'
let myFunc = spy() let myFunc = spy()
@ -167,7 +167,7 @@ Queue up the `func` as a test with the specified messagt.
In case you wanna describe a bunch of tests, you can add them inside `func` and it will have the specified `message` prepended before every test: In case you wanna describe a bunch of tests, you can add them inside `func` and it will have the specified `message` prepended before every test:
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
function someFunction() { return true } function someFunction() { return true }
@ -191,7 +191,7 @@ will output:
Queue up the `func` to run before any test or groups within current active group. Queue up the `func` to run before any test or groups within current active group.
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
t.before(function() { t.before(function() {
@ -223,7 +223,7 @@ t.describe('#anotherTest()', function() {
Queue up the `func` to run after any test or groups within current active group. Queue up the `func` to run after any test or groups within current active group.
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
t.after(function() { t.after(function() {
@ -255,7 +255,7 @@ t.describe('#anotherTest()', function() {
Queue up the `func` to run before each test or groups within current active group. Queue up the `func` to run before each test or groups within current active group.
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
t.beforeEach(function() { t.beforeEach(function() {
@ -287,7 +287,7 @@ t.describe('#anotherTest()', function() {
Queue up the `func` to run after every test or groups within current active group. Queue up the `func` to run after every test or groups within current active group.
```node ```javascript
import { Eltro as t, assert} from 'eltro' import { Eltro as t, assert} from 'eltro'
t.afterEach(function() { t.afterEach(function() {
@ -321,7 +321,7 @@ Eltro supports exclusivity when running tests. When specified, only tests marked
You can do exclusivity on tests by adding `.only()` in front of describe, after or before the test like so: You can do exclusivity on tests by adding `.only()` in front of describe, after or before the test like so:
```node ```javascript
t.only().describe('Only these will run', function() { t.only().describe('Only these will run', function() {
t.test('this one', function() { assert.strictEqual(true, true) }) t.test('this one', function() { assert.strictEqual(true, true) })
t.test('and this one', function() { assert.strictEqual(true, true) }) t.test('and this one', function() { assert.strictEqual(true, true) })
@ -330,7 +330,7 @@ t.only().describe('Only these will run', function() {
You can also put it on individual test like so You can also put it on individual test like so
```node ```javascript
t.test('Only run this test', function() { t.test('Only run this test', function() {
assert.strictEqual(true, true) assert.strictEqual(true, true)
}).only() }).only()
@ -338,7 +338,7 @@ t.test('Only run this test', function() {
or like so: or like so:
```node ```javascript
t.only().test('Only run this test', function() { t.only().test('Only run this test', function() {
assert.strictEqual(true, true) assert.strictEqual(true, true)
}) })
@ -348,7 +348,7 @@ t.only().test('Only run this test', function() {
You can skip tests easily by adding `.skip()` before describe, before or after the test like so: You can skip tests easily by adding `.skip()` before describe, before or after the test like so:
```node ```javascript
t.skip().describe('None of these will run', function() { t.skip().describe('None of these will run', function() {
t.test('not this', function() { assert.strictEqual(true, true) }) t.test('not this', function() { assert.strictEqual(true, true) })
t.test('or this one', function() { assert.strictEqual(true, true) }) t.test('or this one', function() { assert.strictEqual(true, true) })
@ -357,7 +357,7 @@ t.skip().describe('None of these will run', function() {
You can also do it on individual tests like so: You can also do it on individual tests like so:
```node ```javascript
t.test('Skip due to something being broken', function() { t.test('Skip due to something being broken', function() {
BrokenFunction() BrokenFunction()
}).skip() }).skip()
@ -365,7 +365,7 @@ t.test('Skip due to something being broken', function() {
or like so: or like so:
```node ```javascript
t.skip().test('Skip this', function() { ... }) t.skip().test('Skip this', function() { ... })
``` ```
@ -373,7 +373,7 @@ t.skip().test('Skip this', function() { ... })
Tests can take a long time. By default, eltro will cancel a test if it takes longer than 2 seconds. You can however override this by calling the timeout function after or before the test or before the describe with the specified duration in milliseconds like so: Tests can take a long time. By default, eltro will cancel a test if it takes longer than 2 seconds. You can however override this by calling the timeout function after or before the test or before the describe with the specified duration in milliseconds like so:
```node ```javascript
t.timeout(5000).describe('These will all have same timeout', function() { t.timeout(5000).describe('These will all have same timeout', function() {
t.test('One slow function', async function() { ... }) t.test('One slow function', async function() { ... })
t.test('Another slow function', async function() { ... }) t.test('Another slow function', async function() { ... })
@ -382,7 +382,7 @@ t.timeout(5000).describe('These will all have same timeout', function() {
Or apply to individual test like so: Or apply to individual test like so:
```node ```javascript
t.test('This is a really long test', async function() { t.test('This is a really long test', async function() {
await DoSomethingForReallyLongTime() await DoSomethingForReallyLongTime()
}).timeout(5000) // 5 seconds }).timeout(5000) // 5 seconds
@ -390,7 +390,7 @@ t.test('This is a really long test', async function() {
or like so: or like so:
```node ```javascript
t.timeout(5000).test('A long test', async function() { ... }) t.timeout(5000).test('A long test', async function() { ... })
``` ```
@ -399,7 +399,7 @@ t.timeout(5000).test('A long test', async function() { ... })
Eltro comes with an extended version of node's built-in assertion library. Eltro comes with an extended version of node's built-in assertion library.
You can start using them by simply importing it with eltro test runner: You can start using them by simply importing it with eltro test runner:
```node ```javascript
import { assert } from 'eltro' import { assert } from 'eltro'
``` ```
@ -408,7 +408,7 @@ import { assert } from 'eltro'
Tests if value is a falsy value using `Boolean(value) == false` Tests if value is a falsy value using `Boolean(value) == false`
```node ```javascript
assert.notOk(false) // ok assert.notOk(false) // ok
assert.notOk(null) // ok assert.notOk(null) // ok
assert.notOk(undefined) // ok assert.notOk(undefined) // ok
@ -419,7 +419,7 @@ assert.notOk([]) // throws
Test if the string value has a regex match of test Test if the string value has a regex match of test
```node ```javascript
assert.match('asdf', /a/) // ok assert.match('asdf', /a/) // ok
assert.match('hello world', /hello/) // ok assert.match('hello world', /hello/) // ok
assert.match('something', /else/) // throws assert.match('something', /else/) // throws
@ -429,7 +429,7 @@ assert.match('something', /else/) // throws
Test if the string value does not regex match the test Test if the string value does not regex match the test
```node ```javascript
assert.notMatch('asdf', /b/) // ok assert.notMatch('asdf', /b/) // ok
assert.notMatch('something', /else/) // ok assert.notMatch('something', /else/) // ok
assert.notMatch('hello world', /hello/) // throws assert.notMatch('hello world', /hello/) // throws
@ -440,7 +440,7 @@ assert.notMatch('hello world', /hello/) // throws
Tests to make sure the promise gets fulfilled successfully and Tests to make sure the promise gets fulfilled successfully and
returns the final result. returns the final result.
```node ```javascript
await assert.isFulfilled(Promise.resolve(null)) // ok await assert.isFulfilled(Promise.resolve(null)) // ok
await assert.isFulfilled(() => { throw new Error() }) // throws await assert.isFulfilled(() => { throw new Error() }) // throws
``` ```
@ -450,7 +450,7 @@ await assert.isFulfilled(() => { throw new Error() }) // throws
Tests to make sure the promise gets rejected and returns the error Tests to make sure the promise gets rejected and returns the error
or value that was rejected or value that was rejected
```node ```javascript
let val = await assert.isRejected(Promise.reject('asdf')) // ok let val = await assert.isRejected(Promise.reject('asdf')) // ok
assert.strictEqual(val, 'asdf') assert.strictEqual(val, 'asdf')
@ -458,7 +458,7 @@ let err = await assert.isRejected(() => { throw new Error('hello') }) // ok
assert.strictEqual(err.message, 'hello') assert.strictEqual(err.message, 'hello')
``` ```
# Sinon-like spy()/stub() # Sinon-like spy() stub()
Using sinon-inspired mechanics for spying on calls as well as being able Using sinon-inspired mechanics for spying on calls as well as being able
to stub existing functionality, eltro comes with a handy little copy-cat. to stub existing functionality, eltro comes with a handy little copy-cat.
@ -469,7 +469,7 @@ the resulting code to speak about its purpose.
To create a stub or a spy, simply import it and call it like so: To create a stub or a spy, simply import it and call it like so:
```node ```javascript
import { spy, stub } from 'eltro' import { spy, stub } from 'eltro'
let spying = spy() let spying = spy()
@ -478,7 +478,7 @@ let fn = stub()
Each call to stub or spy is an array list of the passed-on arguments: Each call to stub or spy is an array list of the passed-on arguments:
```node ```javascript
let spying = spy() let spying = spy()
spying('hello', 'world') spying('hello', 'world')
@ -488,9 +488,9 @@ assert.strictEqual(spying.lastCall[1], 'world')
### lastCall ### lastCall
Returns the last call that was made to sinon and stub: Returns the last call that was made to the spy or stub:
```node ```javascript
let spying = spy() let spying = spy()
spying('a') spying('a')
spying('b') spying('b')
@ -501,9 +501,9 @@ assert.strictEqual(spying.lastCall[0], 'c')
### called ### called
Boolean variable that gets flipped once it's called at least once Boolean variable that gets flipped once it gets called at least once
```node ```javascript
let spying = spy() let spying = spy()
assert.strictEqual(spying.called, false) assert.strictEqual(spying.called, false)
spying('a') spying('a')
@ -517,7 +517,7 @@ assert.strictEqual(spying.called, true)
The number of times it's been called The number of times it's been called
```node ```javascript
let spying = spy() let spying = spy()
assert.strictEqual(spying.callCount, 0) assert.strictEqual(spying.callCount, 0)
spying('a') spying('a')
@ -531,7 +531,7 @@ assert.strictEqual(spying.callCount, 3)
Specifies what value the stub or spy should return when it gets called. Specifies what value the stub or spy should return when it gets called.
```node ```javascript
let fn = stub() let fn = stub()
fn.returns('a') fn.returns('a')
@ -543,14 +543,14 @@ assert.strictEqual(fn(), 'a')
Specifies what value the stub or spy should throw when it gets called. Specifies what value the stub or spy should throw when it gets called.
```node ```javascript
let fn = stub() let fn = stub()
fn.throws(new Error('b')) fn.throws(new Error('b'))
try { try {
fn() fn()
} catch (err) { } catch (err) {
assert.strictEqual(fn(), 'b') assert.strictEqual(err.message, 'b')
} }
``` ```
@ -558,7 +558,7 @@ try {
Specifies what value the stub or spy should return wrapped in a promise. Specifies what value the stub or spy should return wrapped in a promise.
```node ```javascript
let fn = stub() let fn = stub()
fn.resolves('a') fn.resolves('a')
@ -571,7 +571,7 @@ fn().then(function(data) {
Specifies what value the stub or spy should reject, wrapped in a promise. Specifies what value the stub or spy should reject, wrapped in a promise.
```node ```javascript
let fn = stub() let fn = stub()
fn.rejects('nope') fn.rejects('nope')
@ -584,7 +584,7 @@ fn().catch(function(data) {
Specify custom function to be called whenever the stub or spy gets called. Specify custom function to be called whenever the stub or spy gets called.
```node ```javascript
let fn = stub() let fn = stub()
fn.returnWith(function(a) { fn.returnWith(function(a) {
if (a === 'a') return true if (a === 'a') return true
@ -597,12 +597,11 @@ assert.strictEqual(fn('a'), true)
assert.strictEqual(fn.callCount, 3) assert.strictEqual(fn.callCount, 3)
``` ```
### getCall(index) ### getCall(index) getCallN(num)
### getCallN(num)
Get a specific call. The `getCall` gets a zero-based index call while the `getCallN(num)` gets the more natural number call Get a specific call. The `getCall` gets a zero-based index call while the `getCallN(num)` gets the more natural number call
```node ```javascript
let spying = spy() let spying = spy()
spying('a') spying('a')
spying('b') spying('b')
@ -613,14 +612,13 @@ assert.strictEqual(spying.getCallN(1), 'a')
assert.strictEqual(spying.getCallN(2), 'b') assert.strictEqual(spying.getCallN(2), 'b')
``` ```
### onCall(index) ### onCall(index) onCallN(num)
### onCallN(num)
Overwrite behavior for a specific numbered call. Just like with getCall/getCallN, the onCall is zero-indexed number of the call you want to specify custom behavior while onCallN is the more natural number of the call you want to specify custom behavior. Overwrite behavior for a specific numbered call. Just like with getCall/getCallN, the onCall is zero-indexed number of the call you want to specify custom behavior while onCallN is the more natural number of the call you want to specify custom behavior.
Note, when called with null, it specifies the default behavior. Note, when called with null, it specifies the default behavior.
```node ```javascript
let fnOne = stub() let fnOne = stub()
let fnTwo = stub() let fnTwo = stub()
@ -644,14 +642,14 @@ assert.strictEqual(fnTwo(), 'one')
Search for the first call when `fn(call)` returns `true`. Essentially a filter to search for a specific call that matches whatever call you're searching for. Search for the first call when `fn(call)` returns `true`. Essentially a filter to search for a specific call that matches whatever call you're searching for.
```node ```javascript
let evnt = stub() let evnt = stub()
evnt('onclick', 'one') evnt('onclick', 'one')
evnt('onerror', 'two') evnt('onerror', 'two')
evnt('something', 'three') evnt('something', 'three')
evnt('onpress', 'four') evnt('onpress', 'four')
evnt('else', 'five') evnt('else', 'five')
let foundPressCall = evnt.findCall(function(call) { return call[0] === 'onpress' }) let foundPressCall = evnt.findCall(function(call) { return call[0] === 'onpress' })
assert.strictEqual(foundPressCall[0], 'onpress') assert.strictEqual(foundPressCall[0], 'onpress')