PHP

Abstract

PHPUnit is a great tool to protect us developers from introducing new defects when adding new features or re-factoring code. However there is one HUGE downside to PHPUnit; it must be installed using PEAR. Personally, I don’t like ‘auto-installers’, I’d prefer to know what exactly is happening behind the scenes with regards to which libraries are required and how they are being called. So when I needed to use PHPUnit on a recent project I shed a tear thinking I would have to break down and install using PEAR.

PHPUnit is not a mythical creature, it doesn’t have magical powers, and as such, it should not intimidate us. It is PHP code, plain and simple, and like any other PHP API Libraries it can be interwoven into our application. So after breaking down the PHPUnit source code, I realized it could be installed without going through PEAR, and without too much headache.

I wrote this article with the goal that it may help others, and maybe even make it’s way to the lead developer of PHPUnit, where he may start using a better autoloading strategy. However, I must warn you to not hold me responsible for any “issues” that may arise on your system by following this article, as it’s strictly demonstrative at this point. There may come a time where I add this code to a GIT repo and officially support it, but not at this point. If you are ok with that, then read on.

Also, note that you can change any of the following guidelines to suit your specific needs. What I am outlining here worked for me, but may not work for you, so feel free to change what you need to, in order to accomplish your end game.

Base Directories

To make things work, we need a base directories from which to work. As with any setting throughout this article, you can change to meet your needs.

Test directory

This directory will be where we put our actual unit tests:

/home/mpurcell/projects/core/test

Vendor directory

This directory will be the location where we download and extract PHPUnit source code:

/home/mpurcell/projects/vendor

Source Code:

Now that we have our directories in place, lets get PHPUnit source code. Normally you would use PEAR to download, extract, and prepare the source code, but personally I don’t like things of this nature being done for me, I am a big boy, I can handle it myself. So I download each of the core packages manually, then extract them, and set their correct directories in preparation for the next ‘Symlinks‘ step.

The PHPUnit developer uses Github as their version control repo, which is good, but sucks when trying to download packages, as the actual files are abstracted by an intermediary PHP script. What I ended up having to do was download to my local machine, then secure copy them over to the server. Once you have the source files on the server, run the following steps:

$ -> cd ~/projects/vendor

$ -> mkdir phpunit

$ -> cd phpunit

$ -> cp ~/sebastianbergmann-phpunit-3.6.7-9-gf5e159b.zip .

$ -> unzip sebastianbergmann-phpunit-3.6.7-9-gf5e159b.zip

# The unzip will result in a weird hash, so I just rename it to
# the correct version based on the original file name
$ -> mv sebastianbergmann-phpunit-f5e159b/ 3.6.7-9

# Don't need source file anymore
$ -> rm *.zip

# Now, we have phpunit locked into a version which we can quickly
# glean when we inspect symlinks to this library
# Lets get the other necessary packages
$ -> mkdir lib

$ -> cd lib
$ -> pwd
/home/mpurcell/projects/vendor/phpunit/lib

# Setup base dirs for phpunit add-ons
$ -> mkdir codeCoverage fileIterator timer

# Now lets copy our add-ons into their respective dirs
$ -> cp ~/sebastianbergmann-php-code-coverage-1.1.1-14-gdc2a15a.zip codeCoverage
$ -> cp ~/sebastianbergmann-php-timer-1.0.2-5-gb352e92.zip timer

# File iterator lib allows you to set a root directory, and phpunit will traverse the directory looking for unit tests
$ -> cp ~/sebastianbergmann-php-file-iterator-1.3.1-1-gbbaab46.zip fileIterator

# Now that we have the files in our lib directory, lets get them setup
$ -> cd codeCoverage
$ -> pwd
/home/mpurcell/projects/vendor/phpunit/lib/codeCoverage

$ -> unzip sebastianbergmann-php-code-coverage-1.1.1-14-gdc2a15a.zip
$ -> mv sebastianbergmann-php-code-coverage-dc2a15a/ 1.1.1-14
$ -> rm *.zip

$ -> cd ../fileIterator
$ -> pwd
/home/mpurcell/projects/vendor/phpunit/lib/codeCoverage

$ -> unzip sebastianbergmann-php-file-iterator-1.3.1-1-gbbaab46.zip
$ -> mv sebastianbergmann-php-file-iterator-bbaab46/ 1.3.1-1
$ -> rm *.zip

$ -> cd ../timer
$ -> pwd
/home/mpurcell/projects/vendor/phpunit/lib/codeCoverage

$ -> unzip sebastianbergmann-php-timer-1.0.2-5-gb352e92.zip
$ -> mv sebastianbergmann-php-timer-b352e92/ 1.0.2-5
$ -> rm *.zip

Ok, now you should have phpunit and it’s core libraries “installed” on your server. In this context, installed is a loose term, as the code isn’t really installed, it’s now available to be hooked into from your testing environment.

Symlinks

As with any 3rd party APIs introduced into your application, it is always best to abstract away version numbers, so you don’t force your application to require files with version numbers in a file’s uri. For example:

