The tester module

Casper ships with a tester module and a Tester class providing an API for unit & functional testing purpose. By default you can access an instance of this class through the test property of any Casper class instance.

The Tester prototype

assert()

Signature: assert(Boolean condition[, String message])

Asserts that the provided condition strictly resolves to a boolean true:

casper.test.assert(true, "true's true");
casper.test.assert(!false, "truth is out");

assertDoesntExist()

Signature: assertDoesntExist(String selector[, String message])

Asserts that an element matching the provided :ref:`selector expression <selectors>` doesn't exists within the remote DOM environment:

casper.test.begin('assertDoesntExist() tests', 1, function(test) {
    casper.start().then(function() {
        this.setContent('<div class="heaven"></div>');
        test.assertDoesntExist('.taxes');
    }).run(function() {
        test.done();
    });
});

assertEquals()

Signature: assertEquals(mixed testValue, mixed expected[, String message])

Asserts that two values are strictly equivalent:

casper.test.begin('assertEquals() tests', 3, function(test) {
    test.assertEquals(1 + 1, 2);
    test.assertEquals([1, 2, 3], [1, 2, 3]);
    test.assertEquals({a: 1, b: 2}, {a: 1, b: 2});
    test.done();
});

assertEval()

Signature: assertEval(Function fn[, String message, Mixed arguments])

Asserts that a :ref:`code evaluation in remote DOM <casper_evaluate>` strictly resolves to a boolean true:

casper.test.begin('assertEval() tests', 1, function(test) {
    casper.start().then(function() {
        this.setContent('<div class="heaven">beer</div>');
        test.assertEval(function() {
            return __utils__.findOne('.heaven').textContent === 'beer';
        });
    }).run(function() {
        test.done();
    });
});

assertEvalEquals()

Signature: assertEvalEquals(Function fn, mixed expected[, String message, Mixed arguments])

Asserts that the result of a :ref:`code evaluation in remote DOM <casper_evaluate>` strictly equals to the expected value:

casper.test.begin('assertEvalEquals() tests', 1, function(test) {
    casper.start().then(function() {
        this.setContent('<div class="heaven">beer</div>');
        test.assertEvalEquals(function() {
            return __utils__.findOne('.heaven').textContent;
        }, 'beer');
    }).run(function() {
        test.done();
    });
});

assertElementCount()

Signature: assertElementCount(String selector, Number count[, String message])

Asserts that a :ref:`selector expression <selectors>` matches a given number of elements:

casper.test.begin('assertElementCount() tests', 3, function(test) {
    casper.start().then(function() {
        this.page.content = '<ul><li>1</li><li>2</li><li>3</li></ul>';
        test.assertElementCount('ul', 1);
        test.assertElementCount('li', 3);
        test.assertElementCount('address', 0);
    }).run(function() {
        test.done();
    });
});

assertExists()

Signature: assertExists(String selector[, String message])

Asserts that an element matching the provided :ref:`selector expression <selectors>` exists in remote DOM environment:

casper.test.begin('assertExists() tests', 1, function(test) {
    casper.start().then(function() {
        this.setContent('<div class="heaven">beer</div>');
        test.assertExists('.heaven');
    }).run(function() {
        test.done();
    });
});

assertFalsy()

Signature: assertFalsy(Mixed subject[, String message])

Asserts that a given subject is falsy.

assertField()

Signature: assertField(String|Object input, String expected[, String message, Object options])

Asserts that a given form field has the provided value with input name or :ref:`selector expression <selectors>`:

casper.test.begin('assertField() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        this.fill('form[name="gs"]', { q: 'plop' }, false);
        test.assertField('q', 'plop');
    }).run(function() {
        test.done();
    });
});

// Path usage with type 'css'
casper.test.begin('assertField() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        this.fill('form[name="gs"]', { q: 'plop' }, false);
        test.assertField({type: 'css', path: '.q.foo'}, 'plop');
    }).run(function() {
        test.done();
    });
});

This also works with any input type: select, textarea, etc.

The options parameter allows to set the options to use with :ref:`ClientUtils#getFieldValue() <clientutils_getfieldvalue>`.

input parameter introspects whether or not a type key is passed in with xpath or css and a property path specified along with it.

assertFieldName()

Signature: assertFieldName(String inputName, String expected[, String message, Object options])

Asserts that a given form field has the provided value:

