casperjs/modules/casper.js

A navigation scripting & testing utility for PhantomJS and SlimerJS

/*!
 * Casper is a navigation utility for PhantomJS.
 *
 * Documentation: http://casperjs.org/
 * Repository:    http://github.com/casperjs/casperjs
 *
 * Copyright (c) 2011-2012 Nicolas Perriault
 *
 * Part of source code is Copyright Joyent, Inc. and other Node contributors.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 *
 */

/*global __utils__, CasperError, console, exports, phantom, patchRequire, require:true*/
require = patchRequire(require);
var colorizer = require('colorizer');
var events = require('events');
var fs = require('fs');
var http = require('http');
var mouse = require('mouse');
var pagestack = require('pagestack');
var qs = require('querystring');
var tester = require('tester');
var utils = require('utils');
var f = utils.format;


var defaultUserAgent = phantom.defaultPageSettings.userAgent
    .replace(/(PhantomJS|SlimerJS)/, f("CasperJS/%s", phantom.casperVersion) + '+$&');

exports.create = function create(options) {
    "use strict";
    // This is a bit of a hack to check if one is trying to override the preconfigured
    // casper instance from within a test environment.
    if (phantom.casperTest && window.casper) {
        console.error("Fatal: you can't override the preconfigured casper instance in a test environment.");
        console.error("Docs: http://docs.casperjs.org/en/latest/testing.html#test-command-args-and-options");
        phantom.exit(1);
    }
    return new Casper(options);
};

/**
 * Shortcut to build an XPath selector object.
 *
 * @param  String  expression  The XPath expression
 * @return Object
 * @see    http://casperjs.org/selectors.html
 */
function selectXPath(expression) {
    "use strict";
    return {
        type: 'xpath',
        path: expression,
        toString: function() {
            return this.type + ' selector: ' + this.path;
        }
    };
}
exports.selectXPath = selectXPath;

/**
 * Main Casper object.
 *
 * @param  Object  options  Casper options
 */
var Casper = function Casper(options) {
    "use strict";
    /*eslint max-statements:0*/
    // init & checks
    if (!(this instanceof Casper)) {
        return new Casper(options);
    }
    // default options
    this.defaults = {
        clientScripts:       [],
        colorizerType:       'Colorizer',
        exitOnError:         true,
        logLevel:            "error",
        httpStatusHandlers:  {},
        safeLogs:            true,
        onAlert:             null,
        onDie:               null,
        onError:             null,
        onLoadError:         null,
        onPageInitialized:   null,
        onResourceReceived:  null,
        onResourceRequested: null,
        onRunComplete:       function _onRunComplete() {
            this.exit();
        },
        onStepComplete:      null,
        onStepTimeout:       function _onStepTimeout(timeout, stepNum) {
            this.die("Maximum step execution timeout exceeded for step " + stepNum);
        },
        onTimeout:           function _onTimeout(timeout) {
            this.die(f("Script timeout of %dms reached, exiting.", timeout));
        },
        onWaitTimeout:       function _onWaitTimeout(timeout) {
            this.die(f("Wait timeout of %dms expired, exiting.", timeout));
        },
        page:                null,
        pageSettings:        {
            localToRemoteUrlAccessEnabled: true,
            javascriptEnabled:             true,
            userAgent:                     defaultUserAgent
        },
        remoteScripts:       [],
        silentErrors:        false,
        stepTimeout:         null,
        timeout:             null,
        verbose:             false,
        retryTimeout:        20,
        waitTimeout:         5000,
        clipRect : null,
        viewportSize : null
    };
    // options
    this.options = utils.mergeObjects(this.defaults, options);
    // factories
    this.cli = phantom.casperArgs;
    this.options.logLevel = this.cli.get('log-level', this.options.logLevel);
    if (!this.options.verbose) {
        this.options.verbose = this.cli.has('direct') || this.cli.has('verbose');
    }
    this.colorizer = this.getColorizer();
    this.mouse = mouse.create(this);
    this.popups = pagestack.create();
    // properties
    this.checker = null;
    this.currentResponse = {};
    this.currentUrl = 'about:blank';
    this.currentHTTPStatus = null;
    this.history = [];
    this.navigationRequested = false;
    this.logFormats = {};
    this.logLevels = ["debug", "info", "warning", "error"];
    this.logStyles = {
        debug:   'INFO',
        info:    'PARAMETER',
        warning: 'COMMENT',
        error:   'ERROR'
    };
    this.page = null;
    this.pendingWait = false;
    this.requestUrl = 'about:blank';
    this.resources = [];
    this.result = {
        log:    [],
        status: "success",
        time:   0
    };
    this.started = false;
    this.step = -1;
    this.steps = [];
    this.waiters = [];
    this._test = undefined;
    this.__defineGetter__('test', function() {
        if (!phantom.casperTest) {
            throw new CasperError('casper.test property is only available using the `casperjs test` command');
        }
        if (!utils.isObject(this._test)) {
            this._test = tester.create(this, {
                concise: this.cli.get('concise')
            });
        }
        return this._test;
    });

    // init phantomjs error handler
    this.initErrorHandler();

    this.on('error', function(msg, backtrace) {
        var c = this.getColorizer();
        var match = /^(.*): __mod_error(.*):: (.*)/.exec(msg);
        var notices = [];
        if (match && match.length === 4) {
            notices.push('  in module ' + match[2]);
            msg = match[3];
        }

        console.log(c.colorize(msg, 'RED_BAR', 80));
        notices.forEach(function(notice) {
            console.log(c.colorize(notice, 'COMMENT'));
        });
        (backtrace || []).forEach(function(item) {
            var message = fs.absolute(item.file) + ":" + c.colorize(item.line, "COMMENT");
            if (item['function']) {
                message += " in " + c.colorize(item['function'], "PARAMETER");
            }
            console.log("  " + message);
        });
    });

    // deprecated feature event handler
    this.on('deprecated', function onDeprecated(message) {
        this.warn('[deprecated] ' + message);
    });

    // dispatching an event when instance has been constructed
    this.emit('init');

    // deprecated direct option
    if (this.cli.has('direct')) {
        this.emit("deprecated", "--direct option has been deprecated since 1.1; you should use --verbose instead.");
    }
};

