Upgrading to 1.1 — CasperJS 1.1.0-DEV documentation

# 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;
    });