casper.test.begin('assertField() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        this.fill('form[name="gs"]', { q: 'plop' }, false);
        test.assertField('q', 'plop', 'did not plop', {formSelector: 'plopper'});
    }).run(function() {
        test.done();
    });
});

assertFieldCSS()

Signature: assertFieldCSS(String cssSelector, String expected, String message)

Asserts that a given form field has the provided value given a CSS selector:

casper.test.begin('assertField() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        this.fill('form[name="gs"]', { q: 'plop' }, false);
        test.assertField('q', 'plop', 'did not plop', 'input.plop');
    }).run(function() {
        test.done();
    });
});

assertFieldXPath()

Signature: assertFieldXPath(String xpathSelector, String expected, String message)

Asserts that a given form field has the provided value given a XPath selector:

casper.test.begin('assertField() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        this.fill('form[name="gs"]', { q: 'plop' }, false);
        test.assertField('q', 'plop', 'did not plop', '/html/body/form[0]/input[1]');
    }).run(function() {
        test.done();
    });
});

assertHttpStatus()

Signature: assertHttpStatus(Number status[, String message])

Asserts that current HTTP status code is the same as the one passed as argument:

casper.test.begin('casperjs.org is up and running', 1, function(test) {
    casper.start('http://casperjs.org/', function() {
        test.assertHttpStatus(200);
    }).run(function() {
        test.done();
    });
});

assertMatch()

Signature: assertMatch(mixed subject, RegExp pattern[, String message])

Asserts that a provided string matches a provided javascript RegExp pattern:

casper.test.assertMatch('Chuck Norris', /^chuck/i, 'Chuck Norris\' first name is Chuck');

assertNot()

Signature: assertNot(mixed subject[, String message])

Asserts that the passed subject resolves to some falsy value:

casper.test.assertNot(false, "Universe is still operational");

assertNotEquals()

Signature: assertNotEquals(mixed testValue, mixed expected[, String message])

Asserts that two values are not strictly equals:

casper.test.assertNotEquals(true, "true");

assertNotVisible()

Signature: assertNotVisible(String selector[, String message])

Asserts that the element matching the provided :ref:`selector expression <selectors>` is not visible:

casper.test.begin('assertNotVisible() tests', 1, function(test) {
    casper.start().then(function() {
        this.setContent('<div class="foo" style="display:none>boo</div>');
        test.assertNotVisible('.foo');
    }).run(function() {
        test.done();
    });
});

assertRaises()

Signature: assertRaises(Function fn, Array args[, String message])

Asserts that the provided function called with the given parameters raises a javascript Error:

casper.test.assertRaises(function(throwIt) {
    if (throwIt) {
        throw new Error('thrown');
    }
}, [true], 'Error has been raised.');

casper.test.assertRaises(function(throwIt) {
    if (throwIt) {
        throw new Error('thrown');
    }
}, [false], 'Error has been raised.'); // fails

assertSelectorDoesntHaveText()

Signature: assertSelectorDoesntHaveText(String selector, String text[, String message])

Asserts that given text does not exist in all the elements matching the provided :ref:`selector expression <selectors>`:

casper.test.begin('assertSelectorDoesntHaveText() tests', 1, function(test) {
    casper.start('http://google.com/', function() {
        test.assertSelectorDoesntHaveText('title', 'Yahoo!');
    }).run(function() {
        test.done();
    });
});

assertSelectorHasText()

Signature: assertSelectorHasText(String selector, String text[, String message])

Asserts that given text exists in elements matching the provided :ref:`selector expression <selectors>`:

casper.test.begin('assertSelectorHasText() tests', 1, function(test) {
    casper.start('http://google.com/', function() {
        test.assertSelectorHasText('title', 'Google');
    }).run(function() {
        test.done();
    });
});

assertResourceExists()

Signature: assertResourceExists(Function testFx[, String message])

The testFx function is executed against all loaded assets and the test passes when at least one resource matches:

casper.test.begin('assertResourceExists() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        test.assertResourceExists(function(resource) {
            return resource.url.match('logo3w.png');
        });
    }).run(function() {
        test.done();
    });
});

Shorter:

casper.test.begin('assertResourceExists() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        test.assertResourceExists('logo3w.png');
    }).run(function() {
        test.done();
    });
});

assertTextExists()

Signature: assertTextExists(String expected[, String message])