// Casper class is an EventEmitter
utils.inherits(Casper, events.EventEmitter);

/**
 * Go a step back in browser's history
 *
 * @return Casper
 */
Casper.prototype.back = function back() {
    "use strict";
    this.checkStarted();
    return this.then(function() {
        this.emit('back');
        this.page.goBack();
    });
};

/**
 * Encodes a resource using the base64 algorithm synchronously using
 * client-side XMLHttpRequest.
 *
 * NOTE: we cannot use window.btoa() for some strange reasons here.
 *
 * @param  String  url     The url to download
 * @param  String  method  The method to use, optional: default GET
 * @param  String  data    The data to send, optional
 * @return string          Base64 encoded result
 */
Casper.prototype.base64encode = function base64encode(url, method, data) {
    "use strict";
    return this.callUtils("getBase64", url, method, data);
};

/**
 * Bypasses `nb` steps.
 *
 * @param  Integer  nb  Number of steps to bypass
 */
Casper.prototype.bypass = function bypass(nb) {
    "use strict";
    var step = this.step,
        steps = this.steps,
        last = steps.length,
        targetStep = Math.min(step + nb, last);
    this.checkStarted();
    this.step = targetStep;
    this.emit('step.bypassed', targetStep, step);
    return this;
};

/**
 * Invokes a client side utils object method within the remote page, with arguments.
 *
 * @param  {String}   method  Method name
 * @return {...args}          Arguments
 * @return {Mixed}
 * @throws {CasperError}      If invokation failed.
 */
Casper.prototype.callUtils = function callUtils(method) {
    "use strict";
    var args = [].slice.call(arguments, 1);
    var result = this.evaluate(function(method, args) {
        return __utils__.__call(method, args);
    }, method, args);
    if (utils.isObject(result) && result.__isCallError) {
        throw new CasperError(f("callUtils(%s) with args %s thrown an error: %s",
                              method, args, result.message));
    }
    return result;
};

/**
 * Proxy method for WebPage#render. Adds a clipRect parameter for
 * automatically set page clipRect setting values and sets it back once
 * done. If the cliprect parameter is omitted, the full page viewport
 * area will be rendered.
 *
 * @param  String  targetFile  A target filename
 * @param  mixed   clipRect    An optional clipRect object (optional)
 * @return Casper
 */
Casper.prototype.capture = function capture(targetFile, clipRect, imgOptions) {
    "use strict";
    /*eslint max-statements:0*/
    this.checkStarted();
    var previousClipRect;
    targetFile = fs.absolute(targetFile);
    if (clipRect) {
        if (!utils.isClipRect(clipRect)) {
            throw new CasperError("clipRect must be a valid ClipRect object.");
        }
        previousClipRect = this.page.clipRect;
        this.page.clipRect = clipRect;
        this.log(f("Capturing page to %s with clipRect %s", targetFile, JSON.stringify(clipRect)), "debug");
    } else {
        this.log(f("Capturing page to %s", targetFile), "debug");
    }
    if (!this.page.render(this.filter('capture.target_filename', targetFile) || targetFile, imgOptions)) {
        this.log(f("Failed to save screenshot to %s; please check permissions", targetFile), "error");
    } else {
        this.log(f("Capture saved to %s", targetFile), "info");
        this.emit('capture.saved', targetFile);
    }
    if (previousClipRect) {
        this.page.clipRect = previousClipRect;
    }
    return this;
};

/**
 * Returns a Base64 representation of a binary image capture of the current
 * page, or an area within the page, in a given format.
 *
 * Supported image formats are `bmp`, `jpg`, `jpeg`, `png`, `ppm`, `tiff`,
 * `xbm` and `xpm`.
 *
 * @param  String                   format    The image format
 * @param  String|Object|undefined  selector  DOM CSS3/XPath selector or clipRect object (optional)
 * @return Casper
 */
Casper.prototype.captureBase64 = function captureBase64(format, area) {
    "use strict";
    /*eslint max-statements:0*/
    this.checkStarted();
    var base64, previousClipRect, formats = ['bmp', 'jpg', 'jpeg', 'png', 'ppm', 'tiff', 'xbm', 'xpm'];
    if (formats.indexOf(format.toLowerCase()) === -1) {
        throw new CasperError(f('Unsupported format "%s"', format));
    }
    if (utils.isClipRect(area)) {
        // if area is a clipRect object
        this.log(f("Capturing base64 %s representation of %s", format, utils.serialize(area)), "debug");
        previousClipRect = this.page.clipRect;
        this.page.clipRect = area;
        base64 = this.page.renderBase64(format);
    } else if (utils.isValidSelector(area)) {
        // if area is a selector string or object
        this.log(f("Capturing base64 %s representation of %s", format, area), "debug");
        var scrollPos = this.evaluate(function() {
            return { x: scrollX, y: scrollY };
        });
        var elementBounds = this.getElementBounds(area);
        elementBounds.top += scrollPos.y;
        elementBounds.left += scrollPos.x;
        base64 = this.captureBase64(format, elementBounds);
    } else {
        // whole page capture
        this.log(f("Capturing base64 %s representation of page", format), "debug");
        base64 = this.page.renderBase64(format);
    }
    if (previousClipRect) {
        this.page.clipRect = previousClipRect;
    }
    return base64;
};

