4. Fixtures

    In Testing array operations with PHPUnit, the fixture was the array that is stored in the variable. Most of the time, though, the fixture will be more complex than a simple array, and the amount of code needed to set it up will grow accordingly. The actual content of the test gets lost in the noise of setting up the fixture. This problem gets even worse when you write several tests with similar fixtures. Without some help from the testing framework, we would have to duplicate the code that sets up the fixture for each test we write.

    PHPUnit supports sharing the setup code. Before a test method is run, a template method called setUp() is invoked. setUp() is where you create the objects against which you will test. Once the test method has finished running, whether it succeeded or failed, another template method called tearDown() is invoked. tearDown() is where you clean up the objects against which you tested.

    In we used the producer-consumer relationship between tests to share a fixture. This is not always desired or even possible. Example 4.1 shows how we can write the tests of the StackTest in such a way that not the fixture itself is reused but the code that creates it. First we declare the instance variable, $stack, that we are going to use instead of a method-local variable. Then we put the creation of the array fixture into the setUp() method. Finally, we remove the redundant code from the test methods and use the newly introduced instance variable, $this->stack, instead of the method-local variable $stack with the assertSame() assertion method.

    Example 4.1 Using setUp() to create the stack fixture

    The setUp() and tearDown() template methods are run once for each test method (and on fresh instances) of the test case class.

    In addition, the setUpBeforeClass() and tearDownAfterClass() template methods are called before the first test of the test case class is run and after the last test of the test case class is run, respectively.

    The example below shows all template methods that are available in a test case class.

    Example 4.2 Example showing all template methods available

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class TemplateMethodsTest extends TestCase
    5. {
    6.     public static function setUpBeforeClass(): void
    7.     {
    8.         fwrite(STDOUT, __METHOD__ . "\n");
    9.     }
    11.     protected function setUp(): void
    12.     {
    13.         fwrite(STDOUT, __METHOD__ . "\n");
    14.     }
    16.     protected function assertPreConditions(): void
    17.     {
    18.         fwrite(STDOUT, __METHOD__ . "\n");
    19.     }
    21.     public function testOne(): void
    22.     {
    23.         fwrite(STDOUT, __METHOD__ . "\n");
    24.         $this->assertTrue(true);
    26.     public function testTwo(): void
    27.     {
    28.         fwrite(STDOUT, __METHOD__ . "\n");
    29.         $this->assertTrue(false);
    30.     }
    32.     protected function assertPostConditions(): void
    33.     {
    34.         fwrite(STDOUT, __METHOD__ . "\n");
    35.     }
    37.     protected function tearDown(): void
    38.     {
    39.         fwrite(STDOUT, __METHOD__ . "\n");
    40.     }
    42.     public static function tearDownAfterClass(): void
    43.     {
    44.         fwrite(STDOUT, __METHOD__ . "\n");
    45.     }
    47.     protected function onNotSuccessfulTest(Throwable $t): void
    48.     {
    49.         fwrite(STDOUT, __METHOD__ . "\n");
    50.         throw $t;
    51.     }
    52. }

    setUp() and tearDown() are nicely symmetrical in theory, but not in practice. In practice, you only need to implement tearDown() if you have allocated external resources such as files or sockets in setUp(). If your setUp() just creates plain PHP objects, you can generally ignore tearDown().

    However, if you create many objects in your setUp(), you may want to unset() the variables holding those objects in your tearDown() so that they can be garbage collected sooner. Objects created within setUp() (or test methods) that are stored in properties of the test object are only automatically garbage collected at the end of the PHP process that runs PHPUnit.

    What happens when you have two tests with slightly different setups? There are two possibilities:

    • If you really have a different setUp(), you need a different test case class. Name the class after the difference in the setup.

    A good example of a fixture that makes sense to share across several tests is a database connection: you log into the database once and reuse the database connection instead of creating a new connection for each test. This makes your tests run faster.

    Example 4.3 uses the setUpBeforeClass() and tearDownAfterClass() template methods to connect to the database before the test case class’ first test and to disconnect from the database after the last test of the test case, respectively.

    Example 4.3 Sharing fixture between the tests of a test suite

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DatabaseTest extends TestCase
    5. {
    6.     private static $dbh;
    8.     public static function setUpBeforeClass(): void
    9.     {
    10.         self::$dbh = new PDO('sqlite::memory:');
    13.     public static function tearDownAfterClass(): void
    14.     {
    15.         self::$dbh = null;
    16.     }
    17. }

    It cannot be emphasized enough that sharing fixtures between tests reduces the value of the tests. The underlying design problem is that objects are not loosely coupled. You will achieve better results solving the underlying design problem and then writing tests using stubs (see ), than by creating dependencies between tests at runtime and ignoring the opportunity to improve your design.

    The same is true for code that uses global variables. Typically, the code you want to test is coupled strongly with a global variable and you cannot control its creation. An additional problem is the fact that one test’s change to a global variable might break another test.

    In PHP, global variables work like this:

    • A global variable $foo = 'bar'; is stored as $GLOBALS['foo'] = 'bar';.

    • The $GLOBALS variable is a so-called super-global variable.

    • Super-global variables are built-in variables that are always available in all scopes.

    • In the scope of a function or method, you may access the global variable $foo by either directly accessing $GLOBALS['foo'] or by using global $foo; to create a local variable with a reference to the global variable.

    Besides global variables, static attributes of classes are also part of the global state.

    Prior to version 6, by default, PHPUnit ran your tests in a way where changes to global and super-global variables ($GLOBALS, $_ENV, $_POST, $_GET, $_COOKIE, $_SERVER, $_FILES, $_REQUEST) do not affect other tests.

    As of version 6, PHPUnit does not perform this backup and restore operation for global and super-global variables by default anymore. It can be activated by using the --globals-backup option or setting backupGlobals="true" in the XML configuration file.

    Note

    The backup and restore operations for global variables and static class attributes use serialize() and unserialize().

    Objects of some classes (e.g., PDO) cannot be serialized and the backup operation will break when such an object is stored e.g. in the $GLOBALS array.

    The @backupGlobals annotation that is discussed in @backupGlobals can be used to control the backup and restore operations for global variables. Alternatively, you can provide a list of global variables that are to be excluded from the backup and restore operations like this

    Note

    Setting the $backupGlobalsExcludeList property inside e.g. the setUp() method has no effect.

    The @backupStaticAttributes annotation discussed in can be used to back up all static property values in all declared classes before each test and restore them afterwards.

    It processes all classes that are declared at the time a test starts, not only the test class itself. It only applies to static class properties, not static variables within functions.

    Note

    The @backupStaticAttributes operation is executed before a test method, but only if it is enabled. If a static value was changed by a previously executed test that did not have @backupStaticAttributes enabled, then that value will be backed up and restored — not the originally declared default value. PHP does not record the originally declared default value of any static variable.

    The same applies to static properties of classes that were newly loaded/declared within a test. They cannot be reset to their originally declared default value after the test, since that value is unknown. Whichever value is set will leak into subsequent tests.

    For unit tests, it is recommended to explicitly reset the values of static properties under test in your setUp() code instead (and ideally also tearDown(), so as to not affect subsequently executed tests).

    You can provide a list of static attributes that are to be excluded from the backup and restore operations:

    1. final class MyTest extends TestCase
    2. {
    3.     protected $backupStaticAttributesExcludeList = [
    4.         'className' => ['attributeName']
    5.     ];
    7. }

    Setting the $backupStaticAttributesExcludeList property inside e.g. the setUp() method has no effect.