PHP Integration Testing – Getting Started After Unit Testing

PHPunit testing

I've written a class that manages recipients on a MailChimp list, called MailChimpRecipient. It uses the MCAPI class, which is an third-party API wrapper.

http://apidocs.mailchimp.com/api/1.3/
http://apidocs.mailchimp.com/api/downloads/

I pass the MCAPI object into the constructor of the MailChimpRecipient object, so I have written unit tests using PHPUnit that test all of the logic in my own class (I am not testing the MCAPI class). I have 100% code coverage and all tests pass. This is done by mocking and stubbing the MCAPI object.

My next step was to write an integration test, also using PHPUnit, where I would construct the MailChimpRecipient fixture using a real MCAPI object, set up to use a real MailChimp list.

I have written what I think is an intergration test, which basically runs tests agains the public interface of the object, like:

public function testAddedRecipientCanBeFound()
{
    $emailAddress = 'fred@fredsdomain.com';
    $forename = 'Fred';
    $surname = 'Smith';

    // First, delete the email address if it is already on the list
    $oldRecipient = $this->createRecipient();
    if($oldRecipient->find($emailAddress))
    {
        $oldRecipient->delete();
    }
    unset($oldRecipient);

    // Add the recipient using the test data
    $newRecipient = $this->createRecipient();
    $newRecipient->setForename($forename);
    $newRecipient->setSurname($surname);
    $newRecipient->setEmailAddress($emailAddress);
    $newRecipient->add();
    unset($newRecipient);

    // Assert that the recipient can be found using the same email address
    $this->assertTrue($this->_recipient->find($emailAddress));
}

The "integration" test doesn't test any of the internals of the class – it just makes sure that given a real MCAPI object, it behaves as advertised.

Is this correct? Is this the best way to run an intergation test? After all, the internals have been tested with a unit test. Am I right in thinking that the integration test is there to test that it really works, according the way its behaviour is advertised?

To take it a step further, the MailChimpRecipient class implements an interface, which will also be implemented by other classes. The idea is to use a factory to pass different types of mailing list recipient objects to my code, which all do the same thing, albeit using different mailing list providers. Since my integration tests test the that interface, how about using it for all of the classes that implement the interface? Then, in the future, if I design a new class to be used interchangably, I can run the same integration test before inserting it into a project.

Does this sound reasonable? The unit tests test the internals of an object, intergration tests make sure that it behaves as advertised?

Best Answer

When testing your code you should pay attention to three areas:

Scenario testing
Functional testing
Unit testing

Normally the amount of test you have in each category would have the shape of a pyramid, meaning a lot unit tests at the bottom, some functional tests in the middle, and just a few scenario tests.