/**
 * Captures the page area matching the provided selector.
 *
 * @param  String  targetFile  Target destination file path.
 * @param  String  selector    DOM CSS3/XPath selector
 * @return Casper
 */
Casper.prototype.captureSelector = function captureSelector(targetFile, selector, imgOptions) {
    "use strict";
    var scrollPos = this.evaluate(function() {
        return { x: scrollX, y: scrollY };
    });
    var elementBounds = this.getElementBounds(selector);
    elementBounds.top += scrollPos.y;
    elementBounds.left += scrollPos.x;
    return this.capture(targetFile, elementBounds, imgOptions);
};

/**
 * Checks for any further navigation step to process.
 *
 * @param  Casper    self        A self reference
 * @param  function  onComplete  An options callback to apply on completion
 */
Casper.prototype.checkStep = function checkStep(self, onComplete) {
    "use strict";

    if (self.page !== null && (self.pendingWait || self.page.loadInProgress || self.navigationRequested || self.page.browserInitializing )) {
        return;
    }
    var step = self.steps[self.step++];
    if (utils.isFunction(step)) {
        return self.runStep(step);
    }
    self.result.time = new Date().getTime() - self.startTime;
    self.log(f("Done %s steps in %dms", self.steps.length, self.result.time), "info");
    clearInterval(self.checker);
    self.step -= 1;
    self.emit('run.complete');
    try {
        if (utils.isFunction(onComplete)) {
            onComplete.call(self, self);
        } else if (utils.isFunction(self.options.onRunComplete)) {
            self.options.onRunComplete.call(self, self);
        }
    } catch (error) {
        self.emit('complete.error', error);
        if (!self.options.silentErrors) {
            throw error;
        }
    }
};

/**
 * Checks if this instance is started.
 *
 * @return Boolean
 * @throws CasperError
 */
Casper.prototype.checkStarted = function checkStarted() {
    "use strict";
    if (!this.started) {
        throw new CasperError(f("Casper is not started, can't execute `%s()`",
                                checkStarted.caller.name));
    }
    if (this.page === null) {
        this.newPage();
    }
};

/**
 * Clears the current page execution environment context. Useful to avoid
 * having previously loaded DOM contents being still active (refs #34).
 *
 * Think of it as a way to stop javascript execution within the remote DOM
 * environment.
 *
 * @return Casper
 */
Casper.prototype.clear = function clear() {
    "use strict";
    this.checkStarted();
    this.page.content = '';
    return this;
};

/**
 * Replace currente page by a new page object, with newPage()
 * Clears the memory cache, with clearMemoryCache()
 * 
 * @return Casper
 */
Casper.prototype.clearCache = function clearCache() {
    "use strict";
    this.checkStarted();
    this.page = this.newPage();
    this.clearMemoryCache();
    return this;
};

/**
 * Clears the memory cache, using engine method
 * reference: https://github.com/ariya/phantomjs/issues/10357
 *
 * @return Casper
 */
Casper.prototype.clearMemoryCache = function clearMemoryCache() {
    "use strict";
    this.checkStarted();
    if (typeof this.page.clearMemoryCache === 'function') {
        this.page.clearMemoryCache();
    } else if ( phantom.casperEngine === 'slimerjs' || utils.matchEngine({name: 'phantomjs', version: {min: '2.0.0'}}) ) {
        this.log('clearMemoryCache() did nothing: page.clearMemoryCache is not avliable in this engine', "warning");
    } else {
        throw new CasperError("clearMemoryCache(): page.clearMemoryCache should be avaliable in this engine");
    };
    return this;
};

/**
 * Emulates a click on the element from the provided selector using the mouse
 * pointer, if possible.
 *
 * In case of success, `true` is returned, `false` otherwise.
 *
 * @param  String   selector  A DOM CSS3 compatible selector
 * @param  String   target    A HTML target '_blank','_self','_parent','_top','framename' (optional)
 * @param  Number   x         X position (optional)
 * @param  Number   y         Y position (optional)
 * @return Boolean
 */
Casper.prototype.click = function click(selector, x, y) {
    "use strict";
    this.checkStarted();
    var success = this.mouseEvent('mousedown', selector, x, y) && this.mouseEvent('mouseup', selector, x, y);
    success = success && this.mouseEvent('click', selector, x, y);
    this.evaluate(function(selector) {
        var element = __utils__.findOne(selector);
        if (element) {
            element.focus();
        }
    }, selector);
    this.emit('click', selector);
    return success;
};

/**
 * Emulates a click on the element having `label` as innerText. The first
 * element matching this label will be selected, so use with caution.
 *
 * @param  String   label  Element innerText value
 * @param  String   tag    An element tag name (eg. `a` or `button`) (optional)
 * @return Boolean
 */
Casper.prototype.clickLabel = function clickLabel(label, tag) {
    "use strict";
    this.checkStarted();
    tag = tag || "*";
    var escapedLabel = utils.quoteXPathAttributeString(label);
    var selector = selectXPath(f('//%s[text()=%s]', tag, escapedLabel));
    return this.click(selector);
};

/**
 * Configures HTTP authentication parameters. Will try parsing auth credentials from
 * the passed location first, then check for configured settings if any.
 *
 * @param  String  location  Requested url
 * @param  Object  settings  Request settings
 * @return Casper
 */
Casper.prototype.configureHttpAuth = function configureHttpAuth(location, settings) {
    "use strict";
    var httpAuthMatch = location.match(/^https?:\/\/(.+):(.+)@/i);
    this.checkStarted();
    if (httpAuthMatch) {
        this.page.settings.userName = httpAuthMatch[1];
        this.page.settings.password = httpAuthMatch[2];
    } else if (utils.isObject(settings) && settings.username) {
        this.page.settings.userName = settings.username;
        this.page.settings.password = settings.password;
    } else {
        return;
    }
    this.emit('http.auth', this.page.settings.userName, this.page.settings.password);
    this.log("Setting HTTP authentication for user " + this.page.settings.userName, "info");
    return this;
};

