7. Incomplete and Skipped Tests

    to keep track of the tests that you have to write. The problem with empty test methods is that they are interpreted as a success by the PHPUnit framework. This misinterpretation leads to the test reports being useless – you cannot see whether a test is actually successful or just not yet implemented. Calling in the unimplemented test method does not help either, since then the test will be interpreted as a failure. This would be just as wrong as interpreting an unimplemented test as a success.

    If we think of a successful test as a green light and a test failure as a red light, we need an additional yellow light to mark a test as being incomplete or not yet implemented. PHPUnit\Framework\IncompleteTest is a marker interface for marking an exception that is raised by a test method as the result of the test being incomplete or currently not implemented. PHPUnit\Framework\IncompleteTestError is the standard implementation of this interface.

    shows a test case class, SampleTest, that contains one test method, testSomething(). By calling the convenience method markTestIncomplete() (which automatically raises an PHPUnit\Framework\IncompleteTestError exception) in the test method, we mark the test as being incomplete.

    Example 7.1 Marking a test as incomplete

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class SampleTest extends TestCase
    5. {
    6.     public function testSomething(): void
    7.     {
    8.         // Optional: Test anything here, if you want.
    9.         $this->assertTrue(true, 'This should already work.');
    11.         // Stop here and mark this test as incomplete.
    12.         $this->markTestIncomplete(
    13.           'This test has not been implemented yet.'
    14.         );
    15.     }

    An incomplete test is denoted by an I in the output of the PHPUnit command-line test runner, as shown in the following example:

    Table 7.1 shows the API for marking tests as incomplete.

    Not all tests can be run in every environment. Consider, for instance, a database abstraction layer that has several drivers for the different database systems it supports. The tests for the MySQL driver can only be run if a MySQL server is available.

    Example 7.2 shows a test case class, DatabaseTest, that contains one test method, testConnection(). In the test case class’ setUp() template method we check whether the MySQLi extension is available and use the method to skip the test if it is not.

    Example 7.2 Skipping a test

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. final class DatabaseTest extends TestCase
    5. {
    6.     protected function setUp(): void
    7.     {
    8.         if (!extension_loaded('mysqli')) {
    9.             $this->markTestSkipped(
    10.               'The MySQLi extension is not available.'
    11.             );
    12.         }
    13.     }
    15.     public function testConnection(): void
    16.     {
    17.         // ...
    18.     }

    A test that has been skipped is denoted by an S in the output of the PHPUnit command-line test runner, as shown in the following example:

    shows the API for skipping tests.

    In addition to the above methods it is also possible to use the @requires annotation to express common preconditions for a test case.

    A test can have multiple @requires annotations, in which case all requirements need to be met for the test to run.

    The following operators are supported for PHP, PHPUnit, and extension version constraints: <, <=, >, >=, =, ==, !=, <>.

    Versions are compared using PHP’s function. Among other things, this means that the = and == operator can only be used with complete X.Y.Z version numbers and that just X.Y will not work.

    Example 7.3 Skipping test cases using @requires

    1. <?php declare(strict_types=1);
    2. use PHPUnit\Framework\TestCase;
    4. /**
    5.  * @requires extension mysqli
    6.  */
    7. final class DatabaseTest extends TestCase
    8. {
    9.     /**
    10.      * @requires PHP >= 5.3
    11.      */
    12.     public function testConnection(): void
    13.     {
    14.         // Test requires the mysqli extension and PHP >= 5.3
    15.     }
    18. }