Asserts that body plain text content contains the given string:

casper.test.begin('assertTextExists() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        test.assertTextExists('google', 'page body contains "google"');
    }).run(function() {
        test.done();
    });
});

assertTextDoesntExist()

Signature: assertTextDoesntExist(String unexpected[, String message])

Asserts that body plain text content doesn't contain the given string:

casper.test.begin('assertTextDoesntExist() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        test.assertTextDoesntExist('bing', 'page body does not contain "bing"');
    }).run(function() {
        test.done();
    });
});

assertTitle()

Signature: assertTitle(String expected[, String message])

Asserts that title of the remote page equals to the expected one:

casper.test.begin('assertTitle() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        test.assertTitle('Google', 'google.fr has the correct title');
    }).run(function() {
        test.done();
    });
});

assertTitleMatch()

Signature: assertTitleMatch(RegExp pattern[, String message])

Asserts that title of the remote page matches the provided RegExp pattern:

casper.test.begin('assertTitleMatch() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        test.assertTitleMatch(/Google/, 'google.fr has a quite predictable title');
    }).run(function() {
        test.done();
    });
});

assertTruthy()

Signature: assertTruthy(Mixed subject[, String message])

Asserts that a given subject is truthy.

assertType()

Signature: assertType(mixed input, String type[, String message])

Asserts that the provided input is of the given type:

casper.test.begin('assertType() tests', 1, function suite(test) {
    test.assertType(42, "number", "Okay, 42 is a number");
    test.assertType([1, 2, 3], "array", "We can test for arrays too!");
    test.done();
});

assertInstanceOf()

Signature: assertInstanceOf(mixed input, Function constructor[, String message])

Asserts that the provided input is of the given constructor:

function Cow() {
    this.moo = function moo() {
        return 'moo!';
    };
}
casper.test.begin('assertInstanceOf() tests', 2, function suite(test) {
    var daisy = new Cow();
    test.assertInstanceOf(daisy, Cow, "Ok, daisy is a cow.");
    test.assertInstanceOf(["moo", "boo"], Array, "We can test for arrays too!");
    test.done();
});

assertUrlMatch()

Signature: assertUrlMatch(Regexp pattern[, String message])

Asserts that the current page url matches the provided RegExp pattern:

casper.test.begin('assertUrlMatch() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        test.assertUrlMatch(/^http:\/\//, 'google.fr is served in http://');
    }).run(function() {
        test.done();
    });
});

assertVisible()

Signature: assertVisible(String selector[, String message])

Asserts that the element matching the provided :ref:`selector expression <selectors>` is visible:

casper.test.begin('assertVisible() tests', 1, function(test) {
    casper.start('http://www.google.fr/', function() {
        test.assertVisible('h1');
    }).run(function() {
        test.done();
    });
});

begin()

Signatures:

• begin(String description, Number planned, Function suite)
• begin(String description, Function suite)
• begin(String description, Number planned, Object config)
• begin(String description, Object config)

Starts a suite of <planned> tests (if defined). The suite callback will get the current Tester instance as its first argument:

function Cow() {
    this.mowed = false;
    this.moo = function moo() {
        this.mowed = true; // mootable state: don't do that
        return 'moo!';
    };
}

// unit style synchronous test case
casper.test.begin('Cow can moo', 2, function suite(test) {
    var cow = new Cow();
    test.assertEquals(cow.moo(), 'moo!');
    test.assert(cow.mowed);
    test.done();
});

A more asynchronous example:

casper.test.begin('Casperjs.org is navigable', 2, function suite(test) {
    casper.start('http://casperjs.org/', function() {
        test.assertTitleMatches(/casperjs/i);
        this.clickLabel('Testing');
    });

    casper.then(function() {
        test.assertUrlMatches(/testing\.html$/);
    });

    casper.run(function() {
        test.done();
    });
});

Tester#begin() also accepts a test configuration object, so you can add setUp() and tearDown() methods:

// cow-test.js
casper.test.begin('Cow can moo', 2, {
    setUp: function(test) {
        this.cow = new Cow();
    },

    tearDown: function(test) {
        this.cow.destroy();
    },

    test: function(test) {
        test.assertEquals(this.cow.moo(), 'moo!');
        test.assert(this.cow.mowed);
        test.done();
    }
});

colorize()

Signature: colorize(String message, String style)

