Laravel 4 acceptance testing with Codeception

The Premise

What Laravel does well is make development enjoyable; the thing that I don't enjoy at the moment (like a lot of others I'm sure) is writing tests for my application.
The heavens parted however when I found out about Codeception. Orchestral music began to play & well you get the point.

There are a couple of issues that caused me to stumble along the way so I'll hopefully be helping a poor soul not feel the need to pull their hair out.

Getting It Working

When setting up my environment to make use of Codeception; there were obviously a couple of things that needed to be done to make it work & organise it neatly within the laravel application framework.

These few steps leading up to my own tip, I'll just llink below for anyone that needs the whole process.

Before starting; the following assumes that you are familiar with Laravel 4 & its environment.

Firstly you may wish to checkout a working Laravel & Codeception pairing described in the Codeception docs, which can be found on GitHub.

Installing Codeception

The steps described here by Dave Ganley will get you up & running.

Or if you're a more visual person, Jeffrey Way explains & demonstrates the steps in this video.

Both of these sources don't include a mention of the possible issues that one may face after successfully installing Codeception & running the command "codecept run" in your app.

So, once you start testing your app out:

Possible Issues & Their Fixes

Please note that the following is only valid if you're using a codeception version below 1.6.7 which fixes all the issues I mention below

First off make sure to edit app/tests/acceptance.suite.yml and include the url to access your application. Acceptance tests unless your app is found at localhost will likely fail without doing so.

config:
    PhpBrowser:
        url: 'http://myapp.dev'

The next possible problem you may face is that your acceptance tests just WON'T complete successfully & keep producing a 404 error when trying to test a form of navigation away from the first page you load.

// the following is a simple Codeception example

$I = new WebGuy($scenario);
$I->wantTo('see the login page');

// the virtual user starts at the root/home page
$I->amOnPage('/');
$I->see('Login');

// the user click the login to take them to the login page
$I->click('Login');
// this will fail inexplicably with a 404 despite working correctly in your browser
$I->see('Please Sign In');

Obviously if this has been fixed and is happily working for you when you're reading this some time in the future; feel free to ignore the following, but for those that are stuck:

Thomas Grim details in full the problem & the causes as well as how to fix it here.

Now Thomas' fix is great & works perfectly well to get tests running, but in my case; I've been working on my app for a while & I didn't feel like changing habit to having to remember to add a port to my address. Also, my application happens to make use of oauth and callbacks for services like soundcloud which fail when the requesting url differs from the settings that i've been using all this time. I didn't like the idea of going to change all those settings so instead, I suggest the following for anyone in a similar situation to mine.

As Thomas explained, the fix is to have the address that Codeception's phpBrowser uses be on a port different to the port that apache uses. What I have done is add a second Virtual Host that points to the same app specifically for Codeception to use for acceptance tests & leave my original Virtual Host alone. Much less painful.

As a result you could have your app accessible through your browser at myapp.dev codeception accessing it through test.myapp.dev. Don't forget to change the YAML file!

config:
    PhpBrowser:
        url: 'http://test.myapp.dev:8081'

At this point I haven't determined what issues these little quirks present for being able to automate this process on a CI server like the likes of Travis, Codeship or Wercker, but when I do I'll add that info to this tip.