Reference

 
args(arg [, arg, ...])

Specifies the arguments of an expected method call. For example, the following creates the expectation that the method appendFileSync() will be called with the arguments "log.txt" and "This is a log entry.":

mock ->
  fs.expects("appendFileSync").args("log.txt", "This is a log entry.")

arg can be of any type:

mock ->
  my_object.expects("my_method").args("string", 123, {an_object: "an_object"})

args() should be called with one or more arguments. Do not use args() if an expected method is to be called with no arguments:

mock ->
  socket = new Socket()
  socket.expects("close")           # ok; no arguments expected (e.g. socket.close() )
  socket.expects("close").args()    # not ok; do not use args() with no arguments

args() should only be called once per expectation:

mock ->
  fs.expects("appendFileSync").args("l.txt", 0)                     # ok
  fs.expects("appendFileSync").args("l.txt").args(0)                # not ok
  fs.expects("appendFileSync").args("l1.txt", 1).args("l2.txt", 2)  # not ok ...
  fs.expects("appendFileSync").args("l1.txt", 1)                    # ... do this instead
  fs.expects("appendFileSync").args("l2.txt", 2)

args() returns an expectation object upon which either returns() or throws() can be called. args() should not be called after returns() or throws():

mock ->
  socket = new Socket()
  socket.expects("greet").args("hello").returns("hi")     # ok
  socket.expects("greet").returns("hi").args("hello")     # not ok
  socket.expects("greet").args(null).throws("error")      # ok
  socket.expects("greet").throws("error").args(null)      # not ok

Example:

chai   = require("chai")
should = chai.should()
mock   = require("TinyMock")
Chat   = require("../src/Chat")

describe "Chat", ->
  describe "greet(my_name)", ->
    it "sends a greeting and returns the response", ->
      mock (socket) ->
        socket.expects("write").args("Hello, my name is Aristotle.\n")
        socket.expects("read").returns("Greetings Aristotle!\n")
        chat = new Chat(socket)
        chat.greet("Aristotle").should.equal("Greetings Aristotle!\n")

 
expects(method_name)

Creates an expectation that method_name will be called on object. For example, the following creates the expectation that the method appendFileSync() will be called on the object fs:

mock ->
  fs.expects("appendFileSync")

expects() can be called on any class, on any instance of Object, or on anything that inherits from Object:

mock ->
  Object.expects("toString")      # Object is a class

class MyClass
  # empty
mock ->
  MyClass.expects("toString")     # any class that inherits from Object (i.e. any class)

mock ->
  object = new Object()
  object.expects("toString")      # object is an instance of Object

class MyClass
  # empty
mock ->
  object = new MyClass()
  object.expects("toString")      # object is an instance of MyClass, which inherits from Object

mock ->
  object = Object.create(null);
  object.expects("my_method")     # not ok; object has no method 'expects'

method_name must already exist unless expects() is called on a mock object passed in by mock():

class MyClass
  # empty
mock ->
  MyClass.expects("my_method")    # not ok; my_method() is not an existing method of MyClass

class MyClass
  # empty
mock ->
  object = new MyClass()
  object.expects("my_method")     # not ok; my_method() is not an existing method of MyClass

mock (object) ->
  object.expects("my_method")     # ok; object was passed in by mock()

For mock objects not passed in by mock, expects() replaces the existing method_name with a mock method, therefore the original method_name's functionality is lost from the point the expects() was called to the end of the callback function:

class MyObject
  my_method: -> console.log("hello")

object = new MyObject()
mock ->
  object.my_method()              # prints "hello" on the console
  object.expects("my_method")
  object.my_method()              # does nothing
object.my_method()                # prints "hello" on the console

expects() returns an expectation object upon which the args(), returns(), or throws() methods can be called. This allows for a bit of fluency:

my_object.expects("my_method").args(1,2,3).returns("something")

Example:

chai   = require("chai")
should = chai.should()
mock   = require("TinyMock")
Chat   = require("../src/Chat")

describe "Chat", ->
  describe "greet(my_name)", ->
    it "sends a greeting and returns the response", ->
      mock (socket) ->
        socket.expects("write").args("Hello, my name is Aristotle.\n")
        socket.expects("read").returns("Greetings Aristotle!\n")
        chat = new Chat(socket)
        chat.greet("Aristotle").should.equal("Greetings Aristotle!\n")

 
mock [options,] callback

Use mock() to run a callback function that sets expectations and runs tests:

mock ->                                     # callback function
  fs.expects("appendFileSync")              # set an expectation
  ...

mock mock_count: 100, (books...) ->         # the number of mock objects to create (default is 5)
  book.expects("rate") for book in books
  ...

mock expects_method_name: "expects2", ->    # use a different name for expects()
  obj = new MyClass()
  obj.expects2("start")
  ...

mock() adds expects() to Object.prototype so that you can add an expectation on anything that is an instance of Object or that inherits from Object. When the callback function finishes running, mock() verifies that all expectations were actually met. It also restores all original methods that were replaced with mock methods by calls to expects(), and removes expects() from Object.prototype.

mock() also pre-creates mock objects and passes them to the callback function:

mock (db) ->
  db.expects("save").args("Aristotle", "philosopher")
  person = new Person("Aristotle", "philosopher")
  person.save(db)

