phpunit-arrange

When to use it?

• You want to reduce your messy "setUp" methods that init objects for ALL tests. But most of the time, they are not required all together.
• You want to have explicit setup/arrange for each tests... Or reuse them!
• You want to have tests easy to read
• You want to put forward real important setup/expectations/fixtures and put the rest as annotations

It's time to refactor your ugly "setUp"!

Compatibility

• PHP: Compatible with PHP 5.3 to the last version (7.1) and HHVM
• PHPUnit: Compatible with version 3., 4., 5.*

See build here. Some builds fail because some version of PHPUnit are not compatible with some PHP versions.

Installation

Composer

Simply add this to your composer.json file:

"require": {
    "nikoms/phpunit-arrange": "dev-master"
}

Then run php composer.phar install

PhpUnit configuration

To activate the plugin. Add the listener to your phpunit.xml(.dist) file:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit>
    ...
    <listeners>
        <listener class="Nikoms\PhpUnit\Listener\ArrangeListener" file="vendor/nikoms/phpunit-arrange/src/ArrangeListener.php" />
    </listeners>
</phpunit>

Usage

"Use" the plugin on the top of your test:

use Nikoms\PhpUnit\Annotation\Arrange;

And then, let the magic begin...

Call an arrange method without argument

It's possible to easily call a custom "setUp" method before the test.

use Nikoms\PhpUnit\Annotation\Arrange;

class ExampleTest extends \PHPUnit_Framework_TestCase
{

    public function initConnectedUser()
    {
        $this->user = new User();
        $this->user->isConnected = true;
    }

    /**
     * @Arrange("initConnectedUser")
     */
    public function testSomething()
    {
        $this->assertSame('Nicolas', $this->user->name);
        // Do something with your $this->user..
    }
}

Call an arrange method with an argument

It's possible to give an argument to the arrange method. It works with a string, an array, a constant, etc...

use Nikoms\PhpUnit\Annotation\Arrange;

class ExampleTest extends \PHPUnit_Framework_TestCase
{
    /**
     * @param string $name
     * @return User
     */
    public function iAmConnectedWithTheName($name)
    {
        $this->user = new User();
        $this->user->isConnected = true;
        $this->user->name = $name;
    }

    /**
     * @Arrange(iAmConnectedWithTheName="Nicolas")
     */
    public function testSomething()
    {
        $this->assertSame('Nicolas', $this->user->name);
        // Do something with your $this->user..
    }
}

Get something from the arrange method

If the arrange method returns something, then it is put as argument in the test method

use Nikoms\PhpUnit\Annotation\Arrange;

class ExampleTest extends \PHPUnit_Framework_TestCase
{
    /**
     * @param string $name
     * @return User
     */
    public function iAmConnectedWithTheName($name)
    {
        $user = new User();
        $user->isConnected = true;
        $user->name = $name;

        return $user;
    }

    /**
     * @Arrange(iAmConnectedWithTheName="Nicolas")
     */
    public function testSomething(User $user)
    {
        $this->assertSame('Nicolas', $user->name);
        // Do something with your user..
    }
}

Chain calls of arrange methods

If the arrange method returns something, then it is put as argument in the test method

use Nikoms\PhpUnit\Annotation\Arrange;

class ExampleTest extends \PHPUnit_Framework_TestCase
{
    /**
     * @param string $name
     * @return User
     */
    public function iAmConnectedWithTheName($name)
    {
        $user = new User();
        $user->isConnected = true;
        $user->name = $name;

        return $user;
    }

    /**
     * @param User $user
     * @param string $group
     * @return User
     */
    public function memberOfGroup($user, $group)
    {
        $user->group = $group;

        return $user;
    }

    /**
     * @Arrange(iAmConnectedWithTheName="Nicolas", memberOfGroup=User::GROUP_ADMIN)
     * @param User $user
     */
    public function testSomething(User $user)
    {
        $this->assertSame(User::GROUP_ADMIN, $user->group);
        $this->assertSame('Nicolas', $user->name);
        // Do something with your user..
    }
}

Use as many @Arrange as you want

Of course, it's possible to have multiple arrange for the same test method

use Nikoms\PhpUnit\Annotation\Arrange;

class ExampleTest extends \PHPUnit_Framework_TestCase
{
    /**
     * @param string $name
     * @return User
     */
    public function iAmConnectedWithTheName($name)
    {
        $user = new User();
        $user->isConnected = true;
        $user->name = $name;

        return $user;
    }
    /**
     * @Arrange(iAmConnectedWithTheName="Nicolas")
     * @Arrange(iAmConnectedWithTheName="Laura")
     * @param User $user
     */
    public function testSomething(User $nicolas, User $laura)
    {
        $this->assertSame('Nicolas', $nicolas->name);
        $this->assertSame('Laura', $laura->name);
        // Do something with your user..
    }
}

Combine it with @dataProvider

@dataProvider can be used to fill arrange methods.

use Nikoms\PhpUnit\Annotation\Arrange;

class ExampleTest extends \PHPUnit_Framework_TestCase
{

    /**
     * @return array
     */
    public function provideNames()
    {
        return array(
            array('Nicolas'),
            array('Laura'),
        );
    }

    /**
     * @param string $name
     * @return User
     */
    public function iAmConnectedWithTheName($name)
    {
        $user = new User();
        $user->isConnected = true;
        $user->name = $name;

        return $user;
    }

    /**
     * @dataProvider provideNames
     * @Arrange("iAmConnectedWithTheName")
     *
     * @param string $dataProviderValue
     * @param User $user
     */
    public function testSomething($dataProviderValue, User $user)
    {
        // The user has the name given by the "@dataProvider":
        // First "Nicolas", then "Laura".
        $this->assertSame($dataProviderValue, $user->name);

        // Do something with your user..
    }
}

Why calling it arrange?

Because it's the name of a step in tests as explained here.

Follow the "3-As" pattern for test methods: Arrange, Act, Assert. Specifically, use separate code paragraphs (groups of lines of code separated by a blank line) for each of the As.

• Arrange is variable declaration and initialization.
• Act is invoking the code under test.
• Assert is using the Assert.* methods to verify that expectations were met. Following this pattern consistently makes it easy to revisit test code.

TO DO

• Refac a little
• Make an HTML testdox to have a nice BDD style output
• Unit test Listener & printer... Even if it's already tested with the tests/ExampleTest.php
• Add the possibility to add "ignoredAnnotationNames" in annotationReaderFactory