In this short, yet comprehensive, tutorial, we'll have a look at behavior driven development (BDD) with phpspec. Mostly, it will be an introduction to the phpspec tool, but as we go, we'll touch on different BDD concepts. BDD is a hot topic these days and phpspec has gained a lot of attention in the PHP community recently.

SpecBDD & Phpspec

BDD is all about describing the behavior of software, in order to get the design right. It is often associated with TDD, but whereas TDD focus on testing your application, BDD is more about describing its behavior. Using a BDD approach will force you to constantly consider the actual requirements and desired behavior of the software you're building.

Two BDD tools have gained a lot of attention in the PHP community recently, Behat and phpspec. Behat helps you describe the external behavior of your application, using the readable Gherkin language. phpspec, on the other hand, helps you describe the internal behavior of your application, by writing small "specs" in the PHP language - hence SpecBDD. These specs are testing that your code has the desired behavior.

What We Will Do

In this tutorial, we'll cover everything related to getting started with phpspec. On our way, we'll build the fundament of a todo list application, step-by-step, using a SpecBDD approach. As we go, we'll have phpspec lead the way!

Note: This is an intermediate article about PHP. I assume you have a good grasp of object-oriented PHP.

Installation

For this tutorial, I assume you have the following stuff up and running:

• A working PHP setup (min. 5.3)
• Composer

Installing phpspec through Composer is the easiest way. All you have to do is run the following command in a terminal:

$ composer require phpspec/phpspec
Please provide a version constraint for the phpspec/phpspec requirement: 2.0.*@dev

This will make a composer.json file for you and install phpspec in a vendor/ directory.

In order to make sure that everything is working, run phpspec and see that you get the following output:

$ vendor/bin/phpspec run

0 specs
0 examples 
0ms

Configuration

Before we start, we need to do a little bit of configuration. When phpspec runs, it looks for a YAML file named phpspec.yml. Since we will be putting our code in a namespace, we need to make sure that phpspec knows about this. Also, while we are at it, let's make sure that our specs looks nice and pretty when we run them.

Go ahead and make the file with the following content:

formatter.name: pretty
suites:
    todo_suite:
        namespace: Petersuhm\Todo

There are many other configuration options available, which you can read about in the documentation.

Another thing we need to do, is to tell Composer how to autoload our code. phpspec will use Composer's autoloader, so this is required for our specs to run.

Add an autoload element to the composer.json file that Composer made for you:

{
    "require": {
        "phpspec/phpspec": "2.0.*@dev"
    },
    "autoload": {
        "psr-0": {
            "Petersuhm\\Todo": "src"
        }
    }
}

Running composer dump-autoload will update the autoloader after this change.

Our First Spec

Now we are ready to write our first spec. We'll start by describing a class called TaskCollection. We'll have phpspec generate a spec class for us by using the describe command (or alternatively the short version desc) .

$ vendor/bin/phpspec describe "Petersuhm\Todo\TaskCollection"
$ vendor/bin/phpspec run
Do you want me to create `Petersuhm\Todo\TaskCollection` for you? y

So what happened here? First, we asked phpspec to create a spec for a TaskCollection. Second, we ran our spec suite and then phpspec automagically offered to create the actual TaskCollection class for us. Cool, isn't it?

Go ahead and run the suite again, and you'll see that we already have one example in our spec (we'll see in a moment what an example is):

$ vendor/bin/phpspec run

      Petersuhm\Todo\TaskCollection

  10  ✔ is initializable


1 specs
1 examples (1 passed)
7ms

From this output, we can see that the TaskCollection is initializable. What is this about? Take a look at the spec file that phpspec generated, and it should be clearer:

<?php

namespace spec\Petersuhm\Todo;

use PhpSpec\ObjectBehavior;
use Prophecy\Argument;

class TaskCollectionSpec extends ObjectBehavior
{
    function it_is_initializable()
    {
        $this->shouldHaveType('Petersuhm\Todo\TaskCollection');
    }
}

The phrase 'is initializable' is derived from a function named it_is_initializable() which phpspec has added to a class called TaskCollectionSpec. This function is what we refer to as an example. In this particular example, we have what we refer to as a matcher called shouldHaveType() that checks the type of our TaskCollection. If you change the parameter passed to this function to something else and run the spec again, you will see that it will fail. Before completely understanding this, I think we need to investigate in what the variable $this refers to in our spec.

What Is $this?

