GitHub - Nikoms/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