tikiwiki/packages/tiki-pkg-casperjs/jerome-breton/casperjs/docs/upgrading/1.1.rst
2023-11-20 20:52:04 +00:00

113 lines
3.7 KiB
ReStructuredText
Executable File

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