Unittesting JavaScript
with Evidence
Tobie Langel
@tobie on twitter

“Evidence in its broadest
sense includes everything
that is used to determine
or demonstrate the truth
of an assertion.”
–Wikipedia

http://github.com/tobie/evidence

Yet Another Unit Test
Framework

DOH Test.Simple/More
JSUnit TestCase
QUnit jsUnitTest
Crosscheck JSTest
J3Unit jsUnity
JSNUnit RhinoUnit
YUI Test FireUnit
JSSpec ...
unittest.js
JSpec
screw-unit

Why?

Scratching our own itch

A lot of unit tests (> 2000 assertions).

A lot of unit tests (> 2000 assertions).
Complex cases (async, cross-browser).

A lot of unit tests (> 2000 assertions).
Complex cases (async, cross-browser).
Uses a framework originally created in
2005 for script.aculo.us...

A lot of unit tests (> 2000 assertions).
Complex cases (async, cross-browser).
Uses a framework originally created in
2005 for script.aculo.us...
...with a dependency on Prototype.

#1
Framework agnostic

#2
Environment agnostic

#2
Environment agnostic
(Attempts to run in as many different
environments as possible.)

#3
Self-contained

#3
Self-contained
(Doesn’t pollute the global scope.)

#4
Reliable

#5
Built with async in mind

#6
Easier to automate

#7
Promotes better testing

“I recommend that
developers spend
25-50% of their time
developing tests.”
–Kent Beck