/**
 * Creates a step definition.
 *
 * @param  Function  fn       The step function to call
 * @param  Object    options  Step options
 * @return Function  The final step function
 */
Casper.prototype.createStep = function createStep(fn, options) {
    "use strict";
    if (!utils.isFunction(fn)) {
        throw new CasperError("createStep(): a step definition must be a function");
    }
    fn.options = utils.isObject(options) ? options : {};
    this.emit('step.created', fn);
    return fn;
};

/**
 * Logs the HTML code of the current page.
 *
 * @param  String   selector  A DOM CSS3/XPath selector (optional)
 * @param  Boolean  outer     Whether to fetch outer HTML contents (default: false)
 * @return Casper
 */
Casper.prototype.debugHTML = function debugHTML(selector, outer) {
    "use strict";
    this.checkStarted();
    return this.echo(this.getHTML(selector, outer));
};

/**
 * Logs the textual contents of the current page.
 *
 * @return Casper
 */
Casper.prototype.debugPage = function debugPage() {
    "use strict";
    this.checkStarted();
    this.echo(this.evaluate(function _evaluate() {
        return document.body.textContent || document.body.innerText;
    }));
    return this;
};

/**
 * Exit phantom on failure, with a logged error message.
 *
 * @param  String  message  An optional error message
 * @param  Number  status   An optional exit status code (must be > 0)
 * @return Casper
 */
Casper.prototype.die = function die(message, status) {
    "use strict";
    this.result.status = "error";
    this.result.time = new Date().getTime() - this.startTime;
    if (!utils.isString(message) || !message.length) {
        message = "Suite explicitly interrupted without any message given.";
    }
    this.log(message, "error");
    this.echo(message, "ERROR");
    this.emit('die', message, status);
    if (utils.isFunction(this.options.onDie)) {
        this.options.onDie.call(this, this, message, status);
    }
    return this.exit(~~status > 0 ? ~~status : 1);
};

/**
 * Downloads a resource and saves it on the filesystem.
 *
 * @param  String  url         The url of the resource to download
 * @param  String  targetPath  The destination file path
 * @param  String  method      The HTTP method to use (default: GET)
 * @param  String  data        Optional data to pass performing the request
 * @return Casper
 */
Casper.prototype.download = function download(url, targetPath, method, data) {
    "use strict";
    this.checkStarted();
    var cu = require('clientutils').create(utils.mergeObjects({}, this.options));
    try {
        fs.write(targetPath, cu.decode(this.base64encode(url, method, data)), 'wb');
        this.emit('downloaded.file', targetPath);
        this.log(f("Downloaded and saved resource in %s", targetPath));
    } catch (e) {
        this.emit('downloaded.error', url);
        this.log(f("Error while downloading %s to %s: %s", url, targetPath, e), "error");
    }
    return this;
};

/**
 * Iterates over the values of a provided array and execute a callback for each
 * item.
 *
 * @param  Array     array
 * @param  Function  fn     Callback: function(casper, item, index)
 * @return Casper
 */
Casper.prototype.each = function each(array, fn) {
    "use strict";
    if (!utils.isArray(array)) {
        this.log("each() only works with arrays", "error");
        return this;
    }
    array.forEach(function _forEach(item, i) {
        fn.call(this, this, item, i);
    }, this);
    return this;
};

/**
 * Iterates over the values of a provided array and adds a step for each item.
 *
 * @param  Array     array
 * @param  Function  then   Step: function(response); item will be attached to response.data
 * @return Casper
 */
Casper.prototype.eachThen = function each(array, then) {
    "use strict";
    if (!utils.isArray(array)) {
        this.log("eachThen() only works with arrays", "error");
        return this;
    }
    array.forEach(function _forEach(item) {
        this.then(function() {
            this.then(this.createStep(then, {data: item}));
        });
    }, this);
    return this;
};

/**
 * Prints something to stdout.
 *
 * @param  String  text   A string to echo to stdout
 * @param  String  style  An optional style name
 * @param  Number  pad    An optional pad value
 * @return Casper
 */
Casper.prototype.echo = function echo(text, style, pad) {
    "use strict";
    if (!utils.isString(text)) {
        try {
            text = text.toString();
        } catch (e) {
            try {
                text = utils.serialize(text);
            } catch (e2) {
                text = '';
            }
        }
    }
    var message = style ? this.colorizer.colorize(text, style, pad) : text;
    console.log(this.filter('echo.message', message) || message);
    return this;
};

/**
 * Evaluates an expression in the page context, a bit like what
 * WebPage#evaluate does, but the passed function can also accept
 * parameters if a context Object is also passed:
 *
 *     casper.evaluate(function(username, password) {
 *         document.querySelector('#username').value = username;
 *         document.querySelector('#password').value = password;
 *         document.querySelector('#submit').click();
 *     }, 'Bazoonga', 'baz00nga');
 *
 * @param  Function  fn       The function to be evaluated within current page DOM
 * @param  Object    context  Object containing the parameters to inject into the function
 * @return mixed
 * @see    WebPage#evaluate
 */
