CasperJS Deployment & Usage Guide

Important: CasperJS is no longer actively maintained. This guide is provided for legacy system maintenance and existing test suites. For new projects, consider modern alternatives like Puppeteer, Playwright, or Cypress.

1. Prerequisites

Before installing CasperJS, ensure you have the following dependencies:

PhantomJS 1.9.7+ or 2.0+ (required)
- Download from phantomjs.org
- PhantomJS 2.0+ requires CasperJS 1.1.0 or later (master branch)
Python 2.7 or 3.x (required for the CLI launcher)
Git (for source installation)
SlimerJS (optional, for Gecko/Firefox engine support)

Note: CasperJS cannot run within a Node.js environment. It requires a PhantomJS or SlimerJS runtime.

2. Installation

Method A: Source Installation (Recommended)

Install the latest stable development version from the master branch:

# Clone the repository
git clone https://github.com/casperjs/casperjs.git
cd casperjs

# Verify you're on master (stable development version)
git branch

# Add to PATH (temporary for current session)
export PATH=$PATH:`pwd`/bin

# For permanent installation, symlink to a directory in your PATH
sudo ln -sf `pwd`/bin/casperjs /usr/local/bin/casperjs

Method B: NPM Installation

While CasperJS is not a Node.js module, it can be distributed via npm:

npm install -g casperjs

Note: This requires that PhantomJS is installed separately and available in your PATH.

Method C: Homebrew (macOS)

brew install casperjs

Verification

Verify installation and check versions:

casperjs --version
casperjs --help

3. Configuration

Environment Variables

Configure the JavaScript engine paths if executables are not in your system PATH:

# PhantomJS (default engine)
export PHANTOMJS_EXECUTABLE=/usr/local/bin/phantomjs

# SlimerJS (alternative engine)
export SLIMERJS_EXECUTABLE=/usr/local/bin/slimerjs

Engine Selection

Run scripts with a specific engine using the --engine flag:

# Use SlimerJS instead of PhantomJS
casperjs script.js --engine=slimerjs

Important: SlimerJS support is still experimental.

4. Build & Run

Running CasperJS Scripts

Create a navigation script (e.g., scrape.js):

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

casper.start('http://example.com/', function() {
    this.echo(this.getTitle());
});

casper.run();

Execute the script:

casperjs scrape.js

Running Tests

CasperJS includes a testing framework. Create a test file:

casper.test.begin('Example test suite', 1, function(test) {
    casper.start('http://example.com/', function() {
        test.assertTitle('Example Domain');
    }).run(function() {
        test.done();
    });
});

Run the test:

casperjs test testfile.js

Self-Testing

Verify your CasperJS installation is working correctly:

casperjs selftest

Note: For version 1.0 branch tests, you must run casperjs selftest manually.

Advanced Example

Dropdown interaction test (from the official samples):

casper.test.begin('a twitter bootstrap dropdown can be opened', 2, function(test) {
    casper.start('http://getbootstrap.com/2.3.2/javascript.html#dropdowns', function() {
        test.assertExists('#navbar-example');
        this.click('#dropdowns .nav-pills .dropdown:last-of-type a.dropdown-toggle');
        this.waitUntilVisible('#dropdowns .nav-pills .open', function() {
            test.pass('Dropdown is open');
        });
    }).run(function() {
        test.done();
    });
});

5. Deployment

Since CasperJS is a command-line testing and navigation utility (not a web service), "deployment" refers to integration into CI/CD pipelines and production execution environments.

Docker Deployment

Create a Dockerfile for consistent execution environments:

FROM ubuntu:20.04

# Install dependencies
RUN apt-get update && apt-get install -y \
    phantomjs \
    python3 \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install CasperJS
RUN git clone https://github.com/casperjs/casperjs.git /opt/casperjs \
    && ln -s /opt/casperjs/bin/casperjs /usr/local/bin/casperjs

WORKDIR /app
COPY . .

CMD ["casperjs", "test", "tests/"]

CI/CD Integration

Travis CI (.travis.yml):

language: python
python:
  - "3.8"
before_install:
  - wget https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-2.1.1-linux-x86_64.tar.bz2
  - tar -xjf phantomjs-2.1.1-linux-x86_64.tar.bz2
  - sudo mv phantomjs-2.1.1-linux-x86_64/bin/phantomjs /usr/local/bin/
install:
  - git clone https://github.com/casperjs/casperjs.git
  - export PATH=$PATH:$PWD/casperjs/bin
script:
  - casperjs test tests/

Jenkins Pipeline:

pipeline {
    agent any
    environment {
        PHANTOMJS_EXECUTABLE = '/usr/bin/phantomjs'
    }
    stages {
        stage('Test') {
            steps {
                sh 'casperjs test tests/'
            }
        }
    }
}

Production Scraping Considerations

Run CasperJS in a screen/tmux session or use nohup for long-running scripts
Implement retry logic for network failures
Use --ignore-ssl-errors=true and --web-security=false for problematic sites (security implications apply)
Rotate User-Agent strings to avoid blocking

6. Troubleshooting

"CasperJS cannot be executed within a nodejs environment"

Cause: Attempting to run CasperJS with Node.js instead of PhantomJS.
Solution: Ensure you're using the casperjs command, not node. CasperJS requires PhantomJS or SlimerJS runtime.

PhantomJS version compatibility

Issue: Scripts fail with PhantomJS 2.0 using CasperJS ≤1.0.
Solution: Upgrade to CasperJS 1.1.0+ or master branch. Versions up to 1.1-beta3 do not support PhantomJS 2.0.

Module not found errors

Cause: CasperJS modules not in load path.
Solution: Ensure you're running scripts with the casperjs command, not directly with PhantomJS. The bootstrapper sets up module paths automatically.

SlimerJS engine not detected

Solution: Explicitly set the executable path:

export SLIMERJS_EXECUTABLE=/path/to/slimerjs
casperjs script.js --engine=slimerjs

SSL/Certificate errors

Fix: Launch with SSL error ignoring (development only):

casperjs --ignore-ssl-errors=true --ssl-protocol=any script.js

Debugging scripts

Enable verbose logging:

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

1.0 branch obsolescence

The 1.0 branch only supports PhantomJS 1.9.x and is unmaintained. Migrate to master branch or 1.1.x releases for modern PhantomJS support.

How to Deploy & Use casperjs/casperjs