This repository contains functionality that makes it easy to create and integrate your own annotations and expectations into the PHPUnit framework. In other words, with this library, your tests may look like this:
where:
MySqlServer ^5.6|^8.0is a custom requirement@sqlis a custom annotation%target_method%is an annotation placeholderexpectSelectStatementToBeExecutedOnce()is a custom expectation.
composer require --dev rybakit/phpunit-extrasIn addition, depending on which functionality you will use, you may need to install the following packages:
To use version-related requirements:
composer require --dev composer/semverTo use the "package" requirement:
composer require --dev ocramius/package-versionsTo use expression-based requirements and/or expectations:
composer require --dev symfony/expression-languageTo install everything in one command, run:
composer require --dev rybakit/phpunit-extras \
composer/semver \
ocramius/package-versions \
symfony/expression-languagePHPUnit supports a variety of annotations, the full list of which can be found here. With this library, you can easily expand this list by using one of the following options:
use PHPUnitExtras\TestCase;
final class MyTest extends TestCase
{
// ...
}use PHPUnit\Framework\TestCase;
use PHPUnitExtras\Annotation\Annotations;
final class MyTest extends TestCase
{
use Annotations;
protected function setUp() : void
{
$this->processAnnotations(static::class, $this->getName(false) ?? '');
}
// ...
}<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/autoload.php"
>
<!-- ... -->
<extensions>
<extension class="PHPUnitExtras\Annotation\AnnotationExtension" />
</extensions>
</phpunit>You can then use annotations provided by the library or created by yourself.
The annotation processor is a class that implements the behavior of your annotation.
The library is currently shipped with only the "Required" processor. For inspiration and more examples of annotation processors take a look at the tarantool/phpunit-extras package.
This processor extends the standard PHPUnit @requires annotation by allowing you to add your own requirements.
The library comes with the following requirements:
Format:
@requires condition <condition>
where <condition> is an arbitrary expression
that should be evaluated to the Boolean value of true. By default, you can refer to the following superglobal variables
in expressions: cookie, env, get, files, post, request and server.
Example:
/**
* @requires condition server.AWS_ACCESS_KEY_ID
* @requires condition server.AWS_SECRET_ACCESS_KEY
*/
final class AwsS3AdapterTest extends TestCase
{
// ...
}You can also define your own variables in expressions:
use PHPUnitExtras\Annotation\Requirement\ConditionRequirement;
// ...
$context = ['db' => $this->getDbConnection()];
$annotationProcessorBuilder->addRequirement(new ConditionRequirement($context));Format:
@requires constant <constant-name>
where <constant-name> is the constant name.
Example:
/**
* @requires constant Redis::SERIALIZER_MSGPACK
*/
public function testSerializeToMessagePack() : void
{
// ...
}Format:
@requires package <package-name> [<version-constraint>]
where <package-name> is the name of the required package and <version-constraint> is a composer-like version constraint.
For details on supported constraint formats, please refer to the Composer documentation.
Example:
/**
* @requires package symfony/uid ^5.1
*/
public function testUseUuidAsPrimaryKey() : void
{
// ...
}Placeholders allow you to dynamically include specific values in your annotations.
The placeholder is any text surrounded by the symbol %. An annotation can have
any number of placeholders. If the placeholder is unknown, an error will be thrown.
Below is a list of the placeholders available by default:
Example:
namespace App\Tests;
/**
* @example %target_class%
* @example %target_class_full%
*/
final class FoobarTest extends TestCase
{
// ...
}In the above example, %target_class% will be substituted with FoobarTest
and %target_class_full% will be substituted with App\Tests\FoobarTest.
Example:
/**
* @example %target_method%
* @example %target_method_full%
*/
public function testFoobar() : void
{
// ...
}In the above example, %target_method% will be substituted with Foobar
and %target_method_full% will be substituted with testFoobar.
Example:
/**
* @log %tmp_dir%/%target_class%.%target_method%.log testing Foobar
*/
public function testFoobar() : void
{
// ...
}In the above example, %tmp_dir% will be substituted with the result
of the sys_get_temp_dir() call.
As an example, let's implement the annotation @sql from the picture above. To do this, create a processor class
with the name SqlProcessor:
namespace App\Tests\PhpUnit;
use PHPUnitExtras\Annotation\Processor\Processor;
final class SqlProcessor implements Processor
{
private $conn;
public function __construct(\PDO $conn)
{
$this->conn = $conn;
}
public function getName() : string
{
return 'sql';
}
public function process(string $value) : void
{
$this->conn->exec($value);
}
}That's it. All this processor does is register the @sql tag and call PDO::exec(), passing everything
that comes after the tag as an argument. In other words, an annotation such as @sql TRUNCATE TABLE foo
is equivalent to $this->conn->exec('TRUNCATE TABLE foo').
Also, just for the purpose of example, let's create a placeholder resolver that replaces %table_name%
with a unique table name for a specific test method or/and class. That will allow using dynamic table names
instead of hardcoded ones:
namespace App\Tests\PhpUnit;
use PHPUnitExtras\Annotation\PlaceholderResolver\PlaceholderResolver;
use PHPUnitExtras\Annotation\Target;
final class TableNameResolver implements PlaceholderResolver
{
public function getName() : string
{
return 'table_name';
}
/**
* Replaces all occurrences of "%table_name%" with
* "table_<short-class-name>[_<short-method-name>]".
*/
public function resolve(string $value, Target $target) : string
{
$tableName = 'table_'.$target->getClassShortName();
if ($target->isOnMethod()) {
$tableName .= '_'.$target->getMethodShortName();
}
return strtr($value, ['%table_name%' => $tableName]);
}
}The only thing left is to register our new annotation:
namespace App\Tests;
use App\Tests\PhpUnit\SqlProcessor;
use App\Tests\PhpUnit\TableNameResolver;
use PHPUnitExtras\Annotation\AnnotationProcessorBuilder;
use PHPUnitExtras\TestCase as BaseTestCase;
abstract class TestCase extends BaseTestCase
{
protected function createAnnotationProcessorBuilder() : AnnotationProcessorBuilder
{
return parent::createAnnotationProcessorBuilder()
->addProcessor(new SqlProcessor($this->getConnection()))
->addPlaceholderResolver(new TableNameResolver());
}
protected function getConnection() : \PDO
{
// TODO: Implement getConnection() method.
}
}After that all classes inherited from App\Tests\TestCase will be able to use the tag @sql.
Don't worry if you forgot to inherit from the base class where your annotations are registered or if you made a mistake in the annotation name, the library will warn you about an unknown annotation.
As mentioned earlier, another way to register annotations is through PHPUnit extensions.
As in the example above, you need to override the createAnnotationProcessorBuilder() method,
but now for the AnnotationExtension class:
namespace App\Tests\PhpUnit;
use PHPUnitExtras\Annotation\AnnotationExtension as BaseAnnotationExtension;
use PHPUnitExtras\Annotation\AnnotationProcessorBuilder;
class AnnotationExtension extends BaseAnnotationExtension
{
private $dsn;
private $conn;
public function __construct($dsn = 'mysql:host=localhost;dbname=test')
{
$this->dsn = $dsn;
}
protected function createAnnotationProcessorBuilder() : AnnotationProcessorBuilder
{
return parent::createAnnotationProcessorBuilder()
->addProcessor(new SqlProcessor($this->getConnection()))
->addPlaceholderResolver(new TableNameResolver());
}
protected function getConnection() : \PDO
{
return $this->conn ?? $this->conn = new \PDO($this->dsn);
}
}After that, register your extension:
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/autoload.php"
>
<!-- ... -->
<extensions>
<extension class="App\Tests\PhpUnit\AnnotationExtension" />
</extensions>
</phpunit>To change the default connection settings, pass the new DSN value as an argument:
<extension class="App\Tests\PhpUnit\AnnotationExtension">
<arguments>
<string>sqlite::memory:</string>
</arguments>
</extension>For more information on configuring extensions, please follow this link.
PHPUnit has a number of methods to set up expectations for code executed under test. Probably the most commonly used are the expectException* and expectOutput* family of methods. The library provides the possibility to create your own expectations with ease.
As an example, let's create an expectation, which verifies that the code under test creates a file.
Let's call it FileCreatedExpectation:
namespace App\Tests\PhpUnit;
use PHPUnit\Framework\Assert;
use PHPUnitExtras\Expectation\Expectation;
final class FileCreatedExpectation implements Expectation
{
private $filename;
public function __construct(string $filename)
{
Assert::assertFileDoesNotExist($filename);
$this->filename = $filename;
}
public function verify() : void
{
Assert::assertFileExists($this->filename);
}
}Now, to be able to use this expectation, inherit your test case class from PHPUnitExtras\TestCase
(recommended) or include the PHPUnitExtras\Expectation\Expectations trait:
use PHPUnit\Framework\TestCase;
use PHPUnitExtras\Expectation\Expectations;
final class MyTest extends TestCase
{
use Expectations;
protected function tearDown() : void
{
$this->verifyExpectations();
}
// ...
}After that, call your expectation as shown below:
public function testDumpPdfToFile() : void
{
$filename = sprintf('%s/foobar.pdf', sys_get_temp_dir());
$this->expect(new FileCreatedExpectation($filename));
$this->generator->dump($filename);
}For convenience, you can put this statement in a separate method and group your expectations into a trait:
namespace App\Tests\PhpUnit;
use PHPUnitExtras\Expectation\Expectation;
trait FileExpectations
{
public function expectFileToBeCreated(string $filename) : void
{
$this->expect(new FileCreatedExpectation($filename));
}
// ...
abstract protected function expect(Expectation $expectation) : void;
}Thanks to the Symfony ExpressionLanguage component, you can create expectations with more complex verification rules without much hassle.
As an example let's implement the expectSelectStatementToBeExecutedOnce() method from the picture above.
To do this, create an expression context that will be responsible for collecting the necessary statistics
on SELECT statement calls:
namespace App\Tests\PhpUnit;
use PHPUnitExtras\Expectation\ExpressionContext;
final class SelectStatementCountContext implements ExpressionContext
{
private $conn;
private $expression;
private $initialValue;
private $finalValue;
private function __construct(\PDO $conn, string $expression)
{
$this->conn = $conn;
$this->expression = $expression;
$this->initialValue = $this->getValue();
}
public static function exactly(\PDO $conn, int $count) : self
{
return new self($conn, "new_count === old_count $count");
}
public static function atLeast(\PDO $conn, int $count) : self
{
return new self($conn, "new_count >= old_count $count");
}
public static function atMost(\PDO $conn, int $count) : self
{
return new self($conn, "new_count <= old_count $count");
}
public function getExpression() : string
{
return $this->expression;
}
public function getValues() : array
{
if (null === $this->finalValue) {
$this->finalValue = $this->getValue();
}
return [
'old_count' => $this->initialValue,
'new_count' => $this->finalValue,
];
}
private function getValue() : int
{
$stmt = $this->conn->query("SHOW GLOBAL STATUS LIKE 'Com_select'");
$stmt->execute();
return (int) $stmt->fetchColumn(1);
}
}Now create a trait which holds all our statement expectations:
namespace App\Tests\PhpUnit;
use PHPUnitExtras\Expectation\Expectation;
use PHPUnitExtras\Expectation\ExpressionExpectation;
trait SelectStatementExpectations
{
public function expectSelectStatementToBeExecuted(int $count) : void
{
$context = SelectStatementCountContext::exactly($this->getConnection(), $count);
$this->expect(new ExpressionExpectation($context));
}
public function expectSelectStatementToBeExecutedOnce() : void
{
$this->expectSelectStatementToBeExecuted(1);
}
// ...
abstract protected function expect(Expectation $expectation) : void;
abstract protected function getConnection() : \PDO;
}And finally, include that trait in your test case class:
use App\Tests\PhpUnit\SelectStatementExpectations;
use PHPUnitExtras\TestCase;
final class CacheableRepositoryTest extends TestCase
{
use SelectStatementExpectations;
public function testFindByIdCachesResultSet() : void
{
$repository = $this->createRepository();
$this->expectSelectStatementToBeExecutedOnce();
$repository->findById(1);
$repository->findById(1);
}
// ...
protected function getConnection() : \PDO
{
// TODO: Implement getConnection() method.
}
}For inspiration and more examples of expectations take a look at the tarantool/phpunit-extras package.
Before running tests, the development dependencies must be installed:
composer installThen, to run all the tests:
vendor/bin/phpunit
vendor/bin/phpunit -c phpunit-extension.xmlThe library is released under the MIT License. See the bundled LICENSE file for details.