macgyver

[![build status](https://secure.travis-ci.org/dominictarr/macgyver.png)](http://travis-ci.org/dominictarr/macgyver) [![browser status](http://ci.testling.com/dominictarr/macgyver.png)](http://ci.testling.com/dominictarr/macgyver) declarative assertion framework for invocation ordering.

npm install macgyver
45 downloads in the last day
477 downloads in the last week
1 885 downloads in the last month

macgyver

build status browser status declarative assertion framework for invocation ordering.

when evented code really gets mission critical there is one man you send in...

useful for testing streams, and other complex evented modules.

example


var macgyver = require('macgyver')

//create a context
var mac = macgyver()

//wrap a function...

function hello () {
  console.log('hello')
}

function goodbye () {
  console.log('goodbye')
}

var hi = mac(hello)

//declare it's behaviours

hi.isCalled(1, 7) //must be called between 1 and 7 times.

var bye = mac(goodbye).once() //must be called strictly once.

hi.before(bye) //hi must be called strictly before bye is called

hi(); hi(); bye()

/*
  //this will produce an error!
  hi(); hi(); bye(); hi()
*/

mac.validate()

here is a real life example: dominictarr/event-stream/test/spec.js

API

create a maggyver context.

var macgyver = require('macgyver')
var mac = macgyver()

wrap a function


function doSomething() {}

var _doSomething = mac(doSomething)

now, we can make declairations about how the wrapped function must be called.

isCalled(min, max)

assert that the function is called at least min times, and at most max times. if min, or max is null, then that bound is not checked. i.e. mac(fun).isCalled(null, 10) will assert that fun is called not more than 10 times.

once()

alias for isCalled (1, 1)

times(n)

alias for isCalled (n, n)

eventually()

alias for isCalled (null, 1)

never()

alias for isCalled (0, 0)

maybeOnce()

alias for isCalled (null, 1)

atMost(max)

alias for isCalled (null, max)

atLeast(min)

alias for isCalled (min, null)

again (inc=1)

increments the number of times a function may be called. (inc may be negative)

before (other)

assert that a function is called before another function. the other must also be a wrapped function. mac(first).before(second = mac(second))

before does not check wether the second function is eventually called or not. use isCalled or an alias.

beforeReturns (other)

just like before but checks that the function is called before the other function returns, so that it is possible for the first function to be called by the other.

returns (value)

assert that a function returns a value. if value is a function, it will be called with the return value.

//assert that fun returns a string.
mac(fun).returns(function (val) {
  assert.equal(typeof val, 'string')
})

the function should throw if the return value was not valid.

isPassed (args)

assert that a function is passed the correct arguments. if args is a function, that function is called as in returns.

throws (test)

assert that a function throws. test may be a value or a function. test is optional.

if supplyed test is called on every call.

mac(fun).throws(function (err, threw) {
  if(threw) {
    assert.equal(err.code,'ERRCODE') //check correct error
  } else {
    //what to do if there was no error?
  }
})

this is useful for checking conditions about when the error should be thrown. example stream#write

validate ()

check all rules passed. must be called once you are sure all calls are finished. for example process.on('exit', mac.validate) is a good time. validate in necessary to check that lower bounds of isCalled and aliases where met.

autoValidate(browserTimeout)

call validate on process.on('exit', mac.validate). if process.on is not available (as on the browser) wait until browserTimeout instead. testling ci kills tests after 30 seconds, so by default browserTimeout = 10e3 (10 seconds)

more coming!

license

MIT / Apachce2

npm loves you