Getting PhantomJS working with Codeception in < 5 minutes

While getting a friend to look over a Codeception video series I’m preparing to release, he noticed that my tests, automated the starting and stopping of PhantomJS. I pointed him at a cool extension and off he went. Unfortunately Codeception like many projects assumes you are using Composer to manage extensions while promoting a very uncomposer like phar file as the main way to install!

So here is how to get PhantomJS working with Codeception, auto starting and stopping if you use the phar version.

Before we start, go install Codeception and run:

codecept bootstrap

(if you haven’t moved Codeception to usr/local/bin then it will be codecept.phar bootstrap)

Getting PhantomJS up and running

If you are on a Ubuntu or Debian system installing PhantomJS is as simple as:

sudo apt-get install phantomjs

If using OSX you can use Brew and similar, for other OS use it’s package manager. Sorry Windows users, I have no idea how you install PhantomJS guessing it’s an exe file and you click next a lot!

Once installed, check it’s working by going to a terminal and running:

phantomjs --version

Assuming everything has gone smoothly you should see a version number like 1.9.0

That was easy and not even time for a cup of tea.

Getting Codeception to use PhantomJS

PhantomJS makes setting up with applications like Codeception super easy as it has a Web Driver emulator which means if something can cope with Selenium (which Codeception can) then it supports PhantomJS. To get up and running, we tell Codeception to use the Web Driver module by editing Acceptance.suite.yml within your tests folder.

modules:
    enabled: [WebDriver]
    config:
        WebDriver:
            url: 'http://local.wordpress.dev/' # our url base
            browser: firefox
            capabilities:
                unexpectedAlertBehaviour: 'accept'

be careful when editing YAML files, white spaces can have unexpected consequences.

So we have told Codeception to use the Web Driver module, given it the base URL for all our tests and told it to “emulate” firefox. If we were using Selenium, then rather then emulating firefox it would actually be launching a headless version of firefox. Finally we are saying if you get any weird dialogs just accept them when processing the tests.

Launching PhantomJS automatically

Now for the fun bit, to launch PhantomJS automatically we are going to use a Codeception extension Phantoman however we will be ignoring the install instructions on the Github page which assumes composer.

Instead download the Phantoman extension from github.
Copy the Phantoman.php from the src folder
and in your codeception tests folder, place it inside the _support/ folder

This folder loads extensions being used for this test suite only. It’s not a global location. So if you have multiple test suites you need to include it each time (or use Composer method which is preferable)

Next step is to configure your extensions, by editing your codeception.yml

extensions:
    enabled:
        - Codeception\Extension\Phantoman
    config:
     Codeception\Extension\Phantoman:
            path: '/usr/bin/phantomjs'
            debug: true
            sslProtocol: any
            ignoreSslErrors: true

Notice the path /usr/bin/phantomjs is for a Debian/Ubuntu install it might be different for you. Again be careful editing the file, and note extensions are different from modules. While you may have other extensions installed, they may not have a config section.

That’s it, now your acceptance tests will use, PhantomJS and auto start and stop PahntomJS when you run a test it will look something like this:

On a side note take a look at Phantoman code for a way to automate other processes for example I use a modified version to automate Liquibase captures and roll backs.

Finally it’s worth saying if you can, going the Composer method for managing extensions is worth doing. However from the default download of Composer this is PhantomJS up and running in 4.45 seconds.

Not to bad.