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.
ipso
thing?
What is this
The Long Answer, ↓
(test/) Injection Decorator
It is placed in front of the test functions.
ipso = require 'ipso' it 'does something'ipso done # as usual
or js:
ipso = ; ;
It can inject node modules into suites.
describe 'it can inject into describe'ipso context 'it can inject into context'ipso it 'confirms'-> vmshouldequal require 'vm' netshouldequal require 'net'
It can inject node modules into tests.
it 'does something'ipso httpshouldequal require 'http'
It can inject dasherized modules using mixed case.
it 'does something'ipso dashedNameshouldequal 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 # # => 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 httpdoes : -> : -> httpcreateServer done
It uses mocha's JSON diff to display failure to call the stubbed function.
actual expected 1 |
or, (depending on your mocha version)
+ expected - actual
The stub replaces the actual function on the module and can therefore return a suitable mock.
http = require 'http' : httpcreateServerhandlerlisten optsport
require 'ipso' it 'creates an http server and listens at opts.port'ipso httpdoes : -> return mock'server'does : portshouldequal 3000 done MyServerlisten port: 3000
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.
require 'ipso' it 'can fake the existance of a file'ipso fsdoes : 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 Serverdoes : -> # console.log arguments consolelog """ _underscore denotes a spy function ================================== * the original will be called after the spy (this function) * both will receive the same arguments """ : -> Serverstart
IMPORTANT Stubs set up in before (All) hooks are not enforced as expectations
require 'ipso' before ipso -> mock'thing'does : -> return 'value1' beforeEach ipso # # injected mock thing (as defined in above) # thingdoes : -> return 'value2' it 'calls function2'ipso thingfunction2 # # does not fail even tho function1() was not called #
Mocks can define properties using .with()
require 'ipso' before ipso -> mock'thing'with property1: 'value1' property2: 'value2' beforeEach ipso thingwith property2: 'overwrite value2' does : -> 'with and does are chainable' : ->
- 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 # Periscope.$prototype.does (dunno yet) Periscopeprototypedoes : -> return 30 : distanceshouldequal 30 : -> @videoStreamcodecshouldequal π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 = codec: πr² periscopeup shouldnotexist error eyeholeshouldbeaninstanceof eventsEventEmitter done
It supports taging objects for multiple subsequent injections by tag.
context 'creates tagged objects for injection into multiple nested tests'-> before ipso ipsotag instanceA: 'type A' instanceB: 'type B' client: require 'socket.io-client' it 'can test with them' it 'and again'
Complex Usage
It can create active mocks for fullblown mocking and stubbing
beforeEach ipso httpdoes : processnextTick -> # # mock an actual "hit" # handler mock'req'mock'mock response'does : -> : -> : -> return ipsomock 'mock server' does : : -> '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 server = httpcreateServer reswriteHead 200 resend facto serverlisten 3000 @portshouldequal 3000
actual expected 1 |
It can create entire module stubs
require 'ipso' before ipso -> # # create a mock to be returned by the module function # mock 'nonExistant' with : -> 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() # : -> 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 nonExistantdoes : -> non = require 'non-existant' consolelog non # # => { function1: [Function], # property1: 'value1', # function2: [Function] } # it "can require 'missing' and create expectations on the Class / instance" ipso ClassNamedoes : argshouldequal 'ARG' : -> # # this would generally be elsewhere (in the module being tested) # missing = require 'missing' instance = 'ARG' instancesomeFunction
-
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
require '../lib/ipso' before ipso tag Got: shouldexist Not: shouldnotexist define : -> Mock 'VodkaMartini' it 'has the vodka and the olive'ipso VodkaMartiniwith olive: true does : -> @vodka = true : -> Martini = require 'martini' instance = Got instancevodka Got instanceolive Not instancegin instanceshake try instancestir # # 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 ModulefunctionThatReturnsAPromise then -> ModulefunctionThatReturnsAPromise then -> ModulefunctionThatReturnsAPromise then -> ModulefunctionThatReturnsAPromise then -> facto
Ipso Facto
it 'does many things to come'ipso factoMetaThings # # 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.