<commit_before>.. _casper_module:

=====================
The ``casper`` module
=====================

.. index:: Casper

The ``Casper`` class
++++++++++++++++++++

The easiest way to get a casper instance is to use the module's ``create()`` method::

    var casper = require('casper').create();

But you can also retrieve the main Function and instantiate it by yourself::

    var casper = new require('casper').Casper();

.. hint::

   Also, check out :doc:`how to extend Casper with your own methods <../extending>`.

Both the ``Casper`` constructor and the ``create()`` function accept a single ``options`` argument which is a standard javascript object::

    var casper = require('casper').create({
        verbose: true,
        logLevel: "debug"
    });

.. _casper_options:

.. index:: Casper options, options

``Casper.options``
++++++++++++++++++

An ``options`` object can be passed to the ``Casper`` constructor, eg.::

    var casper = require('casper').create({
        clientScripts:  [
            'includes/jquery.js',      // These two scripts will be injected in remote
            'includes/underscore.js'   // DOM on every request
        ],
        pageSettings: {
            loadImages:  false,        // The WebPage instance used by Casper will
            loadPlugins: false         // use these settings
        },
        logLevel: "info",              // Only "info" level messages will be logged
        verbose: true                  // log messages will be printed out to the console
    });

You can also alter options at runtime::

    var casper = require('casper').create();
    casper.options.waitTimeout = 1000;

The whole list of available options is detailed below.

.. index:: Client scripts

.. _casper_option_clientscripts:

``clientScripts``
-------------------------------------------------------------------------------

**Type:** ``Array``

**Default:** ``[]``

A collection of script filepaths to include in every page loaded.

.. index:: exit, error

``exitOnError``
-------------------------------------------------------------------------------

**Type:** ``Boolean``

**Default:** ``true``

Sets if CasperJS must exit when an uncaught error has been thrown by the script.

.. index:: HTTP

``httpStatusHandlers``
-------------------------------------------------------------------------------

**Type:** ``Object``

**Default:** ``{}``

A javascript Object containing functions to call when a requested resource has a given HTTP status code. A dedicated sample is provided as an example.

.. index:: Logging

``logLevel``
-------------------------------------------------------------------------------

**Type:** ``String``

**Default:** ``"error"``

Logging level (see the logging section for more information)

``onAlert``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onAlert(String message)``

A function to be called when a javascript alert() is triggered

``onDie``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onDie(Object Casper, String message, String status)``

A function to be called when Casper#die() is called

.. index:: error, Error handling

``onError``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onError(String msg, Array backtrace)``

A function to be called when an "error" level event occurs

.. index:: error, Error handling

``onLoadError``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onLoadError(Object Casper, String casper.requestUrl, String status)``

A function to be called when a requested resource cannot be loaded

``onPageInitialized``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onPageInitialized(Object page)``

A function to be called after ``WebPage`` instance has been initialized

.. index:: HTTP

``onResourceReceived``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onResourceReceived(Object resource)``

Proxy method for PhantomJS' ``WebPage#onResourceReceived()`` callback, but the current Casper instance is passed as first argument.

.. index:: HTTP

``onResourceRequested``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

Proxy method for PhantomJS' WebPage#onResourceRequested() callback, but the current Casper instance is passed as first argument.

.. index:: Step stack

``onStepComplete``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onStepComplete(Object Casper, stepResult)``

A function to be executed when a step function execution is finished.

.. index:: Step stack, Error handling, timeout

``onStepTimeout``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``Function``

**Signature:** ``onStepTimeout(Integer timeout, Integer stepNum)``<commit_msg>refs #1704 refs #1328 - fixed signatures of event callbacks in docs<commit_after>.. _casper_module:

=====================
The ``casper`` module
=====================

.. index:: Casper

The ``Casper`` class
++++++++++++++++++++

The easiest way to get a casper instance is to use the module's ``create()`` method::

    var casper = require('casper').create();

But you can also retrieve the main Function and instantiate it by yourself::

    var casper = new require('casper').Casper();

.. hint::

   Also, check out :doc:`how to extend Casper with your own methods <../extending>`.

Both the ``Casper`` constructor and the ``create()`` function accept a single ``options`` argument which is a standard javascript object::

    var casper = require('casper').create({
        verbose: true,
        logLevel: "debug"
    });

.. _casper_options:

.. index:: Casper options, options

``Casper.options``
++++++++++++++++++

An ``options`` object can be passed to the ``Casper`` constructor, eg.::

    var casper = require('casper').create({
        clientScripts:  [
            'includes/jquery.js',      // These two scripts will be injected in remote
            'includes/underscore.js'   // DOM on every request
        ],
        pageSettings: {
            loadImages:  false,        // The WebPage instance used by Casper will
            loadPlugins: false         // use these settings
        },
        logLevel: "info",              // Only "info" level messages will be logged
        verbose: true                  // log messages will be printed out to the console
    });

You can also alter options at runtime::

    var casper = require('casper').create();
    casper.options.waitTimeout = 1000;

The whole list of available options is detailed below.

.. index:: Client scripts

.. _casper_option_clientscripts:

``clientScripts``
-------------------------------------------------------------------------------

**Type:** ``Array``

**Default:** ``[]``

A collection of script filepaths to include in every page loaded.

.. index:: exit, error

``exitOnError``
-------------------------------------------------------------------------------

**Type:** ``Boolean``

**Default:** ``true``

Sets if CasperJS must exit when an uncaught error has been thrown by the script.

.. index:: HTTP

``httpStatusHandlers``
-------------------------------------------------------------------------------

**Type:** ``Object``

**Default:** ``{}``

A javascript Object containing functions to call when a requested resource has a given HTTP status code. A dedicated sample is provided as an example.

.. index:: Logging

``logLevel``
-------------------------------------------------------------------------------

**Type:** ``String``

**Default:** ``"error"``

Logging level (see the logging section for more information)

``onAlert``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onAlert(Object Casper, String message)``

A function to be called when a javascript alert() is triggered

``onDie``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onDie(Object Casper, String message, String status)``

A function to be called when Casper#die() is called

.. index:: error, Error handling

``onError``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onError(Object Casper, String msg, Array backtrace)``

A function to be called when an "error" level event occurs

.. index:: error, Error handling

``onLoadError``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onLoadError(Object Casper, String casper.requestUrl, String status)``

A function to be called when a requested resource cannot be loaded

``onPageInitialized``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onPageInitialized(Object page)``

A function to be called after ``WebPage`` instance has been initialized

.. index:: HTTP

``onResourceReceived``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onResourceReceived(Object Casper, Object resource)``

Proxy method for PhantomJS' ``WebPage#onResourceReceived()`` callback, but the current Casper instance is passed as first argument.

.. index:: HTTP

``onResourceRequested``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onResourceRequested(Object Casper, Object resource)``

Proxy method for PhantomJS' WebPage#onResourceRequested() callback, but the current Casper instance is passed as first argument.

.. index:: Step stack

``onStepComplete``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``null``

**Signature:** ``onStepComplete(Object Casper, stepResult)``

A function to be executed when a step function execution is finished.

.. index:: Step stack, Error handling, timeout

``onStepTimeout``
-------------------------------------------------------------------------------

**Type:** ``Function``

**Default:** ``Function``

**Signature:** ``onStepTimeout(Integer timeout, Integer stepNum)``
{'fraction_non_alphanumeric': 0.32214643019554345, 'fraction_numerical': 0.001455206912232833, 'mean_word_length': 1.8702688593056642, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1644987', 'n_tokens_mistral': 2570, 'n_tokens_neox': 2502, 'n_words': 952}