Upgrading to 1.1

Testing framework refactor

The most visible change is the way you write tests. With 1.0, you were able to access a .test property from any casper script and so running a suite using the standard casperjs executable:

// 1.0 style test script not using the `casperjs test` subcommand
var casper = require('casper').create();

casper.start('http://foo.bar/', function() {
    this.test.assert(true);
});

casper.run(function() {
    this.test.done(1);
    this.test.renderResults(true);
});

In 1.1, the test framework has been heavily refactored to decouple the tester from a casper instance as much as possible, so it’s no more possible to run a test suite right from the standard casperjs command as you would have done with the script shown above.

Instead you now have to use the casperjs test subcommand mandatorily to access a tester instance from the casper.test property.

Warning

As of 1.1:

• you shouldn’t invoke the renderResults() method directly anymore
• you shouldn’t use the done() first argument to set planned test as it’s been deprecated
• you can’t access the casper.test property when not using the casperjs test subcommand

If you try, you’ll get an error:

// test.js
var casper = require('casper').create();
casper.test.assert(true);

Will give:

$ casperjs test.js
CasperError: casper.test property is only available using the `casperjs test` command

The new Tester#begin() method

However, a new begin() method as been added to the Tester prototype, to ease describing your tests:

casper.test.begin('Description of my test', 1, function(test) {
    test.assert(true);
    test.done();
});

More asynchronously:

casper.test.begin('Description of my test', 1, function(test) {
    casper.start('http://foo.bar/', function() {
        test.assert(true);
    });

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

Note

Please notice begin()’s second argument which is now the place to set the number of planned tests.

require() in custom modules

CasperJS 1.1 now internally uses PhantomJS’ native require() function, but it has side effect if you write your own casperjs modules; in any casperjs module, you now have to use the new global patchRequire() function first:

// casperjs module code
var require = patchRequire(require);
// now you can require casperjs builtins
var utils = require('utils');
exports = {
    // ...
};

Note

You don’t have to use patchRequire() in a standard casperjs script.

__file__ has been removed

As of 1.1, CasperJS now uses native PhantomJS’ require() function which doesn’t support the __file__ builtin variable within custom modules like 1.0 allowed.

Tester#getFailures() and Tester#getPasses() methods removed

These two methods have been removed from the Tester API.

You can retrieve test failure and success records by simply accessing tester.currentSuite.failures and tester.currentSuite.passes instead.

Step and run completion callbacks don’t throw anymore

Instead, you should listen to the step.error and complete.error events; if you really want to keep raising them:

casper.on("step.error complete.error", function(error) {
  throw error;
});