slides

space, →	next slide
←	previous slide
d	debug mode
## <ret>	go to slide #
c	table of contents (vi)
f	toggle footer
r	reload slides
z	toggle help (this)

loading presentation...

Sinon.JS

Simplifying JavaScript testing

about:me

My job: gitorious.org

Gitorious

My book

Book

Sinon.JS

http://sinonjs.org

OSI approved license

http://www.opensource.org/licenses/bsd-license.php

Design goals

Standalone

No JS library dependencies
Test framework agnostic
Run in browsers and on servers

Test frameworks

Integration hooks
Bridges with automatic sandboxing

"Proper" terminology

Terminology

XUnit test patterns

"JavaScript native"

Test spies

Definition

The Test Spy is designed to act as an observation point by recording the method calls made to it by the SUT as it is exercised.

Anonymous spy

"test should call subscriber": function () {
    var spy = sinon.spy();

    PubSub.subscribe("message", spy);
    PubSub.publishSync("message", undefined);

    assertTrue(spy.called);
}

How it works

Behaves like function () {}
All calls are recorded
Verify using assertions

Spy properties

spy.called
spy.calledOnce
spy.calledTwice
spy.calledThrice
spy.callCount

Received arguments

"test should call subscriber": function () {
    var spy = sinon.spy();

    PubSub.subscribe("message", spy);
    PubSub.publishSync("message", { id: 42 });
    PubSub.publishSync("message", [3, 4, 2]);

    // assert(???)
}

Argument matcher

"test should call subscriber": function () {
    var spy = sinon.spy();

    PubSub.subscribe("message", spy);
    PubSub.publishSync("message", { id: 42 });
    PubSub.publishSync("message", [3, 4, 2]);

    assertTrue(spy.calledWith({ id: 42 }));
}

args property

"test should call subscriber": function () {
    var spy = sinon.spy();

    PubSub.subscribe("message", spy);
    PubSub.publishSync("message", { id: 42 });
    PubSub.publishSync("message", [3, 4, 2]);

    assertTrue(spy.calledWith({ id: 42 }));
    assertEquals([3, 4, 2], spy.args[1][0]);
}

Strict matcher

"test should call subscriber": function () {
    var spy = sinon.spy();

    PubSub.subscribe("message", spy);
    PubSub.publishSync("message", "Many", "arguments");
    PubSub.publishSync("message", 12, 34);

    assertTrue(spy.calledWith("Many"));        // Passes
    assertTrue(spy.calledWithExactly("Many")); // Fails
}

Strict matcher

"test should call subscriber": function () {
    var spy = sinon.spy();

    PubSub.subscribe("message", spy);
    PubSub.publishSync("message", "Many", "arguments");
    PubSub.publishSync("message", 12, 34);

    assertTrue(spy.calledWith("Many"));
    assertTrue(spy.calledWithExactly("Many", "arguments"));
}

Strict(er) matcher

"test should call subscriber": function () {
    var spy = sinon.spy();

    PubSub.subscribe("message", spy);
    PubSub.publishSync("message", "Many", "arguments");
    PubSub.publishSync("message", "Many", 34);

    assertTrue(spy.alwaysCalledWith("Many"));        // Passes
    assertTrue(spy.alwaysCalledWithExactly("Many")); // Fails
}

Observing call order

"test should call subscriber": function () {
    var mspy = sinon.spy();
    var espy = sinon.spy();

    PubSub.subscribe("message", mspy);
    PubSub.subscribe("event", espy);
    PubSub.publishSync("message", { id: 42 });
    PubSub.publishSync("event", [3, 4, 2]);

    assertTrue(mspy.calledBefore(espy));
    assertTrue(espy.calledAfter(mspy));
}

More matchers

spy.calledOn(obj);
spy.threw();
spy.returned(obj);
Also: always* variants

Example of the evening

Todotard website

xp.todoList

add(text, callback);
all(callback);
complete(id, callback);

xp.formController

addItem();

xp.listController

init();
completeItem(itemElement);
addItem(todoItem);

Spying on methods

ListControllerInitTest

"test should fetch items from backend": function () {
    var element = document.createElement("ol");
    var list = xp.todoList.create();
    sinon.spy(list, "all");

    var controller = xp.listController.create(element, list);
    controller.init();

    assert(list.all.calledOnce);
}

How it works

Proxies original method
sinon.spy(obj, "method") == obj.method

Test stubs

Definition

The Test Stub replaces a real object with a test-specific object that feeds the desired indirect inputs into the system under test.

s/object/function/

Anonymous stub