Casper.prototype.evaluate = function evaluate(fn, context) {
    "use strict";
    this.checkStarted();
    // check whether javascript is enabled !!
    if (this.options.pageSettings.javascriptEnabled === false) {
        throw new CasperError("evaluate() requires javascript to be enabled");
    }
    // preliminary checks
    if (!utils.isFunction(fn) && !utils.isString(fn)) { // phantomjs allows functions defs as string
        throw new CasperError("evaluate() only accepts functions or strings");
    }

    // ensure client utils are always injected
    this.injectClientUtils();
    // function context
    if (arguments.length === 1) {
        return utils.clone(this.page.evaluate(fn));
    } else if (arguments.length === 2) {
        // check for closure signature if it matches context
        if (utils.isObject(context) && fn.length === Object.keys(context).length) {
            /*
             * in case if user passes argument as one array with only one object.
             * evaluate shlould return original array with one object
             * instead of converte this array to object
             */
            if (utils.isArray(context) && context.length === 1) {
                context = [context];
            } else {
                context = utils.objectValues(context);
            }
        } else {
            context = [context];
        }
    } else {
        // phantomjs-style signature
        context = [].slice.call(arguments, 1);
    }
    return utils.clone(this.page.evaluate.apply(this.page, [fn].concat(context)));
};

/**
 * Evaluates an expression within the current page DOM and die() if it
 * returns false.
 *
 * @param  function  fn       The expression to evaluate
 * @param  String    message  The error message to log
 * @param  Number  status   An optional exit status code (must be > 0)
 *
 * @return Casper
 */
Casper.prototype.evaluateOrDie = function evaluateOrDie(fn, message, status) {
    "use strict";
    this.checkStarted();
    if (!this.evaluate(fn)) {
        return this.die(message, status);
    }
    return this;
};

/**
 * Checks if an element matching the provided DOM CSS3/XPath selector exists in
 * current page DOM.
 *
 * @param  String  selector  A DOM CSS3/XPath selector
 * @return Boolean
 */
Casper.prototype.exists = function exists(selector) {
    "use strict";
    this.checkStarted();
    return this.callUtils("exists", selector);
};

/**
 * Exits phantom.
 *
 * @param  Number  status  Status
 * @return Casper
 */
Casper.prototype.exit = function exit(status) {
    "use strict";
    this.emit('exit', status);
    this.die = function(){};
    setTimeout(function() { phantom.exit(status); }, 0);
};

/**
 * Fetches plain text contents contained in the DOM element(s) matching a given CSS3/XPath
 * selector.
 *
 * @param  String  selector  A DOM CSS3/XPath selector
 * @return String
 */
Casper.prototype.fetchText = function fetchText(selector) {
    "use strict";
    this.checkStarted();
    return this.callUtils("fetchText", selector);
};

/**
 * Fills a form with provided field values.
 *
 * @param  String selector  A DOM CSS3/XPath selector to the target form to fill
 * @param  Object vals      Field values
 * @param  Object options   The fill settings (optional)
 */
Casper.prototype.fillForm = function fillForm(selector, vals, options) {
    "use strict";
    this.checkStarted();
    var self = this;
    var selectorType = options && options.selectorType || "names",
        submit = !!(options && options.submit);

    this.emit('fill', selector, vals, options);

    var fillResults = this.evaluate(function _evaluate(selector, vals, selectorType) {
        try {
            return __utils__.fill(selector, vals, selectorType);
        } catch (exception) {
            return {exception: exception.toString()};
        }
    }, selector, vals, selectorType);

    if (!fillResults) {
        throw new CasperError("Unable to fill form");
    } else if (fillResults && fillResults.exception) {
        throw new CasperError("Unable to fill form: " + fillResults.exception);
    } else if (fillResults.errors.length > 0) {
        throw new CasperError(f('Errors encountered while filling form: %s',
                              fillResults.errors.join('; ')));
    }

    // File uploads
    if (fillResults.files && fillResults.files.length > 0) {
        fillResults.files.forEach(function _forEach(file) {
            if (!file || !file.path) {
                return;
            }
            var paths = (utils.isArray(file.path) && file.path.length > 0) ? file.path : [file.path];
            paths.map(function(filePath) {
                if (!fs.exists(filePath)) {
                    throw new CasperError('Cannot upload nonexistent file: ' + filePath);
                }
            },this);
            var fileFieldSelector;
            if (file.type === "names") {
                fileFieldSelector = [selector, 'input[name="' + file.selector + '"]'].join(' ');
            } else if (file.type === "css" || file.type === "labels") {
                fileFieldSelector = [selector, file.selector].join(' ');
            } else if (file.type === "xpath") {
                fileFieldSelector = [selector, self.evaluate(function _evaluate(selector, scope, limit) {
                    return __utils__.getCssSelector(selector, scope, limit);
                }, selectXPath(file.selector), selector, 'FORM')].join(' ');
            }
            this.page.uploadFile(fileFieldSelector, paths);
        }.bind(this));
    }

    // Form submission?
    if (submit) {
        this.evaluate(function _evaluate(selector) {
            var form = __utils__.findOne(selector);
            var method = (form.getAttribute('method') || "GET").toUpperCase();
            var action = form.getAttribute('action') || "unknown";
            __utils__.log('submitting form to ' + action + ', HTTP ' + method, 'info');
            var event = document.createEvent('Event');
            event.initEvent('submit', true, true);
            if (!form.dispatchEvent(event)) {
                __utils__.log('unable to submit form', 'warning');
                return;
            }
            if (typeof form.submit === "function") {
                form.submit();
            } else {
                // http://www.spiration.co.uk/post/1232/Submit-is-not-a-function
                form.submit.click();
            }
        }, selector);
    }
    
    return this;
};

/**
 * Fills a form with provided field values using the Name attribute.
 *
 * @param  String  formSelector  A DOM CSS3/XPath selector to the target form to fill
 * @param  Object  vals          Field values
 * @param  Boolean submit        Submit the form?
 */
Casper.prototype.fillNames = function fillNames(formSelector, vals, submit) {
    "use strict";
    return this.fillForm(formSelector, vals, {
        submit: submit,
        selectorType: 'names'
    });
};

/**
 * Fills a form with provided field values using associated label text.
 *
 * @param  String  formSelector  A DOM CSS3/XPath selector to the target form to fill
 * @param  Object  vals          Field values
 * @param  Boolean submit        Submit the form?
 */
