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.
Note
The best way to learn how to use the Tester API and see it in action is probably to have a look at CasperJS’ own test suites.
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");
See also
assertDoesntExist()
¶
Signature: assertDoesntExist(String selector[, String message])
Asserts that an element matching the provided selector expression 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();
});
});
See also
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();
});
See also
assertEval()
¶
Signature: assertEval(Function fn[, String message, Mixed arguments])
Asserts that a code evaluation in remote DOM 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 code evaluation in remote DOM 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 selector expression 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 selector expression 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();
});
});
See also
assertFalsy()
¶
Signature: assertFalsy(Mixed subject[, String message])
New in version 1.0.
Asserts that a given subject is falsy.
See also
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 selector expression:
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();
});
});
New in version 1.0.
This also works with any input type: select
, textarea
, etc.
New in version 1.1.
The options parameter allows to set the options to use with 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])
New in version 1.1-beta3.
Asserts that a given form field has the provided value:
casper.test.begin('assertFieldName() tests', 1, function(test) {
casper.start('http://www.google.fr/', function() {
this.fill('form[name="gs"]', { q: 'plop' }, false);
test.assertFieldName('q', 'plop', 'did not plop', {formSelector: 'plopper'});
}).run(function() {
test.done();
});
});
assertFieldCSS()
¶
Signature: assertFieldCSS(String cssSelector, String expected, String message)
New in version 1.1.
Asserts that a given form field has the provided value given a CSS selector:
casper.test.begin('assertFieldCSS() tests', 1, function(test) {
casper.start('http://www.google.fr/', function() {
this.fill('form[name="gs"]', { q: 'plop' }, false);
test.assertFieldCSS('q', 'plop', 'did not plop', 'input.plop');
}).run(function() {
test.done();
});
});
assertFieldXPath()
¶
Signature: assertFieldXPath(String xpathSelector, String expected, String message)
New in version 1.1.
Asserts that a given form field has the provided value given a XPath selector:
casper.test.begin('assertFieldXPath() tests', 1, function(test) {
casper.start('http://www.google.fr/', function() {
this.fill('form[name="gs"]', { q: 'plop' }, false);
test.assertFieldXPath('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');
See also
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");
See also
assertNotEquals()
¶
Signature: assertNotEquals(mixed testValue, mixed expected[, String message])
New in version 0.6.7.
Asserts that two values are not strictly equals:
casper.test.assertNotEquals(true, "true");
See also
assertNotVisible()
¶
Signature: assertNotVisible(String selector[, String message])
Asserts that the element matching the provided selector expression 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();
});
});
See also
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 selector expression:
casper.test.begin('assertSelectorDoesntHaveText() tests', 1, function(test) {
casper.start('http://google.com/', function() {
test.assertSelectorDoesntHaveText('title', 'Yahoo!');
}).run(function() {
test.done();
});
});
See also
assertSelectorHasText()
¶
Signature: assertSelectorHasText(String selector, String text[, String message])
Asserts that given text exists in elements matching the provided selector expression:
casper.test.begin('assertSelectorHasText() tests', 1, function(test) {
casper.start('http://google.com/', function() {
test.assertSelectorHasText('title', 'Google');
}).run(function() {
test.done();
});
});
See also
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();
});
});
Hint
Check the documentation for Casper.resourceExists().
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();
});
});
See also
assertTextDoesntExist()
¶
Signature: assertTextDoesntExist(String unexpected[, String message])
New in version 1.0.
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();
});
});
See also
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();
});
});
See also
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();
});
});
See also
assertTruthy()
¶
Signature: assertTruthy(Mixed subject[, String message])
New in version 1.0.
Asserts that a given subject is truthy.
See also
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();
});
Note
Type names are always expressed in lower case.
assertInstanceOf()
¶
Signature: assertInstanceOf(mixed input, Function constructor[, String message])
New in version 1.1.
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 at least one element matching the provided selector expression is visible:
casper.test.begin('assertVisible() tests', 1, function(test) {
casper.start('http://www.google.fr/', function() {
test.assertVisible('h1');
}).run(function() {
test.done();
});
});
See also
assertAllVisible()
¶
Signature: assertAllVisible(String selector[, String message])
Asserts that all elements matching the provided selector expression are visible:
casper.test.begin('assertAllVisible() tests', 1, function(test) {
casper.start('http://www.google.fr/', function() {
test.assertAllVisible('input[type="submit"]');
}).run(function() {
test.done();
});
});
See also
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)
New in version 1.1.
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();
});
Note
The planned
argument is especially useful in case a given test script is abruptly interrupted leaving you with no obvious way to know it and an erroneously successful status.
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();
});
});
Important
done() must be called in order to terminate the suite. This is specially important when doing asynchronous tests so ensure it’s called when everything has actually been performed.
See also
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()
Changed in version 1.1: planned
parameter is deprecated
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();
});
});
See also
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'});
See also
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()
New in version 1.0.
Deprecated since version 1.1.
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
Note
In CasperJS 1.1, you can recorded test failures by listening to the tester fail
event:
var failures = [];
casper.test.on("fail", function(failure) {
failures.push(failure);
});
getPasses()
¶
Signature: getPasses()
New in version 1.0.
Deprecated since version 1.1.
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.
Note
In CasperJS 1.1, you can recorded test successes by listening to the tester success
event:
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");
See also
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');
Note
This method is not to be called when using the casperjs test
command (see documentation for testing), where it’s done automatically for you.
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);
});
Warning
Don’t specify the done
argument if you don’t intend to use the method asynchronously.
See also
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 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);
});
Warning
Don’t specify the done
argument if you don’t intend to use the method asynchronously.
See also