ExpectThat

ExpectThat is a CoffeeScript library that helps you write expressive, self-documenting unit tests. ExpectThat currently supports Mocha, Pavlov, QUnit, and Jasmine.

The goals of ExpectThat are:

• to make the unit test code speak for itself (no need to write the same thing in a comment or test name).
• to provide human readable unit test assertions.
• to leverage existing test frameworks, while at the same time adapting them to CoffeScript in new ways.

How To Get It

For Node.js + Jasmine-Node use NPM

npm install expectThat.jasmine-node

Once installed, the following command can be run

expectThat.jasmine-node '<relative path to spec files>'

or see the jasmine-node example in the expectThat solution and test it out by running the following command

node runspecs.js

For Node.js + Mocha use NPM

npm install expectThat.mocha

Once installed, add require('expectThat.mocha'); to the top of the spec files and run mocha as you normally would. i.e.

mocha '<spec file>' --reporter spec

For Visual Studio use NuGet

install-package expectThat.Pavlov

install-package expectThat.QUnit

install-package expectThat.Jasmine

install-package expectThat.Mocha

Getting Started

With ExpectThat, you can write unit tests like this:

One object equals or does not equal another:

expectThat -> 1.should equal 1

expectThat -> 1.shouldnt equal 2

An object is true or false

expectThat -> ("b"+"ar" is "bar").should be true

expectThat -> ("foo" is "baz").shouldnt be true

expectThat -> ("b"+"az" is "bar").should be false

expectThat -> ("b" + "az" is "baz").shouldnt be false

expectThat -> (null is null).should be true

expectThat -> ("" is null).should be false

expectThat -> (undefined is undefined).should be true

expectThat -> ("" is undefined).should be false

A number is or is not greater than or less than another

expectThat -> 10.1.should be greaterThan 10

expectThat -> 9.shouldnt be greaterThan 10

expectThat -> 10.1.should be lessThan 10.2

expectThat -> 10.1.shouldnt be lessThan 10

A number is or is not greater than or equal to or less than or equal to another

expectThat -> 10.should be greaterThanOrEqual to 10

expectThat -> 9.9.shouldnt be greaterThanOrEqual to 10

expectThat -> (10.0).should be lessThanOrEqual to 10

expectThat -> 10.1.shouldnt be lessThanOrEqual to 10

An object is strictly equal (i.e. is or ===) to another

testFn = ->
testFn2 = ->

expectThat -> testFn.should be strictlyEqual to testFn

expectThat -> testFn.shouldnt be strictlyEqual to testFn2

A function throws an exception

expectThat -> (-> throw "test exception").should throwException

A function throws an exception with a specific exception message (Note: The exception message must match exactly.)

expectThat -> (-> throw "test exception").should throwException "test exception"

Most assertions can be created using the be and/or to keywords:

expectThat -> 1.shouldnt be equal to 2

expectThat -> ("b"+"ar" is "bar").should be true

expectThat -> ("b" + "az" is "baz").shouldnt be false

While most of the time it is desirable to allow the code to dictate the test name, there may be times when you wish to have more control. Because of this, version 0.2.1.0+ provides a way to explicitly state the test name. Here's an example:

expectThat "Some Test Name", -> foo.should equal "bar"

Examples

The following are examples of ExpectThat in use with Pavlov.js (https://github.com/mmonteleone/pavlov), QUnit (https://github.com/jquery/qunit), and Jasmine (https://github.com/pivotal/jasmine/) as well as Mocha (http://visionmedia.github.com/mocha/) respectively. Note: More extensive examples can be found in the example folder ( https://github.com/dmohl/expectThat/tree/master/example ).

Pavlov:

pavlov.specify "expectThat Specifications", ->
    describe "When testing should equal", ->
        foo = undefined
        before ->
            foo = "bar"
        after ->
            foo = "baz"
        expectThat -> foo.should equal "bar"
        expectThat -> foo.shouldnt equal "baz"
        expectThat -> (foo + "test").shouldnt equal "bartest2"
        expectThat -> foo.should be equal to "bar"
        expectThat -> foo.shouldnt be equal to "bah"

QUnit:

module "When testing should equal"

foo = "bar"

expectThat -> foo.should equal "bar"
expectThat -> foo.shouldnt equal "baz"
expectThat -> (foo + "test").shouldnt equal "bartest2"
expectThat -> foo.should be equal to "bar"
expectThat -> foo.shouldnt be equal to "bah"

Jasmine and Mocha (BDD):

describe "Example Specifications", ->
    foo = "bar"
    describe "When testing should equal", ->
        expectThat -> foo.should equal "bar"
    describe "When testing shouldnt equal", ->
        expectThat -> foo.shouldnt equal "baz"
    describe "When testing for true", ->
        expectThat -> (foo is "bar").should be true
        expectThat -> (foo is "baz").shouldnt be true
    describe "When testing for false", ->
        expectThat -> (foo is "baz").should be false
        expectThat -> (foo is "bar").shouldnt be false

ExpectThat also supports custom matchers. Any matcher that evaluates to true/false can be created. Here's an example of a custom matcher for Pavlov. Examples for QUnit and Jasmine are available in the example folder of this project - https://github.com/dmohl/expectThat/tree/master/example ):

((expectThat) ->
    myCustomMatchers =
        atleastTwoGreaterThan: (expected) ->
            "assertionType": "atleastTwoGreaterThan"
            "expected": expected
            "expr": (actual, expected) -> actual >= expected + 2

    expectThat.util.extend pavlov.api, myCustomMatchers
) expectThat

Using ExpectThat with JavaScript

While the syntax of ExpectThat is especially well suited and specifically designed for CoffeeScript, it can also be used in JavaScript. Here's a Pavlov example:

pavlov.specify("expectThat Specifications", function() {
    describe("When testing should equal", function() {
        var foo = "bar";
        expectThat(function() {
            foo.should(equal("bar"));
        });
        expectThat(function() {
            (foo + "test").should(equal("bartest"));
        });
    });
});