Using PHPUnit

PHPUnit is cool. It will make you write better code. You can even use it for testing.
Here's how you use PHPUnit on your codebase:

1. Download and unzip PHPUnit. Copy the extracted folder under your project called
test/lib/PHPUnit

2. There is a shell script called phpunit at test/lib/phpunit

This isn't set in stone, and will probably change over time.
But for now, run a unit test by typing:

test/lib/phpunit path/to/mytest.php

You can add PHPUnit to your path like this:

export PATH=$PATH:test/lib

or create an alias like this:

alias phpunit='test/lib/phpunit'

Now you can type the following from anywhere:

phpunit path/to/mytest.php

3. You probably want to write a test by now.

Hold your horses. Let's talk about some conventions first.

If you are writing a unit test (testing a single class or file), your test file should be under
/tests, but mirroring the /codebase file structure.

For example, if you have a class under codebase/classes/Cheese/Whiz.php

you would create a unit test for it under tests/classes/Cheese/Whiz_Test.php

Your class might be called Cheese_Whiz and if it is, I'd really prefer that you named your
unit test Cheese_Whiz_Test

There's a bit more to know about code conventions, but I can hear you yawning, so let's
write a test and even better, run it!
 class Cheese_Whiz_Test extends PHPUnit_Framework_TestCase {
public function testIsItReallyCheese() {
$this->fail('Cheese Whiz is not really cheese');
}
}

You might have noticed a couple things:

o every test extends PHPUnit_Framework_TestCase

o every test method starts with the magic 4 letters 'test'

You might have noticed some other things or have some questions, but here and now is
not the time or place to discuss them.
Allow me to refer you to the fine manual:

http://www.phpunit.de/

4. Let's run our test and see what happens.

The easiest way to do this is from the command line in dev. Assuming you are in your
project root folder (e.g. ~/public_html), type:

phpunit tests/classes/Cheese/Whiz_Test.php

Here's the output I got:

Whiz_Test.php
PHPUnit 3.3.9 by Sebastian Bergmann.

Time: 0 seconds

There was 1 failure:

1) testIsItReallyCheese(Cheese_Whiz_Test)
Cheese Whiz is not really cheese
/usr/home/aevans/member-
refactor/tests/classes/Cheese/Whiz_Test.php:4

FAILURES!
Tests: 1, Assertions: 0, Failures: 1.

It failed. No surprises there, unless you believe the Kraft marketing. That's what the “F”
stands for.
 The last line shows the total number of tests run (1), the total number of assertions (0 –
because we failed automatically), and the number of failures (1). Sadly, you have to do a
little math to find out how many tests passed.

5. Before you go forth and start testing everything in sight, there's one more thing you
need to know.

Because we're not running through a web browser, we need to do a little setup and tie
it all together with some glue. Add this line to the start of every test:

require_once('/home/'.$_ENV['USER'].'/testconfig.php');

This is looking for a file called testconfig.php in your home directory. It sets some values
and enables us to autoload all of our classes.

It looks something like this:

<?php
$docroot = '/home/'.$_ENV['USER'].'/public_html';
putenv("HTTP_HOST=your.hostname.com");
define('DOCUMENT_ROOT',$docroot);
require_once($docroot.'/codebase/includes/base.php);
?>

I'm sure this is going to get more complex as we go along, but right now all you need to
do is change the part that says 'aaron' to your name.

6. Now you're ready to write some real tests.

Please give me a holler and we can work through any questions you have and I'd love to
pair up and write some tests together. It helps me learn the code base, and might help
you get some tests written.
7. One more thing. If you want to run a bunch of tests together, you can either create a
suite (see the fine documentation), or run phpunit against a directory. For example:

phpunit tests/classes/Cheese

will run all the phpunit tests it finds under the Cheese folder.

You could run phpunit tests and it will run all the tests it finds in the whole project,
Beware though, there are some tests that shouldn't be run all the time, and some that
will fail. We're working on clearing that up.

8. One last thing-- just kidding Columbo.

We'll talk about the difference between unit tests and integration tests later.
This document was written by Aaron Evans aarone@one-shore.com.