Casper.prototype.fillLabels = function fillLabels(formSelector, vals, submit) {
    "use strict";
    return this.fillForm(formSelector, vals, {
        submit: submit,
        selectorType: 'labels'
    });
};

/**
 * Fills a form with provided field values using CSS3 selectors.
 *
 * @param  String  formSelector  A DOM CSS3/XPath selector to the target form to fill
 * @param  Object  vals          Field values
 * @param  Boolean submit        Submit the form?
 */
Casper.prototype.fillSelectors = function fillSelectors(formSelector, vals, submit) {
    "use strict";
    return this.fillForm(formSelector, vals, {
        submit: submit,
        selectorType: 'css'
    });
};

/**
 * Fills a form with provided field values using the Name attribute by default.
 *
 * @param  String  formSelector  A DOM CSS3/XPath selector to the target form to fill
 * @param  Object  vals          Field values
 * @param  Boolean submit        Submit the form?
 */
Casper.prototype.fill = Casper.prototype.fillNames;

/**
 * Fills a form with provided field values using XPath selectors.
 *
 * @param  String  formSelector  A DOM CSS3/XPath selector to the target form to fill
 * @param  Object  vals          Field values
 * @param  Boolean submit        Submit the form?
 */
Casper.prototype.fillXPath = function fillXPath(formSelector, vals, submit) {
    "use strict";
    return this.fillForm(formSelector, vals, {
        submit: submit,
        selectorType: 'xpath'
    });
};

/**
 * Go a step forward in browser's history
 *
 * @return Casper
 */
Casper.prototype.forward = function forward() {
    "use strict";
    this.checkStarted();
    return this.then(function() {
        this.emit('forward');
        this.page.goForward();
    });
};

/**
 * Creates a new Colorizer instance. Sets `Casper.options.type` to change the
 * colorizer type name (see the `colorizer` module).
 *
 * @return Object
 */
Casper.prototype.getColorizer = function getColorizer() {
    "use strict";
    return colorizer.create(this.options.colorizerType || 'Colorizer');
};

/**
 * Retrieves current page contents, dealing with exotic other content types than HTML.
 *
 * @return String
 */
Casper.prototype.getPageContent = function getPageContent() {
    "use strict";
    this.checkStarted();
    var contentType = utils.getPropertyPath(this, 'currentResponse.contentType');
    if (!utils.isString(contentType) || contentType.indexOf("text/html") !== -1) {
        return this.page.frameContent;
    }
    // FIXME: with slimerjs this will work only for
    // text/* and application/json content types.
    // see FIXME in slimerjs src/modules/webpageUtils.jsm getWindowContent
    return this.page.framePlainText;
};

/**
 * Retrieves current page contents in plain text.
 *
 * @return String
 */
Casper.prototype.getPlainText = function getPlainText() {
    "use strict";
    this.checkStarted();
    return this.page.framePlainText;
};

/**
 * Retrieves current document url.
 *
 * @return String
 */
Casper.prototype.getCurrentUrl = function getCurrentUrl() {
    "use strict";
    this.checkStarted();
    try {
        if (this.options.pageSettings.javascriptEnabled === false) {
            return this.page.url;
        } else {
            return utils.decodeUrl(this.evaluate(function _evaluate() {
                return document.location.href;
            }));
        }
    } catch (e) {
        // most likely the current page object has been "deleted" (think closed popup)
        if (/deleted QObject/.test(e.message))
            return "";
        throw e;
    }
};

/**
 * Retrieves the value of an attribute on the first element matching the provided
 * DOM CSS3/XPath selector.
 *
 * @param  String  selector   A DOM CSS3/XPath selector
 * @param  String  attribute  The attribute name to lookup
 * @return String  The requested DOM element attribute value
 */
Casper.prototype.getElementAttribute =
Casper.prototype.getElementAttr = function getElementAttr(selector, attribute) {
    "use strict";
    this.checkStarted();
    return this.evaluate(function _evaluate(selector, attribute) {
        return __utils__.findOne(selector).getAttribute(attribute);
    }, selector, attribute);
};

/**
 * Retrieves the value of an attribute for each element matching the provided
 * DOM CSS3/XPath selector.
 *
 * @param  String  selector   A DOM CSS3/XPath selector
 * @param  String  attribute  The attribute name to lookup
 * @return Array
 */
Casper.prototype.getElementsAttribute =
Casper.prototype.getElementsAttr = function getElementsAttr(selector, attribute) {
    "use strict";
    this.checkStarted();
    return this.evaluate(function _evaluate(selector, attribute) {
        return [].map.call(__utils__.findAll(selector), function(element) {
            return element.getAttribute(attribute);
        });
    }, selector, attribute);
};

/**
 * Retrieves boundaries for a DOM element matching the provided DOM CSS3/XPath selector.
 *
 * @param  String  selector  A DOM CSS3/XPath selector
 * @param  Boolean page      A flag that allows to get coords of the full page (iframe includes)
 * @return Object
 */
Casper.prototype.getElementBounds = function getElementBounds(selector, page) {
    "use strict";
    this.checkStarted();
    if (!this.exists(selector)) {
        throw new CasperError("No element matching selector found: " + selector);
    }
    var zoomFactor = this.page.zoomFactor || 1;
    var clipRect = this.callUtils("getElementBounds", selector);
    if (zoomFactor !== 1) {
        for (var prop in clipRect) {
            if (clipRect.hasOwnProperty(prop)) {
                clipRect[prop] = clipRect[prop] * zoomFactor;
            }
        }
    }
    if (!utils.isClipRect(clipRect)) {
        throw new CasperError('Could not fetch boundaries for element matching selector: ' + selector);
    }
    if (page) {
        clipRect = {
            "x": clipRect.left + this.page.context.x,
            "y": clipRect.top + this.page.context.y,
            "left": clipRect.left + this.page.context.x,
            "top": clipRect.top + this.page.context.y,
            "width": clipRect.width,
            "height": clipRect.height
        };
    }
    return clipRect;
};