"test should call subscriber": function () {
    var stub = sinon.stub();

    PubSub.subscribe("message", stub);
    PubSub.publishSync("message", undefined);

    assertTrue(stub.called);
}

Stubs are spies

Stubs do not proxy original methods
Stubs have an API for controlling behavior

Stubbing methods

"test should fetch items from backend": function () {
    var element = document.createElement("ol");
    var list = xp.todoList.create();
    sinon.stub(list, "all");

    var controller = xp.listController.create(element, list);
    controller.init();

    assert(list.all.calledOnce);
}

Controlling behavior

"test should attach todo items to list": function () {
    var list = xp.todoList.create();

    sinon.stub(list, "all").yields([
        { text: "Do it", id: 1, done: false },
        { text: "Run, Forest!", id: 2, done: false }]);

    // ...

Controlling behavior

    // ...

    var element = document.createElement("ol");
    var controller = xp.listController.create(element, list);
    controller.init();

    assertEquals(2, element.childNodes.length);
    assertEquals("Do it", element.childNodes[0].innerHTML);
    assertEquals("Run, Forest!", element.childNodes[1].innerHTML);
}

Modifiers

stub.yields([args...]);
stub.returns(value);
stub.throws("ErrorType");

`yields` is new in 1.1.0

Tighter callback control

Specify position of callback