Render a colorized output. Basically a proxy method for Casper.Colorizer#colorize().

comment()

Signature: comment(String message)

Writes a comment-style formatted message to stdout:

casper.test.comment("Hi, I'm a comment");

done()

Signature: done()

Flag a test suite started with begin() as processed:

casper.test.begin('my test suite', 2, function(test) {
    test.assert(true);
    test.assertNot(false);
    test.done();
});

More asynchronously:

casper.test.begin('Casperjs.org is navigable', 2, function suite(test) {
    casper.start('http://casperjs.org/', function() {
        test.assertTitleMatches(/casperjs/i);
        this.clickLabel('Testing');
    });

    casper.then(function() {
        test.assertUrlMatches(/testing\.html$/);
    });

    casper.run(function() {
        test.done();
    });
});

error()

Signature: error(String message)

Writes an error-style formatted message to stdout:

casper.test.error("Hi, I'm an error");

fail()

Signature: fail(String message [, Object option])

Adds a failed test entry to the stack:

casper.test.fail("Georges W. Bush");
casper.test.fail("Here goes a really long and expressive message", {name:'shortfacts'});

formatMessage()

Signature: formatMessage(String message, String style)

Formats a message to highlight some parts of it. Only used internally by the tester.

getFailures()

Signature: getFailures()

Retrieves failures for current test suite:

casper.test.assertEquals(true, false);
require('utils').dump(casper.test.getFailures());
casper.test.done();

That will give something like this:

$ casperjs test test-getFailures.js
Test file: test-getFailures.js
FAIL Subject equals the expected value
#    type: assertEquals
#    subject: true
#    expected: false
{
    "length": 1,
    "cases": [
        {
            "success": false,
            "type": "assertEquals",
            "standard": "Subject equals the expected value",
            "file": "test-getFailures.js",
            "values": {
                "subject": true,
                "expected": false
            }
        }
    ]
}
FAIL 1 tests executed, 0 passed, 1 failed.

Details for the 1 failed test:

In c.js:0
   assertEquals: Subject equals the expected value

var failures = [];

casper.test.on("fail", function(failure) {
  failures.push(failure);
});

getPasses()

Signature: getPasses()

Retrieves a report for successful test cases in the current test suite:

casper.test.assertEquals(true, true);
require('utils').dump(casper.test.getPasses());
casper.test.done();

That will give something like this:

$ casperjs test test-getPasses.js
Test file: test-getPasses.js
PASS Subject equals the expected value
{
    "length": 1,
    "cases": [
        {
            "success": true,
            "type": "assertEquals",
            "standard": "Subject equals the expected value",
            "file": "test-getPasses.js",
            "values": {
                "subject": true,
                "expected": true
            }
        }
    ]
}
PASS 1 tests executed, 1 passed, 0 failed.

var successes = [];

casper.test.on("success", function(success) {
  successes.push(success);
});

info()

Signature: info(String message)

Writes an info-style formatted message to stdout:

casper.test.info("Hi, I'm an informative message.");

pass()

Signature: pass(String message)

Adds a successful test entry to the stack:

casper.test.pass("Barrack Obama");

renderResults()

Signature: renderResults(Boolean exit, Number status, String save)

Render test results, save results in an XUnit formatted file, and optionally exits phantomjs:

casper.test.renderResults(true, 0, 'test-results.xml');

setUp()

Signature: setUp([Function fn])

Defines a function which will be executed before every test defined using begin():

casper.test.setUp(function() {
    casper.start().userAgent('Mosaic 0.1');
});

To perform asynchronous operations, use the done argument:

casper.test.setUp(function(done) {
    casper.start('http://foo').then(function() {
        // ...
    }).run(done);
});

skip()

Signature: skip(Number nb, String message)

Skips a given number of planned tests:

casper.test.begin('Skip tests', 4, function(test) {
    test.assert(true, 'First test executed');
    test.assert(true, 'Second test executed');
    test.skip(2, 'Two tests skipped');
    test.done();
});

tearDown()

Signature: tearDown([Function fn])

Defines a function which will be executed before after every test defined using begin():

casper.test.tearDown(function() {
    casper.echo('See ya');
});

To perform asynchronous operations, use the done argument:

casper.test.tearDown(function(done) {
    casper.start('http://foo/goodbye').then(function() {
        // ...
    }).run(done);
});