Of course, $this refers to the instance of the class TaskCollectionSpec, since this is just regular PHP code. But with phpspec, you have to treat $this different from what you normally do, since under the hood, it's actually referring to the object under test, which is in fact the TaskCollection class. This behavior is inherited from the class ObjectBehavior, which makes sure that function calls are proxied to the spec'ed class. This means that SomeClassSpec will proxy method calls to an instance of SomeClass. phpspec will wrap these method calls in order to run their return values against matchers like the one you just saw.

You don't need a deep understanding of this in order to use phpspec, just remember that as far as you are concerned, $this actually refers to the object under test.

Building Our Task Collection

So far, we haven't done anything ourself. But phpspec have made an empty TaskCollection class for us to use. Now is the time to fill in some code and make this class useful. We will add two methods: an add() method, to add tasks, and a count() method, to count the number of tasks in the collection.

Adding a Task

Before we write any real code, we should write an example in our spec. In our example, we want to try to add a task to the collection, and then afterwards make sure that the task is in fact added. In order to do this, we need an instance of the (so far non-existing) Task class. If we add this dependency as a parameter to our spec function, phpspec will automatically give us an instance that we can use. Actually, the instance isn't a real instance, but what phpspec refers to as a Collaborator. This object will act as the real object, but phpspec allows us to do more fancy stuff with this, which we'll see soon. Even though the Task class doesn't exist yet, for now, just pretend it does. Open up the TaskCollectionSpec and add a use statement for the Task class and then add the example it_adds_a_task_to_the_collection():

use Petersuhm\Todo\Task;

...

function it_adds_a_task_to_the_collection(Task $task)
{
    $this->add($task);
    $this->tasks[0]->shouldBe($task);
}

In our example, we write the code "we wish we had". We call the add() method and then try to give it a $task. Then we check that the task was in fact added to the instance variable $tasks. The matcher shouldBe() is an identity matcher similar to the PHP === comparator. You can use either shouldBe(), shouldBeEqualTo(), shouldEqual() or shouldReturn() - they all do the same.

Running phpspec will yield some errors, since we don't have a class named Task yet.

Let's have phpspec fix that for us:

$ vendor/bin/phpspec describe "Petersuhm\Todo\Task"
$ vendor/bin/phpspec run
Do you want me to create `Petersuhm\Todo\Task` for you? y

Running phpspec again, something interesting happens:

$ vendor/bin/phpspec run
Do you want me to create `Petersuhm\Todo\TaskCollection::add()` for you? y

Perfect! If you take a look at the TaskCollection.php file, you will see that phpspec made an add() function for us to fill out:

<?php

namespace Petersuhm\Todo;

class TaskCollection
{

    public function add($argument1)
    {
        // TODO: write logic here
    }
}

phpspec is still complaining, though. We don't have a $tasks array, so let's make one and add the task to it:

<?php

namespace Petersuhm\Todo;

class TaskCollection
{
    public $tasks;

    public function add(Task $task)
    {
        $this->tasks[] = $task;
    }
}

Now our specs are all nice and green. Note that I made sure to typehint the $task parameter.

Just to make sure we got it right, let's add another task:

function it_adds_a_task_to_the_collection(Task $task, Task $anotherTask)
{
    $this->add($task);
    $this->tasks[0]->shouldBe($task);

    $this->add($anotherTask);
    $this->tasks[1]->shouldBe($anotherTask);
}

Running phpspec, it looks like we're all good.

Implementing the Countable Interface

We want to know how many tasks are in a collection, which is a great reason for using one of the interfaces from the Standard PHP Library (SPL), namely the Countable interface. This interface dictates that a class implementing it must have a count() method.

Earlier, we used the matcher shouldHaveType(), which is a type matcher. It uses the PHP comparator instanceof to validate that an object is in fact an instance of a given class. There are 4 type matchers, which all does the same. One of them is shouldImplement(), which is perfect for our purpose, so let's go ahead and use that in an example:

function it_is_countable()
{
    $this->shouldImplement('Countable');
}

See how beautiful that reads? Let's run the example and have phpspec lead the way for us:

$ vendor/bin/phpspec run

        Petersuhm/Todo/TaskCollection
  25  ✘ is countable
        expected an instance of Countable, but got [obj:Petersuhm\Todo\TaskCollection].

Okay, so our class isn't an instance of Countable since we haven't implemented it yet. Let's update the code for our TaskCollection class:

class TaskCollection implements \Countable

Our tests won't run, since the Countable interface has an abstract method, count(), which we have to implement. An empty method will do the trick for now:

public function count()
{
    // ...
}

And we're back to green. At the moment our count() method doesn't do much, and it's actually pretty useless. Let's write a spec for the behavior that we wish it to have. First, with no tasks, our count function is expected to return zero:

function it_counts_elements_of_the_collection()
{
    $this->count()->shouldReturn(0);
}

