due homage: RSpec

experimental/unstable api changes will still occur (without deprecation warnings)

npm install ipso 0.0.22 license

• Injection Decorator, for mocking and stubbing, with Mocha
• Now also a modulename aliasing bridge, for using components, serverside

Almost all examples in coffee-script.

What is this ipso thing?

The Short Answer

The Long Answer, ↓

(test/) Injection Decorator

It is placed in front of the test functions.

ipso = require 'ipso'

it 'does something', ipso (done) -> 

    done() # as usual

or js:

ipso = require('ipso');

it('does something', ipso(  function(done) {
  
  done();

}  ));

It can inject node modules into suites.

describe 'it can inject into describe', ipso (vm) -> 
    context 'it can inject into context', ipso (net) -> 
        it 'confirms', -> 

            vm.should.equal  require 'vm'
            net.should.equal require 'net'

It can inject node modules into tests.

it 'does something', ipso (done, http) -> 

    http.should.equal require 'http'

It can inject dasherized modules using mixed case.

it 'does something', ipso (dashedName) ->

    dashedName.should.equal require 'dashed-name'

IMPORTANT: done will only contain the test resolver if the argument's signaure is literally "done" and it in the first position.

In other words.

it 'does something', ipso (finished, http) -> 

#
# => Error: Cannot find module 'finished' 
# 
# And the problem becomes more subtle if there IS a module called 'finshed' installed...
# 

It defines .does() on each injected module for use as a stubber.

it 'creates an http server', ipso (done, http) -> 

    http.does 
        createServer: -> 
        anotherFunction: -> 

    http.createServer()
    done()

It uses mocha's JSON diff to display failure to call the stubbed function.

      actual expected
      
      1 | {
      2 |   "http": {
      3 |     "functions": {
      4 |       "Object.createServer()": "was called"
      5 |       "Object.anotherFunction()": "was NOT called"
      6 |     }
      7 |   }
      8 | }

or, (depending on your mocha version)

      + expected - actual

       {
         "http": {
           "functions": {
             "Object.createServer()": "was called",
      +      "Object.anotherFunction()": "was called"
      -      "Object.anotherFunction()": "was NOT called"
           }
         }
       }

The stub replaces the actual function on the module and can therefore return a suitable mock.

http = require 'http'
class MyServer
    listen: (opts, handler) -> 
        http.createServer(handler).listen opts.port

{ipso, mock} = require 'ipso'

it 'creates an http server and listens at opts.port', ipso (done, http, MyServer) -> 

    http.does
        createServer: -> 
            return mock('server').does
                listen: (port) ->
                    port.should.equal 3000
                    done()

    MyServer.listen port: 3000, (req, res) -> 

You may have noticed that MyServer was also injected in the previous example.

• The injector recurses ./lib and ./app for the specified module.
• It does so only if the module has a CamelCaseModuleName in the injection argument's signature
• It searches for the underscored equivalent ./lib/**/*/camel_case_module_name.js|coffee
  • TODO: make search strategy configurable
• These Local Module Injections can also be stubbed.

It can call the original function from within the stub.

{ipso, original} = require 'ipso'

it 'can fake the existance of a file', ipso (fs) -> 

    fs.does
        readFileSync: (filename) -> 

            return 'mock file contents' if filename is 'something'

            #
            # otherwise call onward to original with arguments
            # ------------------------------------------------
            # 
            # * original() references the currently running stub's original
            # * it therefore only functions as expected from inside running stub
            # 

            return original arguments

It can create multiple function expectation stubs ( and spies ).

it 'can create multiple expectation stubs', ipso (done, Server) -> 

    Server.does 

        _listen: ->

            # console.log arguments 

            console.log """

                _underscore denotes a spy function
                ==================================

                * the original will be called after the spy (this function)
                * both will receive the same arguments

            """

        anotherFunction: -> 

    Server.start()

IMPORTANT Stubs set up in before (All) hooks are not enforced as expectations

{ipso, mock} = require 'ipso'


before ipso ->
    mock('thing').does
        function1: -> return 'value1'


beforeEach ipso (thing) -> 

    #
    # injected mock thing (as defined in above)
    #

    thing.does
        function2: -> return 'value2'



it 'calls function2', ipso (thing) -> 

    thing.function2() 

    #
    # does not fail even tho function1() was not called
    #

Mocks can define properties using .with()

{ipso, mock} = require 'ipso'

before ipso ->
    mock('thing').with
        property1: 'value1'
        property2: 'value2'

beforeEach ipso (thing) -> 

    thing.with

        property2: 'overwrite value2'

    .does

        function1: -> 'with and does are chainable'
        function2: -> 

• Note that .with() only exists on objects created with ipso.mock()

PENDING (unlikely, use tags, see below) It can create future instance stubs (on the prototype)

it 'can create multiple expectation stubs', ipso (done, Periscope, events, should) -> 
    
    # Periscope.$prototype.does  (dunno yet)
    Periscope.prototype.does 

        measureDepth: -> return 30

        _riseToSurface: (distance, finishedRising) -> 
            distance.should.equal 30

        _openLens: -> 
            @videoStream.codec.should.equal πr²

            #
            # note: That `@` a.k.a. `this` refers to the instance context 
            #       and not the test context. It therefore has access to
            #       properties of the Periscope instance.
            # 


    periscope = new Periscope codec: πr²
    periscope.up (error, eyehole) -> 

        should.not.exist error
        eyehole.should.be.an.instanceof events.EventEmitter
        done()

It supports taging objects for multiple subsequent injections by tag.