/**
 * Retrieves information about the node matching the provided selector.
 *
 * @param  String|Objects  selector  CSS3/XPath selector
 * @return Object
 */
Casper.prototype.getElementInfo = function getElementInfo(selector) {
    "use strict";
    this.checkStarted();
    if (!this.exists(selector)) {
        throw new CasperError(f("Cannot get informations from %s: element not found.", selector));
    }
    return this.callUtils("getElementInfo", selector);
};

/**
 * Retrieves information about the nodes matching the provided selector.
 *
 * @param String|Objects  selector  CSS3/XPath selector
 * @return Array
 */
Casper.prototype.getElementsInfo = function getElementsInfo(selector) {
    "use strict";
    this.checkStarted();
    if (!this.exists(selector)) {
        throw new CasperError(f("Cannot get information from %s: no elements found.", selector));
    }
    return this.callUtils("getElementsInfo", selector);
};

/**
 * Retrieves boundaries for all the DOM elements matching the provided DOM CSS3/XPath selector.
 *
 * @param  String  selector  A DOM CSS3/XPath selector
 * @return Array
 */
Casper.prototype.getElementsBounds = function getElementsBounds(selector) {
    "use strict";
    this.checkStarted();
    if (!this.exists(selector)) {
        throw new CasperError("No element matching selector found: " + selector);
    }
    var zoomFactor = this.page.zoomFactor || 1;
    var clipRects = this.callUtils("getElementsBounds", selector);
    if (zoomFactor !== 1) {
        Array.prototype.forEach.call(clipRects, function(clipRect) {
            for (var prop in clipRect) {
                if (clipRect.hasOwnProperty(prop)) {
                    clipRect[prop] = clipRect[prop] * zoomFactor;
                }
            }
        });
    }
    return clipRects;
};

/**
 * Retrieves a given form all of its field values.
 *
 * @param  String  selector  A DOM CSS3/XPath selector
 * @return Object
 */
Casper.prototype.getFormValues = function(selector) {
    "use strict";
    this.checkStarted();
    if (!this.exists(selector)) {
        throw new CasperError(f('Form matching selector "%s" not found', selector));
    }
    return this.callUtils("getFormValues", selector);
};

/**
 * Retrieves global variable.
 *
 * @param  String  name  The name of the global variable to retrieve
 * @return mixed
 */
Casper.prototype.getGlobal = function getGlobal(name) {
    "use strict";
    this.checkStarted();
    var result = this.evaluate(function _evaluate(name) {
        var result = {};
        try {
            result.value = JSON.stringify(window[name]);
        } catch (e) {
            var message = "Unable to JSON encode window." + name + ": " + e;
            __utils__.log(message, "error");
            result.error = message;
        }
        return result;
    }, name);
    if (!utils.isObject(result)) {
        throw new CasperError(f('Could not retrieve global value for "%s"', name));
    } else if ('error' in result) {
        throw new CasperError(result.error);
    } else if (utils.isString(result.value)) {
        return JSON.parse(result.value);
    }
};

/**
 * Retrieves current HTML code matching the provided CSS3/XPath selector.
 * Returns the HTML contents for the whole page if no arg is passed.
 *
 * @param  String   selector  A DOM CSS3/XPath selector
 * @param  Boolean  outer     Whether to fetch outer HTML contents (default: false)
 * @return String
 */
Casper.prototype.getHTML = function getHTML(selector, outer) {
    "use strict";
    this.checkStarted();
    if (!selector) {
        return this.page.frameContent;
    }
    if (!this.exists(selector)) {
        throw new CasperError("No element matching selector found: " + selector);
    }
    return this.evaluate(function getSelectorHTML(selector, outer) {
        var element = __utils__.findOne(selector);
        return outer ? element.outerHTML : element.innerHTML;
    }, selector, !!outer);
};

/**
 * Retrieves current page title, if any.
 *
 * @return String
 */
Casper.prototype.getTitle = function getTitle() {
    "use strict";
    this.checkStarted();
    return this.evaluate(function _evaluate() {
        return document.title;
    });
};

/**
 * Handles received HTTP resource.
 *
 * @param  Object  resource  PhantomJS HTTP resource
 */
Casper.prototype.handleReceivedResource = function(resource) {
    "use strict";
    /*eslint max-statements:0*/
    if (resource.stage !== "end") {
        return;
    }
    this.resources.push(resource);

    var checkUrl = ((phantom.casperEngine === 'phantomjs' && utils.ltVersion(phantom.version, '2.1.0')) ||
                   (phantom.casperEngine === 'slimerjs' && utils.ltVersion(slimer.version, '0.10.0'))) ? utils.decodeUrl(resource.url) : resource.url;
    if (checkUrl !== this.requestUrl) {
        return;
    }
    this.currentHTTPStatus = null;
    this.currentResponse = {};
    if (utils.isHTTPResource(resource)) {
        this.emit('page.resource.received', resource);
        this.currentResponse = resource;
        this.currentHTTPStatus = resource.status;
        this.emit('http.status.' + resource.status, resource);
        if (utils.isObject(this.options.httpStatusHandlers) &&
            resource.status in this.options.httpStatusHandlers &&
            utils.isFunction(this.options.httpStatusHandlers[resource.status])) {
            this.options.httpStatusHandlers[resource.status].call(this, this, resource);
        }
    }
    this.currentUrl = resource.url;
    this.emit('location.changed', resource.url);
};

/**
 * Initializes PhantomJS error handler.
 *
 */
