Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A test decorator.
CoffeeScript JavaScript
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

all development efforts suspended

objective_dev achieves the goals set out here.

due homage: RSpec

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

npm install ipso 0.0.22 license

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) {


}  ));

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 (done, 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) -> 

        createServer: -> 
        anotherFunction: -> 


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) -> 

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

    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) -> 

        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) -> 


        _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: -> 


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

{ipso, mock} = require 'ipso'

before ipso ->
        function1: -> return 'value1'

beforeEach ipso (thing) -> 

    # injected mock thing (as defined in above)

        function2: -> return 'value2'

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


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

Mocks can define properties using .with()

{ipso, mock} = require 'ipso'

before ipso ->
        property1: 'value1'
        property2: 'value2'

beforeEach ipso (thing) -> 


        property2: 'overwrite value2'


        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)

        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 events.EventEmitter

It supports taging objects for multiple subsequent injections by tag.

context 'creates tagged objects for injection into multiple nested tests', -> 

    before ipso (ClassName) ->


            instanceA: new ClassName 'type A'
            instanceB: new ClassName 'type B'
            client:    require ''

    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) -> 

        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

    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 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) ->


            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'

  • Use case

    • Testing component based clientside code without running a browser.

    • 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) -> 


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


        martini: -> Mock 'VodkaMartini'

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


        olive: true


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

    Martini  = require 'martini'
    instance = new Martini

    Got instance.olive
    Not instance.gin


    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) -> 


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

Ipso Facto

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


    # 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.
Something went wrong with that request. Please try again.