// Good
require_once 'path/to/ThirdParty_Vendor/Api/Class.php';

// Bad
require_once 'path/to/ThirdParty_Vendor-1.1.1-9/Api/Class.php';

Why does this matter? Because, when a new version of the file is released, and you upgrade, you won’t have to update all the code references. Instead, just change the related symlink and your application will work as before, except with the newer version of the file.

So lets make the PHPUnit libraries available to our testing environment:

$ -> cd ~/projects/core/test
$ -> mkdir lib
$ -> cd lib
$ -> pwd
/home/mpurcell/projects/test/lib

$ -> ln -s ~/projects/vendor/phpunit/3.6.7-9/PHPUnit
$ -> ln -s ~/projects/vendor/phpunit/lib/codeCoverage/1.1.1-14/PHP PHPCodeCoverage
$ -> ln -s ~/projects/vendor/phpunit/lib/fileIterator/1.3.1-1/File PHPFileIterator
$ -> ln -s ~/projects/vendor/phpunit/lib/timer/1.0.2-5/PHP PHPTimer

Ok, now we have hooks to phpunit libraries within our testing directory, onto the next step.

Bootstrap

A bootstrapper is meant to prepare a library for usage, and that’s exactly what we are going to do. This bootstrapper will setup include_paths along with a few other settings so we can use run our tests correctly. The code is posted here, otherwise it’s too hard to read in wordpress.

Autoloader

Here’s where the magic lies. This autoloader will know how to map files that PHPUnit is requiring, to their symlinked location. It’s pretty easy to follow, all we do is check for a namespace footprint (PHP_Timer), and if it exists, re-map it to our symlink (PHPTimer). The code is posted here, otherwise it’s too hard to read in wordpress.

Changes to PHPUnit Source code

Now for the ugly. It is NEVER a good idea to edit 3rd party (vendor) code directly, otherwise you update and forget about the changes and your app goes to hell. However in this instance I had no choice, and fortunately I was able to limit the change to just one location in the PHPUnit source code. It is a trivial change, but you should add a README to your ~/projects/vendor/phpunit directory to remind yourself to make this change for future upgrades (assuming the lead developer doesn’t change it himself).

My README file:

ATTENTION!
When upgrading phpunit, 1 change must be made to ensure unit tests work

Why:    This allows us to use our own autloader
File:   PHPUnit/Util/GlobalState.php
Line:   98
Change:
    From:    protected static $phpunitFiles;
    To:      public static $phpunitFiles;

This change makes it so we can override the singleton $phpunitfiles. If we don’t over-ride it, then PHPUnit will attempt to use it’s built-in autoloader, which doesn’t work with our setup. By setting the scope from protected to public, we can over-ride the value with an empty array, as the conditional used in source code check is ‘ === NULL’.

phpunit executable

Now we need to create the phpunit executable which will kick off the unit testing. When I was going through the PHPUnit source code, I noticed that the PEAR installer was just renaming the phpunit.php to phpunit. So, lets copy the phpunit executable which came with PHPUnit to our test directory and make a few minor changes:

$ -> pwd
/home/mpurcell/projects/core/test

$ -> cp ~/projects/vendor/phpunit/3.6.7-9/phpunit.php .

Now, make the following changes:

#!/usr/bin/env php

// Bring in our bootstrap file
require_once substr(__FILE__, 0, strpos(__FILE__, '/test')) . '/test/Bootstrap.php';

// Set our main define
define('PHPUnit_MAIN_METHOD', 'PHPUnit_TextUI_Command::main');

// Remember we set the scope of $phpunitfiles to public?
// Now we can set it to whatever we want, which is just an empty
// array, which allows our autoloader to handle loading files
PHPUnit_Util_GlobalState::$phpunitFiles = array();

// Kick this pig
PHPUnit_TextUI_Command::main();

Home Stretch

Finally, we made it. Now, we can call on the phpunit executable and run tests. First lets create a sample test:

$ -> pwd
/home/mpurcell/projects/core/test

$ -> touch CoreTest/ArrayTest.php

Now lets add an easy test:

<?php
class CoreTest_Api_Array_PackageTest extends PHPUnit_Framework_TestCase{
     public function testCount()
     {
         $this->assertCount(2, array('foo', 'bar'));
     }
}

Now, run the test:

$ -> pwd
/home/mpurcell/projects/core/test

$ -> ./phpunit/CoreTest/

Now your ArrayTest test should run (and pass). Notice that we passed a directory to the ./phpunit executable, you can pass a directory, or a specific test to meet your needs. The PHPFileIterator we setup will parse directories for any files ending in *Test.

Congratulations

Hopefully this article wasn’t too hard to follow, and your unit tests are running though PHPUnit, as if you installed through PEAR. If you wouldn’t mind taking the time to contact the lead developer, and let him know that he should drop PEAR and run an autoloader/bootstrap combo like many other PHP libraries/frameworks, I would greatly appreciate it. He has done a good job, but we need to make PHPUnit easier to install and set-up so others don’t get discouraged and give up unit tests altogether.