Note that you can only add an expectation for a non-existent method to the mock objects passed in by mock(). The following will not work because "my_method" is not an existing method of obj (an Object), and obj was not passed in by mock():

mock ->
  obj = new Object()
  obj.expects("my_method")          # throws "'my_method' not an existing method" error
  ...

This prevents you from accidentally mocking a non-existing method on an existing object, which can be painful to track down:

mock ->
  fs.expects("appnedFileSync")      # spelling mistake ('append' not 'appned')
  fs.expects("noSuchMethod")        # method does not exist on fs
  chat = new Chat()
  chat.greet("Aristotle")

By default mock() creates five mock objects and passes them to the callback function. You can use as few or as many of them as appropriate, and of course you can name them any way you like:

mock (store, inventory, book1, book2, customer) ->
  store.expects("get_inventory").returns(inventory)
  inventory.expects("get_books").returns( [book1, book2] )
  customer.expects ...

You can have mock() create more than five mock objects by specifying a mock_count option:

mock mock_count: 101, (cat, dogs...) ->
  cat.expects("meow")
  dog.expects("chase") for dog in dogs
  ...

Sometimes you may find you want to set expectations on an object that already has an expects() method. In such cases, you can tell mock to use a different name for expects():

class MyClass
  start:   -> "something"
  expects: -> "anything"

mock expects_method_name: "expects2", ->    # use expects2() instead of expects() ...
  obj = new MyClass()
  obj.expects2("start")                     # ... because MyClass already has an expects() method
  ...

WARNING: watch the space before the callback argument list's opening parenthesis:

# this is correct
mock (m1) ->
  ...

# but this is not
mock(m1) ->
  ...

In summary, mock() creates mock objects, does verification, and cleans up so that you don't have to. The price is an extra level of indentation.

 
require

Use the Node.js require() function to make TinyMock available in code:

mock = require("TinyMock")

Example:

chai   = require("chai")
should = chai.should()
mock   = require("TinyMock")
Chat   = require("../src/Chat")

describe "Chat", ->
  describe "greet(my_name)", ->
    it "sends a greeting and returns the response", ->
      mock (socket) ->
        socket.expects("write").args("Hello, my name is Aristotle.\n")
        socket.expects("read").returns("Greetings Aristotle!\n")
        chat = new Chat(socket)
        chat.greet("Aristotle").should.equal("Greetings Aristotle!\n")

 
returns(value)

Specifies the value that a mock method installed by an expectation should return. For example, the following creates an expectation for the method read() and that the mock read() installed by the expectation should return "a message":

mock ->
  socket = new Socket()
  socket.expects("read").returns("a message")

returns() should be called with one argument. Do not use returns() if the mocked method should not return anything:

mock ->
  socket = new Socket()
  socket.expects("close")             # ok; mocked close() does not return anything
  socket.expects("close").returns()   # not ok; do not use returns() with no arguments

returns() should only be called once per expectation:

mock ->
  socket = new Socket()
  socket.expects("read").returns("a message")           # ok
  socket.expects("read").returns("m1").returns("m2")    # not ok

mock ->
  socket.expects("read").returns("m1")
  socket.expects("read").returns("m2")                  # not ok; TinyMock cannot handle this

returns() and throws() cannot be used on the same expectation:

mock ->
  socket.expects("read").throws("an error").returns("a message")    # not ok

Example:

chai   = require("chai")
should = chai.should()
mock   = require("TinyMock")
Chat   = require("../src/Chat")

describe "Chat", ->
  describe "greet(my_name)", ->
    it "sends a greeting and returns the response", ->
      mock (socket) ->
        socket.expects("write").args("Hello, my name is Aristotle.\n")
        socket.expects("read").returns("Greetings Aristotle!\n")
        chat = new Chat(socket)
        chat.greet("Aristotle").should.equal("Greetings Aristotle!\n")

 
throws(error)

Specifies the error that a mock method installed by an expectation should throw. For example, the following creates an expectation for the method read() and that the mock read() installed by the expectation should throw "an error":

mock ->
  socket = new Socket()
  socket.expects("read").throws(new Error("an error"))

throws() should be called with one argument. Do not use throws() if the mocked method should not throw anything:

mock ->
  socket = new Socket()
  socket.expects("close")             # ok; mocked close() does not throw anything
  socket.expects("close").throws()    # not ok; do not use throws() with no arguments

throws() should only be called once per expectation:

mock ->
  socket = new Socket()
  socket.expects("read").throws("e")                  # ok
  socket.expects("read").throws("e1").throws("e2")    # not ok

mock ->
  socket.expects("read").throws("e1")
  socket.expects("read").throws("e2")                 # not ok; TinyMock cannot handle this

throws() and returns() cannot be used on the same expectation:

mock ->
  socket.expects("read").returns("a message").throws("an error")    # not ok

Example:

chai   = require("chai")
should = chai.should()
mock   = require("TinyMock")
Chat   = require("../src/Chat")

describe "Chat", ->
  describe "greet(my_name)", ->
    it "sends a greeting and returns the response", ->
      mock (socket) ->
        socket.expects("write").args("Hello, my name is Aristotle.\n")
        socket.expects("read").throws(new Error("socket read error"))
        chat = new Chat(socket)
        (-> chat.greet("Aristotle") ).should.throw("socket read error\n")