With a unit test you mock out everything that the class under test uses and you test it in pure isolation (this is why it's important to make sure that inside your class you retrieve all dependencies trough injection so they can be replaced under test).

With unit testing you test all possibilities, so not only the 'happy path' but also all error conditions.

If you are completely certain that your all units work in isolation you write a couple of tests (functional tests) to make sure the units also work when combined. Then you write a scenario test, which tests the wiring between all the functional modules.

For example, suppose you're testing a car.

You could assemble the whole car and as a driver check every possible condition but that would be really hard to do.

Instead you would test a small part of the engine with all possibilities (unit test)

Then you test the whole engine (separate from the car) which would be a functional test.

As a last test, you put your key in, start the car and drive it to the parking lot. If that's working then you know that all parts (battery, fuel, engine, ..) are connected and since you tested them in isolation you can be pretty sure that the whole car is functioning correctly.

So in your case, you tested all error conditions and the happy path in your unit test and know you only have to an end-to-end test with the 'real components' to check if the wiring is correct.

A few other points,

Avoid conditional logic in your unit test. If you have to clean up, your using some kind of global state and the tests can suddenly influence each other.
Don't specify any data that's not relevant for the test. If I would change forename, or surname, would the test fail? Probably not because it's the email address that's important but because you mention it explicitly in your test, I can't be sure. Try looking at the Builder Pattern for building your test data and making it explicit what's really important.

Related Solutions

Unit Testing Integration Tests – Are Integration Tests Meant to be Redundant?

It sort of seems like a test that says, "yes, your production code is actually working when you don't stub or mock things out."

That's exactly what it is.

Stubs and mocks isolate the infrastructure from your unit tests, which means that your units get tested, but not the infrastructure that you've stubbed out, nor the connections your units make with that infrastructure. It's the behavior of your units and the way that behavior interacts with the actual components that you've stubbed out that is being tested in an integration test.

Remember, stubs and mocks don't represent the actual behavior of a real system; they only simulate a small number of artificially-induced behaviors so that you can run your unit tests. An integration test not only provides a more realistic exercise of the system, but also a more comprehensive one.

Php – How to pass a mock object into a class for unit tests

However, I'm not using Dependency Injection so I cannot use this approach.

Are you sure you're not? Because when you write code like this:

class Example
{
    private $dependency;

    public function __construct(Dependency $dependency)
    {
        $this->dependency = $dependency;
    }
}

That screams dependency injection at me (your first Example above is ready for constructor injection). After all dependency injection is nothing more then a fancy term for passing a parameter in to become part of state. Some like to use DI container frameworks or libraries to do their DI in what amounts to a new language but others like to stick with the tools built into their language and use Pure DI. What you provided above is an example of Pure DI.

Either way you do it the main point is to separate construction code from behavior code. So long as you do that you get DI's main benefit: the ability to reconfigure without much rewriting.

A simple pattern for using Pure DI is to do the composing (constructing) in main (or as far up the call stack as you can get). But in PHP main is just the first line of code. So assume that's where the following lives:

$example = new Example( new Dependency() );

There's your injection. No DI container needed. If you have more injections for more objects to do you put them here as well. Doing this you can build up a connected object graph. If you need to change Dependency so that it depends on something else you build that in here as well. Whether you give them $ names is up to you. Whatever is most readable. Just don't go nuts¹. Remember, names are a good thing.

Once everything is composed/constructed you write one line, and one line only, of behavior code to start your object graph ticking. Something like:

$example.start();

This is the end of your procedural code. Everything else is object oriented.

You also offered:

class Example
{
    private $dependency;

    public function __construct()
    {
        $this->setDependency(new Dependency());
    }

    public function setDependency(Dependency $dependency)
    {
        $this->dependency = $dependency;
    }
}

My tests can now use this public method to set the dependency to my mocked value. This seems like the best approach, however I've added this new setDependency method just to make testing easier and that feels a bit dirty.

What makes this dirty is that it forces the class to be mutable (state can change after construction) only for the sake of testing when testing doesn't need it. Testing was perfectly happy with the first example.

But you have something here that you didn't have before. What you have here is a known-good-default-value. It's a royal pain to have to configure everything when there are obvious defaults. Convention over configuration argues that it is better to design a system with a convention of known good defaults that can be overridden by adding configuration code, not simply changing configuration code.

There is a way to give testing, convention, and configuration everything they need, all without forcing the object to be mutable:

class Example
{
    private $dependency;

    public function __construct( Dependency $dependency = new Dependency() )
    {
        $this->dependency = $dependency;
    }
}

This makes use of optional arguments². Now when you want the convention you can use:

$example = new Example();

and it's the same as if you used

$example = new Example( new Dependency() );

yet you are free to write

$example = new Example( new DependencyMock() );

in your tests or use it in your code to configure away from the convention.

Yes, technically the convention is hard coded. But the hard coded value is an overridable default value. That makes a world of difference. If you need to use factory methods this same trick works with them as well.

Lastly you hit us with this:

class Example
{
    protected $dependency;
}

And then you start talking about using reflection in your tests.

What is the right way for my tests to pass a mocked object into my Example class when I'm not using Dependency Injection?

The right way is to rewrite to accept injections. As shown above that doesn't require any fancy tools. You can use reflection to ignore encapsulation protections but it's generally better to parameterize and let the injections come in the front door rather then make them break your windows in the dark of night.

Best Answer

Related Solutions

Unit Testing Integration Tests – Are Integration Tests Meant to be Redundant?

Php – How to pass a mock object into a class for unit tests

Related Topic