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 :doc:`casperjs test <../testing>` 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:

   .. code-block:: text

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

The new ``Tester#begin()`` method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

However, a new :ref:`begin() <tester_begin>` method as been added to the :ref:`Tester <tester_module>` 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 :doc:`Tester <../modules/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;
    });