Download the PHP package rybakit/phpunit-extras without Composer

PHPUnit Extras

This repository contains functionality that makes it easy to create custom attributes and expectations and use them with the PHPUnit framework. In other words, with this library, your tests may look like this:

Here:

• #[RequiresMySqlServer('^5.6|^8.0')] is a custom requirement.
• #[Sql(...)] is a custom attribute.
• %target_method% is an attribute placeholder.
• expectSelectStatementToBeExecutedOnce() is a custom expectation.

Table of contents

• Installation
• Attributes
  • Requirements
    • Condition
    • Constant
    • Package
  • Placeholders
    • TargetClass
    • TargetMethod
    • TmpDir
  • Creating your own attribute
• Expectations
  • Usage example
  • Advanced example
• Testing
• License

Installation

Depending on which functionality you use, you may also need to install these packages:

To use version-related requirements:

To use the package requirement: Composer 2 is required for the built-in package version lookup used by the package requirement.

To use expression-based requirements and/or expectations:

To install everything in one command, run:

Attributes

PHPUnit supports a variety of attributes, the full list of which can be found in the PHPUnit manual. 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 attributes provided by the library or created by yourself.

Requirements

The library comes with the following requirements:

Condition

Format:

where <condition> is an arbitrary expression that should evaluate to 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:

For a custom requirement, define its attribute and a Requirement that handles that attribute class:

Register the requirement in your test case builder with $builder->addRequirement(new FeatureRequirement()), then use #[RequiresFeature('new-checkout')]. The requirement gets the typed attribute, test target, and placeholder resolver. Return null to run the test; return a message to skip it.

Constant

Format: #[RequiresConstant('<constant-name>')] where <constant-name> is the constant name.

Example:

Package

Format: #[RequiresPackage('<package-name> [<version-constraint>]')] where <package-name> is the required package name and <version-constraint> is a Composer-style version constraint. See the Composer documentation for supported constraint formats.

Example:

Placeholders

Placeholders let you include values that depend on the target test in string arguments to custom attributes. A placeholder is any text surrounded by %. An error is thrown for unknown placeholders.

Below is a list of the placeholders available by default:

TargetClass

Example:

In the example above, %target_class% is replaced with FoobarTest, and %target_class_full% is replaced with App\Tests\FoobarTest.

TargetMethod

Example:

In the example above, %target_method% is replaced with Foobar, and %target_method_full% is replaced with testFoobar.

TmpDir

Example:

In the example above, %tmp_dir% is replaced with the result of the sys_get_temp_dir() call.

Creating your own attribute

As an example, let's implement a #[Sql(...)] attribute. First, create a processor class named SqlProcessor:

The processor declares which attribute class it handles, resolves placeholders in its SQL, and calls PDO::exec(). An attribute such as #[Sql('TRUNCATE TABLE foo')] is equivalent to $this->conn->exec('TRUNCATE TABLE foo').

Next, create the attribute class. Its class is the key the processor registers for:

The processor can use the placeholder resolver it receives to replace %table_name% with a unique table name for a specific test method or class. This lets you use dynamic table names instead of hard-coded ones:

The only thing left is to register our new processor:

After that, all classes that extend App\Tests\TestCase can use #[Sql(...)].

If no processor is registered for an attribute class, the library throws an InvalidAttributeException.

As mentioned earlier, you can also register attributes through PHPUnit extensions. To do this, override the createAttributeProcessorBuilder() method in your AttributeExtension class:

Then register your extension:

To change the default connection settings, pass the new DSN value as a parameter:

For more information on configuring extensions, please refer to the PHPUnit manual.

Expectations

PHPUnit provides several methods for setting expectations about code under test. The most commonly used are the expectException* and expectOutput* methods. This library also lets you create custom expectations.

Usage example

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

To use this expectation, extend PHPUnitExtras\TestCase (recommended) or include the PHPUnitExtras\Expectation\Expectations trait in your test case:

Then use the expectation as shown below:

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

Advanced example

The Symfony ExpressionLanguage component lets you create expectations with more complex verification rules.

As an example, let's implement the expectSelectStatementToBeExecutedOnce() method mentioned above. First, create an expression context that collects 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.