Events & filters¶
CasperJS provides an event handler very similar to the nodejs‘ one; actually it borrows most of its codebase. CasperJS also adds filters, which are basically ways to alter values asynchronously.
Events¶
Using events is pretty much straightforward if you’re a node developer, or if you worked with any evented system before:
var casper = require('casper').create();
casper.on('resource.received', function(resource) {
casper.echo(resource.url);
});
Emitting you own events¶
Of course you can emit your own events, using the Casper.emit()
method:
var casper = require('casper').create();
// listening to a custom event
casper.on('google.loaded', function() {
this.echo('Google page title is ' + this.getTitle());
});
casper.start('http://google.com/', function() {
// emitting a custom event
this.emit('google.loaded');
});
casper.run();
Events reference¶
complete.error
¶
Arguments: error
New in version 1.1.
Emitted when a complete callback has errored.
By default, CasperJS doesn’t listen to this event, you have to declare your own listeners by hand:
casper.on('complete.error', function(err) {
this.die("Complete callback has failed: " + err);
});
downloaded.file
¶
Arguments: targetPath
Emitted when a file has been downloaded by Casper.download(); target
will contain the path to the downloaded file.
error
¶
Arguments: msg, backtrace
New in version 0.6.9.
Emitted when an error hasn’t been explicitly caught within the CasperJS/PhantomJS environment. Do basically what PhantomJS’ onError()
native handler does.
fill
¶
Arguments: selector, vals, submit
Emitted when a form is filled using the Casper.fill()
method.
forward
¶
Arguments: None
Emitted when the embedded browser is asked to go forward a step in its history.
http.status.[code]
¶
Arguments: resource
Emitted when any given HTTP reponse is received with the status code specified by [code]
, eg.:
casper.on('http.status.404', function(resource) {
casper.echo(resource.url + ' is 404');
})
load.started
¶
Arguments: None
Emitted when PhantomJS’ WebPage.onLoadStarted
event callback is called.
load.failed
¶
Arguments: Object
Emitted when PhantomJS’ WebPage.onLoadFinished
event callback has been called and failed.
load.finished
¶
Arguments: status
Emitted when PhantomJS’ WebPage.onLoadFinished
event callback is called.
log
¶
Arguments: entry
Emitted when the Casper.log()
method has been called. The entry
parameter is an Object like this:
{
level: "debug",
space: "phantom",
message: "A message",
date: "a javascript Date instance"
}
mouse.down
¶
Arguments: args
Emitted when the mouse presses on something or somewhere with the left button.
mouse.up
¶
Arguments: args
Emitted when the mouse releases the left button over something or somewhere.
open
¶
location, settings
Emitted when an HTTP request is sent. First callback arg is the location, second one is a request settings Object of the form:
{
method: "post",
data: "foo=42&chuck=norris"
}
page.created
¶
Arguments: page
Emitted when PhantomJS’ WebPage
object used by CasperJS has been created.
page.error
¶
Arguments: message, trace
Emitted when retrieved page leaves a Javascript error uncaught:
casper.on("page.error", function(msg, trace) {
this.echo("Error: " + msg, "ERROR");
});
page.initialized
¶
Arguments: WebPage
Emitted when PhantomJS’ WebPage
object used by CasperJS has been initialized.
page.resource.received
¶
Arguments: response
Emitted when the HTTP response corresponding to current required url has been received.
page.resource.requested
¶
Arguments: request
Emitted when a new HTTP request is performed to open the required url.
New in version 1.1.
Arguments: requestData, request
You can also abort requests:
casper.on('page.resource.requested', function(requestData, request) {
if (requestData.url.indexOf('http://adserver.com') === 0) {
request.abort();
}
});
remote.callback
¶
Arguments: data
Emitted when a remote window.callPhantom(data) call has been performed.
resource.error
¶
Arguments: resourceError
Emitted when any requested resource fails to load properly. The received resourceError
object has the following properties:
errorCode
: error codeerrorString
: error descriptionurl
: resource urlid
: resource id
run.complete
¶
Arguments: None
Emitted when the whole series of steps in the stack have been executed.
step.error
¶
Arguments: error
New in version 1.1.
Emitted when a step function has errored.
By default, CasperJS doesn’t listen to this event, you have to declare your own listeners by hand:
casper.on('step.error', function(err) {
this.die("Step has failed: " + err);
});
timeout
¶
Arguments: None
Emitted when the execution time of the script has reached the Casper.options.timeout
value.
waitFor.timeout
¶
Arguments: [timeout, details]
Emitted when the execution time of a Casper.wait*()
operation has exceeded the value of timeout
.
details
is a property bag describing what was being waited on. For example, if waitForSelector
timed out, details
will have a selector
string property that was the selector that did not show up in time.
Filters¶
Filters allow you to alter some values asynchronously. Sounds obscure? Let’s take a simple example and imagine you would like to alter every single url opened by CasperJS to append a foo=42
query string parameter:
var casper = require('casper').create();
casper.setFilter('open.location', function(location) {
return /\?+/.test(location) ? location += "&foo=42" : location += "?foo=42";
});
There you have it, every single requested url will have this appended. Let me bet you’ll find far more interesting use cases than my silly one ;)
Here’a the list of all available filters with their expected return value:
Filters reference¶
capture.target_filename
¶
Arguments: args
Return type: String
Allows to alter the value of the filename where a screen capture should be stored.
echo.message
¶
Arguments: message
Return type: String
Allows to alter every message written onto stdout.
open.location
¶
Arguments: args
Return type: String
Allows to alter every url before it being opened.
page.confirm
¶
Arguments: message
Return type: Boolean
New in version 1.0.
Allows to react on a javascript confirm()
call:
casper.setFilter("page.confirm", function(msg) {
return msg === "Do you like vbscript?" ? false : true;
});
page.prompt
¶
Arguments: message, value
Return type: String
New in version 1.0.
Allows to react on a javascript prompt()
call:
casper.setFilter("page.prompt", function(msg, value) {
if (msg === "What's your name?") {
return "Chuck";
}
});