It returns null, not 0. To get a green test, let's fix this the TDD/BDD way:

public function count()
{
    return 0;
}

We're green and all is good, but this is probably not the behavior we want. Instead, let's expand our spec and add something to the $tasks array:

function it_counts_elements_of_the_collection()
{
    $this->count()->shouldReturn(0);

    $this->tasks = ['foo'];
    $this->count()->shouldReturn(1);
}

Of course, our code is still returning 0, and we have a red step. Fixing this is not too difficult and our TaskCollection class should now look like this:

<?php

namespace Petersuhm\Todo;

class TaskCollection implements \Countable
{
    public $tasks;

    public function add(Task $task)
    {
        $this->tasks[] = $task;
    }

    public function count()
    {
        return count($this->tasks);
    }
}

We have a green test and our count() method works. What a day!

Expectations & Promises

Remember I told you that phpspec allows you to do cool stuff with instances of the Collaborator class, AKA the instances that are automatically injected by phpspec? If you have been writing unit tests before, you know what mocks and stubs are. If you don't, please don't worry too much about it. It's only jargon. These things refers to "fake" objects that will act as your real objects, but allow you to test in isolation. phpspec will automatically turn these Collaborator instances into mocks and stubs if you need it in your specs. 

This is really awesome. Under the hood, phpspec uses the Prophecy library, which is a highly opinionated mocking framework that plays well with phpspec (and is build by the same awesome folks). You can set an expectation on a collaborator (mocking), like "this method should be called", and you can add promises (stubbing), like "this method will return this value". With phpspec this is really easy and we'll do both things next.

Let's make a class, we'll call it TodoList, that can make use of our collection class.

$ vendor/bin/phpspec desc "Petersuhm\Todo\TodoList"
$ vendor/bin/phpspec run
Do you want me to create `Petersuhm\Todo\TodoList` for you? y

Adding Tasks

The first example we'll add, is one for adding tasks. We will make an addTask() method, that does nothing more than adding a task to our collection. It simply directs the call to the add() method on the collection, so this is a perfect place to make use of an expectation. We do not want the method to actually call the add() method, we just want to make sure that it tries to do it. Furthermore, we want to make sure that it calls it only once. Take a look at how we can go about this with phpspec:

<?php

namespace spec\Petersuhm\Todo;

use PhpSpec\ObjectBehavior;
use Prophecy\Argument;
use Petersuhm\Todo\TaskCollection;
use Petersuhm\Todo\Task;

class TodoListSpec extends ObjectBehavior
{
    function it_is_initializable()
    {
        $this->shouldHaveType('Petersuhm\Todo\TodoList');
    }

    function it_adds_a_task_to_the_list(TaskCollection $tasks, Task $task)
    {
        $tasks->add($task)->shouldBeCalledTimes(1);
        $this->tasks = $tasks;

        $this->addTask($task);
    }
}

First, we have phpspec provide us with the two collaborators we need: a task collection and a task. Then we set an expectation on the task collection collaborator that basically says: "the add() method should be called exactly 1 time with the variable $task as a parameter". This is how we prepare our collaborator, which is now a mock, before we assign it to the $tasks property on the TodoList. Finally, we try to actually call the addTask() method.

Ok, what does phpspec have to say about this:

$ vendor/bin/phpspec run

        Petersuhm/Todo/TodoList
  17  ! adds a task to the list
        property tasks not found.

The $tasks property is non-existing - easy one:

<?php

namespace Petersuhm\Todo;

class TodoList
{
    public $tasks;
}

Try again, and have phpspec guide our way:

$ vendor/bin/phpspec run
Do you want me to create `Petersuhm\Todo\TodoList::addTask()` for you? y
$ vendor/bin/phpspec run

        Petersuhm/Todo/TodoList
  17  ✘ adds a task to the list
        some predictions failed:
          Double\Petersuhm\Todo\TaskCollection\P4:
            Expected exactly 1 calls that match:
              Double\Petersuhm\Todo\TaskCollection\P4->add(exact(Double\Petersuhm\Todo\Task\P3:000000002544d76d0000000059fcae53))
            but none were made.

Okay, now something interesting happened. See the message "Expected exactly 1 calls that match: ..."? This is our failing expectation. This happens because after calling the addTask() method, the add() method on the collection was not called, which we expected it to be.

In order to get back to green, fill in the following code in the empty addTask() method:

<?php

namespace Petersuhm\Todo;

class TodoList
{
    public $tasks;

    public function addTask(Task $task)
    {
        $this->tasks->add($task);
    }
}

Back to green! It feels good, right?