Drawing by Witold Riedel (http://www.witoldriedel.com)

Kent Beck’s original
white paper
Drawing by Witold Riedel (http://www.witoldriedel.com)

Kent Beck’s original
white paper
http://tr.im/kentbeck
Drawing by Witold Riedel (http://www.witoldriedel.com)

JUnit

JUnit
Kent Beck &
Erich Gamma

Test::Unit

MiniTest

unittest / PyUnit

YUI.Test

... and of course, Kent
Beck’s original Smalltalk
implementation.

(

Evidence

!=

RSpec

BDD

Why?

I don’t like BDD

&

JavaScript’s awful at
writing DSLs

unless

you’re using it’s bad
parts!

function callAssertions(fn) {
var rgxp = /^[^{]*{((.*n*)*)}/m;
fn = fn.toString();
fn = fn.match(rgxp)[1];
eval('with (dsl) {
with (context) {
with (matchers) { ' +
fn + ' }}}');
}

Function decompilation
function callAssertions(fn) {
(Not part of any standard.)
var rgxp = /^[^{]*{((.*n*)*)}/m;
fn = fn.toString();
fn = fn.match(rgxp)[1];
eval('with (dsl) {
with (context) {
with (matchers) { ' +
fn + ' }}}');
}

function callAssertions(fn) {
var rgxp = /^[^{]*{((.*n*)*)}/m;
fn = fn.toString();
fn = fn.match(rgxp)[1];
eval('with (dsl) {
with (context) {
with (matchers) { ' +
fn + ' }}}'); Nested with statements
} (Not ES5 strict compliant.)

function callAssertions(fn) {
var rgxp = /^[^{]*{((.*n*)*)}/m;
fn = fn.toString();
eval
fn = fn.match(rgxp)[1];
(Not supported in some environments.)
eval('with (dsl) {
with (context) {
with (matchers) { ' +
fn + ' }}}');
}

function callAssertions(fn) {
var rgxp = /^[^{]*{((.*n*)*)}/m;
fn = fn.toString();
fn = fn.match(rgxp)[1];
eval('with (dsl) {
with (context) {
with (matchers) { ' +
fn + ' }}}');
}

)

xUnit

xUnit

xUnit
TestCase

xUnit
TestCase
TestSuite

xUnit
TestCase
TestSuite
TestRunner

xUnit
TestCase
TestSuite
TestRunner
TestResult

Anatomy of a TestCase

var ArrayTest = Evidence.TestCase.extend('ArrayTest', {
setUp: function() {
this.array = ['foo', 'bar', 'baz'];
},
testFirst: function() {
this.assertEqual('foo', _.first(this.array));
this.assertUndefined(_.first([]));
},
testLast: function() {
this.assertEqual('bar', _.last(this.array),
'Failed to grab the last element of the array.');
this.assertUndefined(_.last([]));
}
});

var ArrayTest = Evidence.TestCase.extend('ArrayTest', {
setUp: function() {
this.array = ['foo', 'bar', 'baz'];
},
“Subclass” TestCase
testFirst: function() {
this.assertEqual('foo', _.first(this.array));
this.assertUndefined(_.first([]));
},
testLast: function() {
this.assertEqual('bar', _.last(this.array),
'Failed to grab the last element of the array.');
this.assertUndefined(_.last([]));
}
});

var ArrayTest = Evidence.TestCase.extend('ArrayTest', {
setUp: function() {
this.array = ['foo', 'bar', 'baz'];
},
Give it a name.
testFirst: function() {
this.assertEqual('foo', _.first(this.array));
this.assertUndefined(_.first([]));
},
testLast: function() {
this.assertEqual('bar', _.last(this.array),
'Failed to grab the last element of the array.');
this.assertUndefined(_.last([]));
}
});

var ArrayTest = Evidence.TestCase.extend('ArrayTest', {
setUp: function() {
this.array = ['foo', 'bar', 'baz'];
},
testFirst: function() {
Add fixtures to your _.first(this.array));
this.assertEqual('foo',
setUp method.
this.assertUndefined(_.first([]));
},
testLast: function() {
this.assertEqual('bar', _.last(this.array),
'Failed to grab the last element of the array.');
this.assertUndefined(_.last([]));
}
});

var ArrayTest = Evidence.TestCase.extend('ArrayTest', {
Prefix setUp:testcases {with
your function()
this.array = ['foo', 'bar', 'baz'];
}, test.
testFirst: function() {
this.assertEqual('foo', _.first(this.array));
this.assertUndefined(_.first([]));
},
testLast: function() {
this.assertEqual('bar', _.last(this.array),
'Failed to grab the last element of the array.');
this.assertUndefined(_.last([]));
}
});

var ArrayTest = Evidence.TestCase.extend('ArrayTest', {
setUp: function() {
this.array = ['foo', 'bar', 'baz'];
},
testFirst: function() {
this.assertEqual('foo', _.first(this.array));
this.assertUndefined(_.first([]));
},
testLast: your assertions.
Write function() {
this.assertEqual('bar', _.last(this.array),
'Failed to grab the last element of the array.');
this.assertUndefined(_.last([]));
}
});

var ArrayTest = Evidence.TestCase.extend('ArrayTest', {
setUp: function() {
this.array = ['foo', 'bar', 'baz'];
},
testFirst: function() {
this.assertEqual('foo', _.first(this.array));
this.assertUndefined(_.first([]));
},
testLast: function() {
this.assertEqual('bar', _.last(this.array),
'Failed to grab the last element of the array.');
this.assertUndefined(_.last([]));
}
Optionally add
}); meaningful error
messages.

Built-in async handling.

Evidence.TestCase.extend('AjaxTest', {
testAjaxRequest: function(testcase) {
testcase.pause();
new Ajax.Request('/some/url', {
onComplete: function(response) {
testcase.resume(function() {
this.assert(response);
});
}
});
}
});

Evidence.TestCase.extend('AjaxTest', {
testAjaxRequest: function(testcase) {
testcase.pause();
new Ajax.Request('/some/url', { instance
TestCase
onComplete: function(response) {
conveniently passed as a
testcase.resume(function() {
this.assert(response); first argument.
});
}
});
}
});

Evidence.TestCase.extend('AjaxTest', {
testAjaxRequest: function(testcase) {
No need to bind this or
testcase.pause();
create your own closure.
new Ajax.Request('/some/url', {
onComplete: function(response) {
testcase.resume(function() {
this.assert(response);
});
}
});
}
});

Evidence.TestCase.extend('AjaxTest', {
testAjaxRequest: function(testcase) {
testcase.pause();
new Ajax.Request('/some/url', {
onComplete: function(response) {
testcase.resume(function() {
this.assert(response);
});
Bound to the original
}
}); scope so:
} this === testcase
});

The TestSuite

function getTestCaseNames(testcaseClass) {
var results = [];
for (var property in testcaseClass.prototype) {
if (property.indexOf('test') === 0) {
results.push(property);
}
}
return results.sort();
}

Grab all the methods
function getTestCaseNames(testcaseClass) {
var results = []; starting with test.
for (var property in testcaseClass.prototype) {
if (property.indexOf('test') === 0) {
results.push(property);
}
}
return results.sort();
}

function getTestCaseNames(testcaseClass) {
var results = [];
for (var property in testcaseClass.prototype) {
if (property.indexOf('test') === 0) {
results.push(property);
} Sort the results.
}
return results.sort();
}

function loadTestsFromTestCase(testcaseClass) {
var suite = new TestSuite(testcaseClass.displayName),
methodNames = getTestCaseNames(testcaseClass);
for (var i = 0; i < methodNames.length; i++) {
suite.push(new testcaseClass(methodNames[i]));
}
return suite;
}

Create a new suite.
function loadTestsFromTestCase(testcaseClass) {
var suite = new TestSuite(testcaseClass.displayName),
methodNames = getTestCaseNames(testcaseClass);
for (var i = 0; i < methodNames.length; i++) {
suite.push(new testcaseClass(methodNames[i]));
}
return suite;
}

Give it a name.
function loadTestsFromTestCase(testcaseClass) {
var suite = new TestSuite(testcaseClass.displayName),
methodNames = getTestCaseNames(testcaseClass);
for (var i = 0; i < methodNames.length; i++) {
suite.push(new testcaseClass(methodNames[i]));
}
return suite;
}

function loadTestsFromTestCase(testcaseClass) {
var suite = new TestSuite(testcaseClass.displayName),
methodNames = getTestCaseNames(testcaseClass);
for (var i = 0; i < methodNames.length; i++) {
suite.push(new testcaseClass(methodNames[i]));
}
Grab the testcase names.
return suite;
}

function loadTestsFromTestCase(testcaseClass) {
var suite = new TestSuite(testcaseClass.displayName),
methodNames = getTestCaseNames(testcaseClass);
for (var i = 0; i < methodNames.length; i++) {
suite.push(new testcaseClass(methodNames[i]));
}
return suite; Create a new instance of
}
the testcase class.

function loadTestsFromTestCase(testcaseClass) {
var suite = new TestSuite(testcaseClass.displayName),
methodNames = getTestCaseNames(testcaseClass);
for (var i = 0; i < methodNames.length; i++) {
suite.push(new testcaseClass(methodNames[i]));
}
return suite;
Add it to your suite.
}

Benefits

Custom assertions

Evidence.TestCase.extend('ElementTest', {
setUp: function() {
this.element = document.createElement('div');
},
testElementExtend: function() {
var extended = Element.extend(this.element);
this.assertEqual(this.element, extended);
this.assertRespondsTo('show', extended);
// ...
},
testElementClone: function() {
var cloned = Element.clone(this.element);
this.assert(cloned.show); // is extended
// ...
}
});

Evidence.TestCase.extend('ElementTest', {
setUp: function() {
this.element = document.createElement('div');
},
What!?
testElementExtend: function() {
var extended = Element.extend(this.element);
this.assertEqual(this.element, extended);
this.assertRespondsTo('show', extended);
// ...
},
testElementClone: function() {
var cloned = Element.clone(this.element);
this.assert(cloned.show); // is extended
// ...
}
});

Evidence.TestCase.extend('ElementTest', {
setUp: function() {
this.element = document.createElement('div');
},
testElementExtend: function() {
var extended = Element.extend(this.element);
this.assertEqual(this.element, extended);
this.assertRespondsTo('show', extended);
// ...
}, Again?!
testElementClone: function() {
var cloned = Element.clone(this.element);
this.assert(cloned.show); // is extended
// ...
}
});

Evidence.TestCase.extend('ElementTest', {
setUp: function() {
this.element = document.createElement('div');
},
testElementExtend: function() {
var extended = Element.extend(this.element);
this.assertEqual(this.element, extended);
this.assertRespondsTo('show', extended);
// ...
},
testElementClone: function() {
var cloned = Element.clone(this.element);
this.assert(cloned.show); // is extended
// ...
OK, now I get it.
}
});

!= DRY

Evidence.TestCase.extend('ElementTest', {
//...
assertElementExtended: function(element, message) {
this._assertExpression(
typeof element.show === 'function',
message || 'Element is not extended.',
'Expected %o to be extended.', element
);
},
testElementExtend: function() {
var extended = Element.extend(this.element);
this.assertElementExtended(extended);
},
testElementClone: function() {
var cloned = Element.clone(this.element);
this.assertElementExtended(cloned);
}

Evidence.TestCase.extend('ElementTest', {
//...
assertElementExtended: function(element, message) {
this._assertExpression(
typeof element.show === 'function',
!
message || 'Element is not extended.',
'Expected %o to be extended.', element
);
Syntax still subject to
}, change!
testElementExtend: function() {
var extended = Element.extend(this.element);
this.assertElementExtended(extended);
},
testElementClone: function() {
var cloned = Element.clone(this.element);
this.assertElementExtended(cloned);
}

Instance methods

function getInnerHTML(element) {
var html = element.innerHTML.toString();
return html.toLowerCase().gsub(/[rnt]/, '');
}
Evidence.TestCase.extend('ElementTest', {
// ...
testElementInsert: function() {
var html = '<p>a paragraph</p>';
Element.insert(this.element, html);
this.assertEqual(html, getInnerHTML(this.element));
}
});

function getInnerHTML(element) {
var html = element.innerHTML.toString();
return html.toLowerCase().gsub(/[rnt]/, '');
}
Global scope pollution.
Evidence.TestCase.extend('ElementTest', {
// ...
testElementInsert: function() {
var html = '<p>a paragraph</p>';
Element.insert(this.element, html);
this.assertEqual(html, getInnerHTML(this.element));
}
});

function getInnerHTML(element) {
var html = element.innerHTML.toString();
return html.toLowerCase().gsub(/[rnt]/, '');
} Obscure syntax.
What’s wrong with
Evidence.TestCase.extend('ElementTest', {
//this.element.innerHTML?
...
testElementInsert: function() {
var html = '<p>a paragraph</p>';
Element.insert(this.element, html);
this.assertEqual(html, getInnerHTML(this.element));
}
});

Evidence.TestCase.extend('ElementTest', {
// ...
testElementInsert: function() {
var html = '<p>a paragraph</p>';
Element.insert(this.element, html);
this.assertEqual(html, this.getElementHTML());
},
getElementHTML: function() {
var html = this.element.innerHTML.toString();
return html.toLowerCase().gsub(/[rnt]/, '');
}
});

Evidence.TestCase.extend('ElementTest', {
// ...
Instance method!
testElementInsert: function() {
var html = '<p>a paragraph</p>';
Element.insert(this.element, html);
this.assertEqual(html, this.getElementHTML());
},
getElementHTML: function() {
var html = this.element.innerHTML.toString();
return html.toLowerCase().gsub(/[rnt]/, '');
}
});

Evidence.TestCase.extend('ElementTest', {
// ...
testElementInsert: function() {
var html = '<p>a paragraph</p>';
Element.insert(this.element, html);
this.assertEqual(html, this.getElementHTML());
},
getElementHTML: function() {
Would benefit from a
var html = this.element.innerHTML.toString();
return html.toLowerCase().gsub(/[rnt]/, '');
custom assertion too.
}
});

The TestRunner

var suite = loadTestsFromTestCase(ArrayTest);
var runner = new Evidence.Runner();
var results = runner.run(suite);

The TestResult

Logs to the console.
The TestResult

Logs to the console.
The TestResult
Prints to STDOUT.

Displays the results in Logs to the console.
a web page.
The TestResult
Prints to STDOUT.

Displays the results in Logs to the console.
a web page.
The TestResult
Sends the data back
to the server in JSON
Prints to STDOUT.
(or XML).

The Magic

All of this is good to know,

but it’s tedious.

So...

Evidence handles it for you!

Evidence.TestCase.extend('ArrayTest', {
setUp: function() {
this.array = ['foo', 'bar', 'baz'];
},
testFirst: function() {
this.assertEqual('foo', _.first(this.array));
this.assertUndefined(_.first([]));
},
testLast: function() {
this.assertEqual('bar', _.last(this.array),
'Failed to grab the last element of the array.');
this.assertUndefined(_.last([]));
}
});

It’s all you need!

?
@tobie on twitter
http://github.com/tobie/evidence
(Soon hopefully on http://evidencejs.org)