"test should attach todo items to list": function () {
    var list = xp.todoList.create();

    sinon.stub(list, "all").callsArgWith(0, [
        { text: "Do it", id: 1, done: false },
        { text: "Run, Forest!", id: 2, done: false }]);

    // ...

Marking todo as complete

"test should yield updated item to callback on success": function () {
    sinon.stub(jQuery, "ajax").yieldsTo(
        "success", '{"text":"Fetch eggs","done":true,"id":1}');

    // ...

    // ...

    var list = xp.todoList.create();
    var callback = sinon.spy();

    list.completeItem(1, callback);

    assert(callback.calledOnce);
    assertEquals({ text: "Fetch eggs", done: true, id: 1 },
                 callback.args[0][0]);
}

`yieldsTo` is new in 1.1.0

Node.js

"should add item to backend": function (test) {
    this.req.method = "POST";
    this.req.body = "item=Are+you+there%3F";

    sinon.stub(this.controller.list, "add");
    controller.create(this.req, fakeHttp.res());

    test.ok(this.controller.list.add.calledOnce);
    test.ok(this.controller.list.add.calledWith("Are you there?"));
    test.done();
}

Mocks

Definition

The mock replaces an object the system under test (SUT) depends on with a test-specific object that verifies it is being used correctly by the SUT.

s/object/function/

Main difference

State expectations up-front
No need for assertions

"test should fetch items from backend": function () {
    var element = document.createElement("ol");
    var list = xp.todoList.create();
    var mock = sinon.mock(list);
    mock.expects("all");

    var controller = xp.listController.create(element, list);
    controller.init();

    mock.verify();
}

Mocks are spies and stubs

Also: Built-in expectations

"test should attach todo items to list": function () {
    var list = xp.todoList.create();
    var mock = sinon.mock(list);

    mock.expects("all").yields([
        { text: "Do it", id: 1, done: false },
        { text: "Run, Forest!", id: 2, done: false }]);

    // ...

How it works

Mock an object, set expectations on methods
Apply modifiers on expectations

Modifiers

"test should fetch items from backend": function () {
    var element = document.createElement("ol");
    var list = xp.todoList.create();
    var mock = sinon.mock(list);
    mock.expects("all").once();

    var controller = xp.listController.create(element, list);
    controller.init();

    mock.verify();
}

Call count modifiers

expectation.atLeast(number);
expectation.atMost(number);
expectation.never();
expectation.once();
expectation.twice();
expectation.thrice();
expectation.exactly(number);

Other modifiers

expectation.withArgs(arg1, arg2, ...);
expectation.withExactArgs(arg1, arg2, ...);
expectation.on(obj);

Integration hooks

sinon.test

"test something": sinon.test(function () {
    this.spy(/* ... */);
    this.stub(/* ... */);
    this.mock(/* ... */);
});

Automatic mock verification

"test should fetch items from backend": sinon.test(function () {
    var element = document.createElement("ol");
    var list = xp.todoList.create();
    this.mock(list).expects("all").once();

    var controller = xp.listController.create(element, list);
    controller.init();
})

Automatic restoration of fakes

"test should yield updated item to callback on success":
sinon.test(function () {
    this.stub(jQuery, "ajax").yieldsTo(
        "success", '{"text":"Fetch eggs","done":true,"id":1}');

    // ...
}),

"test something else": function () {
    // jQuery.ajax is live again
}

How it works

Sinon creates a sinon.sandbox
Sandbox is bound to the test instance
Sandbox is verified and restored
sinon.config is in control

sinon.testCase();

TestCase("MyTest", sinon.testCase({
    // All tests are sandboxed
}));

Feedback from tests

ListControllerInitTest

"test should fetch items from backend": function () {
    var element = document.createElement("ol");
    var list = xp.todoList.create();
    sinon.spy(list, "all");

    var controller = xp.listController.create(element, list);
    controller.init();

    assertTrue(list.all.calledOnce);
}

Problem

$ jstestdriver --tests all
...........................F....................................
Total 64 tests (Passed: 63; Fails: 1; Errors: 0) (198.00 ms)
  Firefox 3.6.13 Linux: Run 64 tests (Passed: 63; Fails: 1; Errors 0) (198.00 ms)
    ListControllerInitTest.test should fetch items from backend failed (1.00  ms): \
    expected true but was false
      /test/list_controller_test.js:56

Tests failed.

.

Problem

$ jstestdriver --tests all
...........................F....................................
Total 64 tests (Passed: 63; Fails: 1; Errors: 0) (198.00 ms)
  Firefox 3.6.13 Linux: Run 64 tests (Passed: 63; Fails: 1; Errors 0) (198.00 ms)
    ListControllerInitTest.test should fetch items from backend failed (1.00  ms): \
    expected true but was false
      /test/list_controller_test.js:56

Tests failed.

"expected true but was false"

ListControllerInitTest

"test should fetch items from backend": function () {
    var element = document.createElement("ol");
    var list = xp.todoList.create();
    sinon.spy(list, "all");

    var controller = xp.listController.create(element, list);
    controller.init();

    sinon.assert.calledOnce(list.all);
}

With Sinon assertion

$ jstestdriver --tests all
...........................F....................................
Total 64 tests (Passed: 63; Fails: 1; Errors: 0) (198.00 ms)
  Firefox 3.6.13 Linux: Run 64 tests (Passed: 63; Fails: 1; Errors 0) (198.00 ms)
    ListControllerInitTest.test should fetch items from backend failed (1.00  ms): \
    expected all to be called once but was called twice
      /test/list_controller_test.js:56

Tests failed.

.

With Sinon assertion

$ jstestdriver --tests all
...........................F....................................
Total 64 tests (Passed: 63; Fails: 1; Errors: 0) (198.00 ms)
  Firefox 3.6.13 Linux: Run 64 tests (Passed: 63; Fails: 1; Errors 0) (198.00 ms)
    ListControllerInitTest.test should fetch items from backend failed (1.00  ms): \
    expected all to be called once but was called twice
      /test/list_controller_test.js:56

Tests failed.

"expected all to be called once but was called twice"

How it works

Fails through sinon.assert.fail
Provides detailed error messages

More assertions

sinon.assert.called(spy);
sinon.assert.calledWith(spy, args...);
sinon.assert.calledBefore(spy, otherSpy);
Many more: http://sinonjs.org/docs/

QUnit integration

sinon.assert.fail = function (msg) {
    QUnit.ok(false, msg);
};

Adapters

QUnit adapter

Uses sinon.test();
30 lines, including default config
Use this.{spy,stub.mock}

Example

test("should fetch items from backend": function () {
    var element = document.createElement("ol");
    var list = xp.todoList.create();
    this.spy(list, "all");

    var controller = xp.listController.create(element, list);
    controller.init();

    sinon.assert.calledOnce(list.all);
});

Run test

QUnit test

Testing challenges

Timers (browsers, server)
XMLHttpRequest (browsers)

Faking timers

Flash messages

"test should fade out element after 2secs": function () {
    var p = jQuery(xp.flash.message("Uh-oh!"));
    p.appendTo(document.body);
    var height = p.height();

    // ???

    assertEquals(0, p.height());
    assertEquals(0, p.parent().length);
}

setUp: function () {
    this.clock = sinon.useFakeTimers();
},

tearDown: function () {
    this.clock.restore();
}

"test should fade out element after 2secs": function () {
    var p = jQuery(xp.flash.message("Uh-oh!"));
    p.appendTo(document.body);
    var height = p.height();

    this.clock.tick(2000);
    assertEquals(1, p.parent().length);

"test should fade out element after 2secs": function () {
    var p = jQuery(xp.flash.message("Uh-oh!"));
    p.appendTo(document.body);
    var height = p.height();

    this.clock.tick(2000);
    assertEquals(1, p.parent().length);

    this.clock.tick(160);
    assert(p.height() < height);

"test should fade out element after 2secs": function () {
    var p = jQuery(xp.flash.message("Uh-oh!"));
    p.appendTo(document.body);
    var height = p.height();

    this.clock.tick(2000);
    assertEquals(1, p.parent().length);

    this.clock.tick(160);
    assert(p.height() < height);

    this.clock.tick(160);
    assertEquals(0, p.height());
    assertEquals(0, p.parent().length);
}

How it works

Explicitly tell Sinon to hijack time
Sinon replaces setTimeout and friends
use clock.tick(ms); to pass time

Manual setup

setUp: function () {
    this.clock = sinon.useFakeTimers();
},

tearDown: function () {
    this.clock.restore();
},

"test something": function () {
    this.clock.tick(15);        
}

Using sinon.test

"test should automatically restore timers": sinon.test(function () {
    this.clock.tick(45);
});

Faking XMLHttpRequest

TodoListAddTest

setUp: function () {
    this.fakeXhr = sinon.useFakeXMLHttpRequest();
    var requests = this.requests = [];

    this.fakeXhr.onCreate = function (xhr) {
        requests.push(xhr);
    };
},

tearDown: function () {
    this.fakeXhr.restore();
}

(cont)

"test should POST to /todo-items": function () {
    var list = xp.todoList.create();
    list.add("Fetch eggs from the store");

    assertEquals(1, this.requests.length);
    assertEquals("POST", this.requests[0].method);
    assertEquals("/todo-items", this.requests[0].url);
}

How it works

Explicitly tell Sinon to hijack XMLHttpRequest
Inspect request data
Restore XMLHttpRequest

With sandboxing

"test should POST to /todo-items": sinon.test(function () {
    var list = xp.todoList.create();
    list.add("Fetch eggs from the store");

    assertEquals(1, this.requests.length);
    assertEquals("POST", this.requests[0].method);
    assertEquals("/todo-items", this.requests[0].url);
})

No manual setUp/tearDown required

Responding to request

"test should yield list item to callback on success": function () {
    var list = xp.todoList.create();
    var callback = sinon.spy();

    list.add("Fetch eggs", callback);
    // ...
}

"test should yield list item to callback on success": function () {
    var list = xp.todoList.create();
    var callback = sinon.spy();

    list.add("Fetch eggs", callback);
    this.requests[0].respond(
         200, { "Content-Type": "application/json" },
         '{"text":"Fetch eggs","done":false,"id":1}');

    assert(callback.calledOnce);
    assertEquals({ text: "Fetch eggs", done: false, id: 1 },
                 callback.args[0][0]);
}

Fake server

setUp: function () {
    this.server.respondWith(
        "POST", "/todo-items",
        [200, { "Content-Type": "application/json" },
         '{"text":"Fetch eggs","done":false,"id":1}']);
}

Fake server

"test should yield list item to callback on success": function () {
    var list = xp.todoList.create();
    var callback = sinon.spy();

    list.add("Fetch eggs", callback);
    this.server.respond();

    assert(callback.calledOnce);
    assertEquals({ text: "Fetch eggs", done: false, id: 1 },
                 callback.args[0][0]);
}

Sinon.JS

Simplifying JavaScript testing

about:me

My job: gitorious.org

My book

Sinon.JS

http://sinonjs.org

Design goals

Standalone

Test frameworks

"Proper" terminology

Terminology

"JavaScript native"

Test spies

Definition

Anonymous spy

How it works

Spy properties

Received arguments

Argument matcher

args property

Strict matcher

Strict matcher

Strict(er) matcher

Observing call order

More matchers

Example of the evening

xp.todoList

xp.formController

xp.listController

Spying on methods

ListControllerInitTest

How it works

Test stubs

Definition

s/object/function/

Anonymous stub

Stubs are spies

Stubbing methods

Controlling behavior

Controlling behavior

Modifiers

yields is new in 1.1.0

Tighter callback control

Specify position of callback

Marking todo as complete

yieldsTo is new in 1.1.0

Node.js

Mocks

Definition

s/object/function/

Main difference

Mocks are spies and stubs

Also: Built-in expectations

How it works

Modifiers

Call count modifiers

Other modifiers

Integration hooks

sinon.test

Automatic mock verification

Automatic restoration of fakes

How it works

sinon.testCase();

Feedback from tests

ListControllerInitTest

Problem

.

Problem

"expected true but was false"

ListControllerInitTest

With Sinon assertion

.

With Sinon assertion

"expected all to be called once but was called twice"

How it works

More assertions

QUnit integration

Adapters

QUnit adapter

`yields` is new in 1.1.0

`yieldsTo` is new in 1.1.0