The clientutils module¶
Casper ships with a few client-side utilities which are injected in the remote DOM environment, and accessible from there through the __utils__ object instance of the ClientUtils class from the clientutils module:
casper.evaluate(function() {
__utils__.echo("Hello World!");
});
Note
These tools are provided to avoid coupling CasperJS to any third-party library like jQuery, Mootools or something; but you can always include these and have them available client-side using the Casper.options.clientScripts option.
Bookmarklet¶
A bookmarklet is also available to help injecting Casper’s client-side utilities in the DOM of your favorite browser.
Just drag the following link onto your favorites toobar; when clicking it, a __utils__ object will be available within the console of your browser:
Note
CasperJS and PhantomJS being based on Webkit, you’re strongly encouraged to use a recent Webkit compatible browser to use this bookmarklet (Chrome, Safari, etc…)
ClientUtils prototype¶
echo()¶
Signature: echo(String message)
New in version 1.0.
Print a message out to the casper console from the remote page DOM environment:
casper.start('http://foo.ner/').thenEvaluate(function() {
__utils__.echo('plop'); // this will be printed to your shell at runtime
});
encode()¶
Signature: encode(String contents)
Encodes a string using the base64 algorithm. For the records, CasperJS doesn’t use builtin window.btoa() function because it can’t deal efficiently with strings encoded using >8b characters:
var base64;
casper.start('http://foo.bar/', function() {
base64 = this.evaluate(function() {
return __utils__.encode("I've been a bit cryptic recently");
});
});
casper.run(function() {
this.echo(base64).exit();
});
exists()¶
Signature: exists(String selector)
Checks if a DOM element matching a given selector expression exists:
var exists;
casper.start('http://foo.bar/', function() {
exists = this.evaluate(function() {
return __utils__.exists('#some_id');
});
});
casper.run(function() {
this.echo(exists).exit();
});
findAll()¶
Signature: findAll(String selector)
Retrieves all DOM elements matching a given selector expression:
var links;
casper.start('http://foo.bar/', function() {
links = this.evaluate(function() {
var elements = __utils__.findAll('a.menu');
return elements.map(function(e) {
return e.getAttribute('href');
});
});
});
casper.run(function() {
this.echo(JSON.stringify(links)).exit();
});
findOne()¶
Signature: findOne(String selector)
Retrieves a single DOM element by a selector expression:
var href;
casper.start('http://foo.bar/', function() {
href = this.evaluate(function() {
return __utils__.findOne('#my_id').getAttribute('href');
});
});
casper.run(function() {
this.echo(href).exit();
});
getBase64()¶
Signature: getBase64(String url[, String method, Object data])
This method will retrieved a base64 encoded version of any resource behind a url. For example, let’s imagine we want to retrieve the base64 representation of some website’s logo:
var logo = null;
casper.start('http://foo.bar/', function() {
logo = this.evaluate(function() {
var imgUrl = document.querySelector('img.logo').getAttribute('src');
return __utils__.getBase64(imgUrl);
});
});
casper.run(function() {
this.echo(logo).exit();
});
getBinary()¶
Signature: getBinary(String url[, String method, Object data])
This method will retrieved the raw contents of a given binary resource; unfortunately though, PhantomJS cannot process these data directly so you’ll have to process them within the remote DOM environment. If you intend to download the resource, use getBase64() or Casper.base64encode() instead:
casper.start('http://foo.bar/', function() {
this.evaluate(function() {
var imgUrl = document.querySelector('img.logo').getAttribute('src');
console.log(__utils__.getBinary(imgUrl));
});
});
casper.run();
getDocumentHeight()¶
Signature: getDocumentHeight()
New in version 1.0.
Retrieves current document height:
var documentHeight;
casper.start('http://google.com/', function() {
documentHeight = this.evaluate(function() {
return __utils__.getDocumentHeight();
});
this.echo('Document height is ' + documentHeight + 'px');
});
casper.run();
getElementBounds()¶
Signature: getElementBounds(String selector)
Retrieves boundaries for a DOM elements matching the provided selector.
It returns an Object with four keys: top, left, width and height, or null if the selector doesn’t exist.
getElementsBounds()¶
Signature: getElementsBounds(String selector)
Retrieves boundaries for all DOM element matching the provided selector.
It returns an array of objects each having four keys: top, left, width and height.
getElementByXPath()¶
Signature: getElementByXPath(String expression [, HTMLElement scope])
Retrieves a single DOM element matching a given XPath expression.
New in version 1.0.
The scope argument allow to set the context for executing the XPath query:
// will be performed against the whole document
__utils__.getElementByXPath('.//a');
// will be performed against a given DOM element
__utils__.getElementByXPath('.//a', __utils__.findOne('div.main'));
getElementsByXPath()¶
Signature: getElementsByXPath(String expression [, HTMLElement scope])
Retrieves all DOM elements matching a given XPath expression, if any.
New in version 1.0.
The scope argument allows to set the context for executing the XPath query.
getFieldValue()¶
Signature: getFieldValue(String inputName[, Object options])
New in version 1.0.
Retrieves the value from the field named against the inputNamed argument:
<form>
<input type="text" name="plop" value="42">
</form>
Using the getFieldValue() method for plop:
__utils__.getFieldValue('plop'); // 42
Options:
formSelector: allows to set the selector for the form containing the target field.
getFormValues()¶
Signature: getFormValues(String selector)
New in version 1.0.
Retrieves a given form and all of its field values:
<form id="login" action="/login">
<input type="text" name="username" value="foo">
<input type="text" name="password" value="bar">
<input type="submit">
</form>
To get the form values:
__utils__.getFormValues('form#login'); // {username: 'foo', password: 'bar'}
log()¶
Signature: log(String message[, String level])
Logs a message with an optional level. Will format the message a way CasperJS will be able to log phantomjs side. Default level is debug:
casper.start('http://foo.ner/').thenEvaluate(function() {
__utils__.log("We've got a problem on client side", 'error');
});
mouseEvent()¶
Signature: mouseEvent(String type, String selector)
Dispatches a mouse event to the DOM element behind the provided selector.
Supported events are mouseup, mousedown, click, mousemove, mouseover and mouseout.
removeElementsByXPath()¶
Signature: removeElementsByXPath(String expression)
Removes all DOM elements matching a given XPath expression.
sendAJAX()¶
Signature: sendAJAX(String url[, String method, Object data, Boolean async, Object settings])
New in version 1.0.
Sends an AJAX request, using the following parameters:
url: The url to request.method: The HTTP method (default:GET).data: Request parameters (default:null).async: Flag for an asynchroneous request? (default:false)settings: Other settings when perform the AJAX request (default:null)
Warning
Don’t forget to pass the --web-security=no option in your CLI call in order to perform cross-domains requests when needed:
var data, wsurl = 'http://api.site.com/search.json';
casper.start('http://my.site.com/', function() {
data = this.evaluate(function(wsurl) {
return JSON.parse(__utils__.sendAJAX(wsurl, 'GET', null, false));
}, {wsurl: wsurl});
});
casper.then(function() {
require('utils').dump(data);
});
visible()¶
Signature: visible(String selector)
Checks if an element is visible:
var logoIsVisible = casper.evaluate(function() {
return __utils__.visible('h1');
});
