Node's Pocket Monsters

    macgyver

    1.10.1 • Public • Published

    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

    Keywords

    none

    Install

    npm i macgyver

    DownloadsWeekly Downloads

    895

    Version

    1.10.1

    License

    none

    Last publish

    Collaborators

    • nopersonsmodules