Checking for Tasks

Let's have a look at promises too. We want a method that can tell us if there are any tasks in the collection. For this, we'll simply check the return value of the count() method on the collection. Again, we do not need a real instance with a real count() method. We just need to make sure that our code calls some count() method and do some stuff depending on the return value.

Take a look at the following example:

function it_checks_whether_it_has_any_tasks(TaskCollection $tasks)
{
    $tasks->count()->willReturn(0);
    $this->tasks = $tasks;

    $this->hasTasks()->shouldReturn(false);
}

We have a task collection collaborator that has a count() method that will return zero. This is our promise. What this means is that every time someone calls the count() method, it will return zero. We then assign the prepared collaborator to the $tasks property on our object. Finally, we try to call a method, hasTasks(), and make sure it returns false.

What does phspec have to say about this?

$ vendor/bin/phpspec run
Do you want me to create `Petersuhm\Todo\TodoList::hasTasks()` for you? y
$ vendor/bin/phpspec run

        Petersuhm/Todo/TodoList
  25  ✘ checks whether it has any tasks
        expected false, but got null.

Cool. phpspec made us a hasTasks() method and not surprisingly, it returns null, not false.

Once again, this is an easy one to fix:

public function hasTasks()
{
    return false;
}

We are back to green, but this is not quite what we want. Let's check for tasks when there are 20 of them. This should return true:

function it_checks_whether_it_has_any_tasks(TaskCollection $tasks)
{
    $tasks->count()->willReturn(0);
    $this->tasks = $tasks;

    $this->hasTasks()->shouldReturn(false);

    $tasks->count()->willReturn(20);
    $this->tasks = $tasks;

    $this->hasTasks()->shouldReturn(true);
}

Run phspec and we'll get:

$ vendor/bin/phpspec run

        Petersuhm/Todo/TodoList
  25  ✘ checks whether it has any tasks
        expected true, but got false.

Okay, false is not true, so we need to improve our code. Let's use that count() method to see if there are tasks or not:

public function hasTasks()
{
    if ($this->tasks->count() > 0)
        return true;

    return false;
}

Tah dah! Back to green!

Building Custom Matchers

Part of writing good specs is to make them as readable as possible. Our last example can actually be improved a tiny bit, thanks to phpspec's custom matchers. It's easy to implement custom matchers - all we have to do is to overwrite the getMatchers() method that is inherited from ObjectBehavior. By implementing two custom matchers, our spec can be changed to look like this:

function it_checks_whether_it_has_any_tasks(TaskCollection $tasks)
{
    $tasks->count()->willReturn(0);
    $this->tasks = $tasks;

    $this->hasTasks()->shouldBeFalse();

    $tasks->count()->willReturn(20);
    $this->tasks = $tasks;

    $this->hasTasks()->shouldBeTrue();
}

function getMatchers()
{
    return [
        'beTrue' => function($subject) {
            return $subject === true;
        },
        'beFalse' => function($subject) {
            return $subject === false;
        },
    ];
}

I think this looks pretty good. Remember, that refactoring your specs is important in order to keep them up to date. Implementing your own custom matchers can clean up your specs and make them more readable.

Actually, we can use the negation of the matchers as well:

function it_checks_whether_it_has_any_tasks(TaskCollection $tasks)
{
    $tasks->count()->willReturn(0);
    $this->tasks = $tasks;

    $this->hasTasks()->shouldNotBeTrue();

    $tasks->count()->willReturn(20);
    $this->tasks = $tasks;

    $this->hasTasks()->shouldNotBeFalse();
}

Yeah. Pretty cool!

Conclusion

All our specs are green and look at how nicely they document our code!

      Petersuhm\Todo\TaskCollection

  10  ✔ is initializable
  15  ✔ adds a task to the collection
  24  ✔ is countable
  29  ✔ counts elements of the collection

      Petersuhm\Todo\Task

  10  ✔ is initializable

      Petersuhm\Todo\TodoList

  11  ✔ is initializable
  16  ✔ adds a task to the list
  24  ✔ checks whether it has any tasks


3 specs
8 examples (8 passed)
16ms

We have effectively described and achieved the desired behavior of our code. Not to mention, our code is 100 % covered by our specs, which means that refactoring won't be a fear-inducing experience.

By following along, I hope you got inspired to give phpspec a try. It is more than a testing tool - it's a design tool. Once you get used to using phpspec (and its awesome code generation tools), you'll have a hard time letting go of it again! People often complain that doing TDD or BDD slows them down. After incorporating phpspec in my work flow, I really feel the opposite way - my productivity is significantly improved. And my code is more solid!