Download the PHP package rybakit/phpunit-extras without Composer

PHPUnit Extras

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:

1. MySqlServer ^5.6|^8.0 is a custom requirement
2. @sql is a custom annotation
3. %target_method% is an annotation placeholder
4. expectSelectStatementToBeExecutedOnce() is a custom expectation.

Table of contents

• Installation
• Annotations
  • Processors
    • Requires
  • Requirements
    • Condition
    • Constant
    • Package
  • Placeholders
    • TargetClass
    • TargetMethod
    • TmpDir
  • Creating your own annotation
• Expectations
  • Usage example
  • Advanced example
• Testing
• License

Installation

In addition, depending on which functionality you will use, you may need to install the following packages:

To use version-related requirements:

To use the "package" requirement:

To use expression-based requirements and/or expectations:

To install everything in one command, run:

Annotations

PHPUnit 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:

Inheriting from the base test case class

Using a trait

Registering an extension

You can then use annotations provided by the library or created by yourself.

Processors

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.

Requires

This processor extends the standard PHPUnit @requires annotation by allowing you to add your own requirements.

Requirements

The library comes with the following requirements:

Condition

Format:

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:

You can also define your own variables in expressions:

Constant

Format:

where <constant-name> is the constant name.

Example:

Package

Format:

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:

Placeholders

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:

TargetClass

Example:

In the above example, %target_class% will be substituted with FoobarTest and %target_class_full% will be substituted with App\Tests\FoobarTest.

TargetMethod

Example:

In the above example, %target_method% will be substituted with Foobar and %target_method_full% will be substituted with testFoobar.

TmpDir

Example:

In the above example, %tmp_dir% will be substituted with the result of the sys_get_temp_dir() call.

Creating your own annotation

As an example, let's implement the annotation @sql from the picture above. To do this, create a processor class with the name SqlProcessor:

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:

The only thing left is to register our new annotation:

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:

After that, register your extension:

To change the default connection settings, pass the new DSN value as an argument:

For more information on configuring extensions, please follow this link.

Expectations

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.

Usage example

As an example, let's create an expectation, which verifies that the code under test creates a file. Let's call it FileCreatedExpectation:

Now, to be able to use this expectation, inherit your test case class from PHPUnitExtras\TestCase (recommended) or include the PHPUnitExtras\Expectation\Expectations trait:

After that, call your expectation as shown below:

For convenience, you can put this statement in a separate method and group your expectations into a trait:

Advanced example

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:

Now create a trait which holds all our statement expectations:

And finally, include that trait in your test case class:

For inspiration and more examples of expectations take a look at the tarantool/phpunit-extras package.

Testing

Before running tests, the development dependencies must be installed:

Then, to run all the tests:

License

The library is released under the MIT License. See the bundled LICENSE file for details.