Casper.prototype.initErrorHandler = function initErrorHandler() {
    "use strict";
    var casper = this;
    phantom.onError = function phantom_onError(msg, backtrace) {
        casper.emit('error', msg, backtrace);
        if (casper.options.exitOnError === true) {
            casper.exit(1);
        }
    };
};

/**
 * Injects configured local client scripts.
 *
 * @return Casper
 */
Casper.prototype.injectClientScripts = function injectClientScripts(page) {
    "use strict";
    this.checkStarted();
    if (!this.options.clientScripts) {
        return;
    }
    page = page || this.page;
    if (utils.isString(this.options.clientScripts)) {
        this.options.clientScripts = [this.options.clientScripts];
    }
    if (!utils.isArray(this.options.clientScripts)) {
        throw new CasperError("The clientScripts option must be an array");
    }
    this.options.clientScripts.forEach(function _forEach(script) {
        if (page.injectJs(script)) {
            this.log(f('Automatically injected %s client side', script), "debug");
        } else {
            this.warn(f('Failed injecting %s client side', script));
        }
    }.bind(this));
    return this;
};

/**
 * Injects Client-side utilities in current page context.
 *
 */
Casper.prototype.injectClientUtils = function injectClientUtils(page) {
    "use strict";
    this.checkStarted();
    page = page || this.page;
    var clientUtilsInjected = page.evaluate(function() {
        return typeof __utils__ === "object";
    });
    if (true === clientUtilsInjected) {
        return;
    }
    var clientUtilsPath = require('fs').pathJoin(phantom.casperPath, 'modules', 'clientutils.js');
    if (true === page.injectJs(clientUtilsPath)) {
        this.log("Successfully injected Casper client-side utilities", "debug");
    } else {
        this.warn("Failed to inject Casper client-side utilities");
    }
    // ClientUtils and Casper shares the same options
    // These are not the lines I'm the most proud of in my life, but it works.
    /*global __options*/
    page.evaluate(function() {
        window.__utils__ = new window.ClientUtils(__options);
    }.toString().replace('__options', JSON.stringify(this.options)));
};

/**
 * Loads and include remote client scripts to current page.
 *
 * @return Casper
 */
Casper.prototype.includeRemoteScripts = function includeRemoteScripts(page) {
    "use strict";
    var numScripts = this.options.remoteScripts.length, loaded = 0;
    if (numScripts === 0) {
        return this;
    }
    this.waitStart();
    page = page || this.page;
    this.options.remoteScripts.forEach(function(scriptUrl) {
        this.log(f("Loading remote script: %s", scriptUrl), "debug");
        page.includeJs(scriptUrl, function() {
            loaded++;
            this.log(f("Remote script %s loaded", scriptUrl), "debug");
            if (loaded === numScripts) {
                this.log("All remote scripts loaded.", "debug");
                this.waitDone();
            }
        }.bind(this));
    }.bind(this));
    return this;
};

/**
 * Logs a message.
 *
 * @param  String  message  The message to log
 * @param  String  level    The log message level (from Casper.logLevels property)
 * @param  String  space    Space from where the logged event occurred (default: "phantom")
 * @return Casper
 */
Casper.prototype.log = function log(message, level, space) {
    "use strict";
    level = level && this.logLevels.indexOf(level) > -1 ? level : "debug";
    space = space ? space : "phantom";
    if (level === "error" && utils.isFunction(this.options.onError)) {
        this.options.onError.call(this, this, message, space);
    }
    if (this.logLevels.indexOf(level) < this.logLevels.indexOf(this.options.logLevel)) {
        return this; // skip logging
    }
    var entry = {
        level:   level,
        space:   space,
        message: message,
        date:    new Date().toString()
    };
    if (level in this.logFormats && utils.isFunction(this.logFormats[level])) {
        message = this.logFormats[level](message, level, space);
    } else {
        message = f('%s [%s] %s',
                    this.colorizer.colorize(f('[%s]', level), this.logStyles[level]),
                    space,
                    message);
    }
    if (this.options.verbose) {
        this.echo(this.filter('log.message', message) || message); // direct output
    }
    this.result.log.push(entry);
    this.emit('log', entry);
    return this;
};

/**
 * Emulates an event on the element from the provided selector using the mouse
 * pointer, if possible.
 *
 * In case of success, `true` is returned, `false` otherwise.
 *
 * @param  String   type      Type of event to emulate
 * @param  String   selector  A DOM CSS3 compatible selector
 * @param  {Number} x X position
 * @param  {Number} y Y position
 * @return Boolean
 */
Casper.prototype.mouseEvent = function mouseEvent(type, selector, x, y) {
    "use strict";
    this.checkStarted();
    this.log("Mouse event '" + type + "' on selector: " + selector, "debug");
    if (!this.exists(selector)) {
        throw new CasperError(f("Cannot dispatch %s event on nonexistent selector: %s", type, selector));
    }
    if (this.callUtils("mouseEvent", type, selector, x, y)) {
        return true;
    }
    // fallback onto native QtWebKit mouse events
    try {
        return this.mouse.processEvent(type, selector, x, y);
    } catch (e) {
        this.log(f("Couldn't emulate '%s' event on %s: %s", type, selector, e), "error");
    }
    return false;
};

/**
 * Performs an HTTP request, with optional settings.
 *
 * Available settings are:
 *
 * - String  method:   The HTTP method to use
 * - Object  data:     The data to use to perform the request, eg. {foo: 'bar'}
 * - Object  headers:  Custom request headers object, eg. {'Cache-Control': 'max-age=0'}
 *
 * @param  String  location  The url to open
 * @param  Object  settings  The request settings (optional)
 * @return Casper
 */
Casper.prototype.open = function open(location, settings) {
    "use strict";
    /*eslint max-statements:0*/
    va