PHPUnit Manual

You can use the @assert annotation in the documentation block of a method to automatically generate simple, yet meaningful tests instead of incomplete test cases when using the Skeleton Generator (see Chapter 16):

/**
 * @assert (0, 0) == 0
 */
public function add($a, $b)
{
    return $a + $b;
}

These annotations are transformed into test code such as

/**
 * Generated from @assert (0, 0) == 0.
 */
public function testAdd() {
    $o = new Calculator;
    $this->assertEquals(0, $o->add(0, 0));
}

The @author annotation is an alias for the @group annotation (see the section called “@group”) and allows to filter tests based on their authors.

The backup and restore operations for global variables can be completely disabled for all tests of a test case class like this

/**
 * @backupGlobals disabled
 */
class MyTest extends PHPUnit_Framework_TestCase
{
    // ...
}

The @backupGlobals annotation can also be used on the test method level. This allows for a fine-grained configuration of the backup and restore operations:

/**
 * @backupGlobals disabled
 */
class MyTest extends PHPUnit_Framework_TestCase
{
    /**
     * @backupGlobals enabled
     */
    public function testThatInteractsWithGlobalVariables()
    {
        // ...
    }
}

The backup and restore operations for static attributes of classes can be completely disabled for all tests of a test case class like this

/**
 * @backupStaticAttributes disabled
 */
class MyTest extends PHPUnit_Framework_TestCase
{
    // ...
}

The @backupStaticAttributes annotation can also be used on the test method level. This allows for a fine-grained configuration of the backup and restore operations:

/**
 * @backupStaticAttributes disabled
 */
class MyTest extends PHPUnit_Framework_TestCase
{
    /**
     * @backupStaticAttributes enabled
     */
    public function testThatInteractsWithStaticAttributes()
    {
        // ...
    }
}

The @codeCoverageIgnore, @codeCoverageIgnoreStart and @codeCoverageIgnoreEnd annotations can be used to exclude lines of code from the coverage analysis.

For usage see the section called “Ignoring Code Blocks”.

The @covers annotation can be used in the test code to specify which method(s) a test method wants to test:

/**
 * @covers BankAccount::getBalance
 */
public function testBalanceIsInitiallyZero()
{
    $this->assertEquals(0, $this->ba->getBalance());
}

If provided, only the code coverage information for the specified method(s) will be considered.

Table B.1 shows the syntax of the @covers annotation.

A test method can accept arbitrary arguments. These arguments are to be provided by a data provider method (provider() in Example 4.4). The data provider method to be used is specified using the @dataProvider annotation.

See the section called “Data Providers” for more details.

PHPUnit supports the declaration of explicit dependencies between test methods. Such dependencies do not define the order in which the test methods are to be executed but they allow the returning of an instance of the test fixture by a producer and passing it to the dependent consumers. Example 4.2 shows how to use the @depends annotation to express dependencies between test methods.

See the section called “Test Dependencies” for more details.

Example 4.7 shows how to use the @expectedException annotation to test whether an exception is thrown inside the tested code.

See the section called “Testing Exceptions” for more details.

The @expectedExceptionCode annotation, in conjunction with the @expectedException allows making assertions on the error code of a thrown exception thus being able to narrow down a specific exception.

class MyTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException     MyException
     * @expectedExceptionCode 20
     */
    public function testExceptionHasErrorcode20()
    {
        throw new MyException('Some Message', 20);
    }
}

The @expectedExceptionMessage annotation works similar to @expectedExceptionCode as it lets you make an assertion on the error message of an exception.

class MyTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException        MyException
     * @expectedExceptionMessage Some Message
     */
    public function testExceptionHasRightMessage()
    {
        throw new MyException('Some Message', 20);
    }
}

The expected message can be a substring of the exception Message. This can be useful to only assert that a certain name or parameter that was passed in shows up in the exception and not fixate the whole exception message in the test.

class MyTest extends PHPUnit_Framework_TestCase
{
     /**
      * @expectedException        MyException
      * @expectedExceptionMessage broken
      */
     public function testExceptionHasRightMessage()
     {
         $param = "broken";
         throw new MyException('Invalid parameter "'.$param.'".', 20);
     }
}

A test can be tagged as belonging to one or more groups using the @group annotation like this

class MyTest extends PHPUnit_Framework_TestCase
{
    /**
     * @group specification
     */
    public function testSomething()
    {
    }

    /**
     * @group regression
     * @group bug2204
     */
    public function testSomethingElse()
    {
    }
}

Tests can be selected for execution based on groups using the --group and --exclude-group switches of the command-line test runner or using the respective directives of the XML configuration file.

The @outputBuffering annotation can be used to control PHP's output buffering like this

/**
 * @outputBuffering enabled
 */
class MyTest extends PHPUnit_Framework_TestCase
{
    // ...
}

The @outputBuffering annotation can also be used on the test method level. This allows for fine-grained control over the output buffering:

/**
 * @outputBuffering disabled
 */
class MyTest extends PHPUnit_Framework_TestCase
{
    /**
     * @outputBuffering enabled
     */
    public function testThatPrintsSomething()
    {
        // ...
    }
}

As an alternative to prefixing your test method names with test, you can use the @test annotation in a method's docblock to mark it as a test method.

/**
 * @test
 */
public function initialBalanceShouldBe0()
{
    $this->assertEquals(0, $this->ba->getBalance());
}