context 'creates tagged objects for injection into multiple nested tests', -> 
    
    before ipso (ClassName) ->

        ipso.tag 

            instanceA: new ClassName 'type A'
            instanceB: new ClassName 'type B'
            client:    require 'socket.io-client'

    it 'can test with them', (instanceA, instanceB, client) -> 
    it 'and again', (instanceA, instanceB) -> 

Complex Usage

It can create active mocks for fullblown mocking and stubbing

beforeEach ipso (done, http) -> 

    http.does
        createServer: (handler) =>  
            process.nextTick ->

                #
                # mock an actual "hit"
                #

                handler mock('req'), mock('mock response').does

                    writeHead: -> 
                    write: ->
                    end: ->
            
            return ipso.mock( 'mock server' ).does

                listen: (@port, args...) => 
                address: -> 'mock address object'

                #
                # note: '=>' pathway from hook's root scope means @port
                # refers to the `this` of the hook's root scope - which 
                # is shared with the tests themselves, so @port becomes 
                # available in all tests that are preceeded by this     hook
                # 

it 'creates a server, starts listening and responds when hit', ipso (facto, http) ->

    server = http.createServer (req, res) -> 

        res.writeHead 200
        res.end()
        facto()

    server.listen 3000
    @port.should.equal 3000

      actual expected
      
       1 | {
       2 |   "http": {
       3 |     "functions": {
       4 |       "Object.createServer()": "was called"
       5 |     }
       6 |   },
       7 |   "mock server": {
       8 |     "functions": {
       9 |       "Object.listen()": "was called",
      10 |       "Object.address()": "was called"
      11 |     }
      12 |   },
      13 |   "mock response": {
      14 |     "functions": {
      15 |       "Object.writeHead()": "was called",
      16 |       "Object.write()": "was NOT called",  <--------------------
      17 |       "Object.end()": "was called"
      18 |     }
      19 |   }
      20 | }

It can create entire module stubs

{ipso, mock, Mock, define} = require 'ipso'

before ipso -> 

    #
    # create a mock to be returned by the module function
    #

    mock( 'nonExistant' ).with

        function1: ->
        property1: 'value1'


    #
    # define(listOfFunctions)
    # -----------------------
    # 
    # * Keys from the list become module names
    # * Each function is run by the module stubber
    # * The returned object is exported as the module
    #

    define

        #
        # define a module that exports two class definitions
        # --------------------------------------------------
        # 
        # * Mock() (capital 'M') creates mock classes
        # 
        # * .with() can be used to define a baseset of functions 
        #   and property stubs.
        # 
        # * The mock entity can be injected by tag/name for 
        #   per test configuration of function expectations
        #   using .does()
        # 

        missing: -> 

            ClassName: Mock 'ClassName'
            Another:   Mock('Another').with(...)

        # 
        # define a module that exports a single function
        # ----------------------------------------------
        # 

        'non-existant': -> ->

            #
            # * The second function becomes the exported function of the module.
            # 
            # * It will be retured by `require 'non-existant'`
            # 
            # * get() is defined in the module scope to enable reference
            #   to mocks and tags defined in this test scope.
            #

            return get 'nonExistant'



it "has created ability to require 'non-existant' in module being tested", 
  
    ipso (nonExistant, SubClass1) -> 

        nonExistant.does function2: ->
        non = require 'non-existant'

        console.log non()

        #
        # => { function1: [Function],
        #      property1: 'value1',
        #      function2: [Function] }
        #


it "can require 'missing' and create expectations on the Class / instance", 

    ipso (ClassName, should) ->

        ClassName.does 

            constructor: (arg) -> arg.should.equal 'ARG'
            someFunction: -> 




        #
        # this would generally be elsewhere (in the module being tested)
        #

        missing  = require 'missing'
        instance = new missing.ClassName 'ARG'
        instance.someFunction()

• Use case

  • Testing component based clientside code without running a browser.

• IMPORTANT / WARNING

  • It is a clunky interface and may change drastically.
  • It tricks require into loading the module by tailoring the behaviours of fs.readFileSync, statSync and lstatSync (a not very eloquent method...)
  • It cannot be reversed (yet), so the stub remains for the duration of the process that created it.

it has been shaken, not stirred

{ipso, tag, define, Mock} = require '../lib/ipso'

before ipso (should) -> 

    tag

        Got: should.exist
        Not: should.not.exist

    define 

        martini: -> Mock 'VodkaMartini'


it 'has the vodka and the olive', ipso (VodkaMartini, Got, Not) -> 

    VodkaMartini.with 

        olive: true

    .does

        constructor: -> @vodka = true
        shake: ->

    Martini  = require 'martini'
    instance = new Martini

    Got instance.vodka
    Got instance.olive
    Not instance.gin

    instance.shake()

    try instance.stir()



    #
    # ps. there is great value in using **only** local scope in tests... (!, later)
    # 

It supports promises.

it 'fails the test on the first rejection in the chain', ipso (facto, Module) -> 

    Module.functionThatReturnsAPromise()

    .then -> Module.functionThatReturnsAPromise()
    .then -> Module.functionThatReturnsAPromise()
    .then -> Module.functionThatReturnsAPromise()
    .then -> facto()

Ipso Facto

it 'does many things to come', ipso (facto, ...) -> 

    facto[MetaThings]()

    #
    # facto() calls mocha's done() in the background
    #

What MetaThings?

• well, ... (( the brief brainstorm suggested a Planet-sized Plethora of Particularly Peachy Possibilities Perch Patiently Poised Pending a Plunge into That rabbit hole.

There is a cli

• It assists with the overhead of dev using coffee-script, specifically the compile.then -> runTest on changes in src/**/*

And who is Unthahorsten?

• And why was he doing the equivalent of standing in the equivalent of a laboratory.