.. _clientutils_module: .. index:: Client utils, __utils__, DOM ========================== 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 :index:`jQuery`, Mootools or something; but you can always include these and have them available client-side using the :ref:`Casper.options.clientScripts ` option. .. _bookmarklet: .. index:: bookmarklet, DOM, Debugging 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: .. raw:: html
CasperJS Utils
.. 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: ``ClientUtils`` prototype +++++++++++++++++++++++++ .. index:: echo ``echo()`` ------------------------------------------------------------------------------- **Signature:** ``echo(String message)`` .. versionadded:: 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 }); .. index:: Base64 ``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(); }); .. index:: DOM ``exists()`` ------------------------------------------------------------------------------- **Signature:** ``exists(String selector)`` Checks if a DOM element matching a given :ref:`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 :ref:`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 :ref:`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(); }); ``forceTarget()`` ------------------------------------------------------------------------------- **Signature:** ``forceTarget(String selector, String target)`` Force the engine to use another target instead of the one provided. Very useful to limit the number of open windows and reduce memory consumption:: casper.start('http://foo.bar/', function() { var href = this.evaluate(function() { return __utils__.forceTarget('#my_id', '_self').click(); }); this.echo(href); }); casper.run(function() { this.exit(); }); .. index:: Base64 ``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(); }); .. index:: Binary ``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 :ref:`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()`` .. versionadded:: 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(); ``getDocumentWidth()`` ------------------------------------------------------------------------------- **Signature:** ``getDocumentWidth()`` .. versionadded:: 1.0 Retrieves current document width:: var documentHeight; casper.start('http://google.com/', function() { documentWidth = this.evaluate(function() { return __utils__.getDocumentWidth(); }); this.echo('Document width is ' + documentWidth + 'px'); }); casper.run(); ``getElementBounds()`` ------------------------------------------------------------------------------- **Signature:** ``getElementBounds(String selector)`` Retrieves boundaries for a DOM elements matching the provided :ref:`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 :ref:`selector `. It returns an array of objects each having four keys: ``top``, ``left``, ``width`` and ``height``. .. index:: XPath ``getElementByXPath()`` ------------------------------------------------------------------------------- **Signature:** ``getElementByXPath(String expression [, HTMLElement scope])`` Retrieves a single DOM element matching a given :ref:`XPath expression `. .. versionadded:: 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')); .. index:: XPath ``getElementsByXPath()`` ------------------------------------------------------------------------------- **Signature:** ``getElementsByXPath(String expression [, HTMLElement scope])`` Retrieves all DOM elements matching a given :ref:`XPath expression `, if any. .. versionadded:: 1.0 The ``scope`` argument allows to set the context for executing the XPath query. .. _clientutils_getfieldvalue: .. index:: Form ``getFieldValue()`` ------------------------------------------------------------------------------- **Signature:** ``getFieldValue(String selector[, HTMLElement scope])`` .. versionadded:: 1.0 Retrieves the value from the field named against the ``inputNamed`` argument: .. code-block:: html
Using the ``getFieldValue()`` method for ``plop``:: __utils__.getFieldValue('[name="plop"]'); // 42 Options: .. index:: Form ``getFormValues()`` ------------------------------------------------------------------------------- **Signature:** ``getFormValues(String selector)`` .. versionadded:: 1.0 Retrieves a given form and all of its field values: .. code-block:: html
To get the form values:: __utils__.getFormValues('form#login'); // {username: 'foo', password: 'bar'} .. index:: log ``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'); }); ``makeSelector()`` ----------------------------------------------------------------------------- **Signature:** ``makeSelector(String selector [, String type])`` .. versionadded:: 1.1-beta5 Makes selector by defined type XPath, Name or Label. Function has same result as selectXPath in Casper module for XPath type - it makes XPath object. Function also accepts name attribute of the form field or can select element by its label text. Parameter ``type`` values: ~~~~~~~~~~~~~~~~~~~~~~~~ - 'css' CSS3 selector - selector is returned transparently - 'xpath' || null XPath selector - return XPath object - 'name' || 'names' select input of specific name, internally covert to CSS3 selector - 'label' || 'labels' select input of specific label, internally converted into XPath selector. As selector is label's text used Examples:: __utils__.makeSelector('//li[text()="blah"]', 'xpath'); // return {type: 'xpath', path: '//li[text()="blah"]'} __utils__.makeSelector('parameter', 'name'); // return '[name="parameter"]' __utils__.makeSelector('My label', 'label'); // return {type: 'xpath', path: '//*[@id=string(//label[text()="My label"]/@for)]'} ``mouseEvent()`` ------------------------------------------------------------------------------- **Signature:** ``mouseEvent(String type, String selector, [Number|String X, Number|String Y])`` Dispatches a mouse event to the DOM element behind the provided selector. Supported events are ``mouseup``, ``mousedown``, ``click``, ``dblclick``, ``mousemove``, ``mouseover``, ``mouseout``, ``mouseenter``, ``mouseleave`` and ``contextmenu``:: .. index:: XPath ``removeElementsByXPath()`` ------------------------------------------------------------------------------- **Signature:** ``removeElementsByXPath(String expression)`` Removes all DOM elements matching a given :ref:`XPath expression `. .. index:: AJAX ``sendAJAX()`` ----------------------------------------------------------------------------- **Signature:** ``sendAJAX(String url[, String method, Object data, Boolean async, Object settings])`` .. versionadded:: 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``: Custom Headers when perform the AJAX request (default: ``null``). WARNING: an invalid header here may make the request fail silently. .. 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); }); ``setFieldValue()`` ----------------------------------------------------------------------------- **Signature:** ``setFieldValue(String|Object selector, Mixed value [, HTMLElement scope])`` .. versionadded:: 1.1-beta5 Sets a value to form field by CSS3 or XPath selector. With `makeSelector()`_ function can be easily used with ``name`` or ``label`` selector Options ~~~~~~~ - ``(String|Object) scope: selector :`` specific form scope Examples:: __utils__.setFieldValue("input[name='email']", 'chuck@norris.com'); __utils__.setFieldValue("input[name='email']", 'chuck@norris.com', {'formSelector': '#myform'}); __utils__.setFieldValue(__utils__.makeSelector('email', 'name'), 'chuck@norris.com'); ``visible()`` ------------------------------------------------------------------------------- **Signature:** ``visible(String selector)`` Checks if an element is visible:: var logoIsVisible = casper.evaluate(function() { return __utils__.visible('h1'); });