Writing Tests

Each test is an ordinary PHP script. Even it seems common, a big potential is hidden in it. We can step through the test in IDE or load it via web browser.


In the example on guide page we used two assertions: Assert::same() and Assert::exception(). Now we introduce all other types and we explain how to be used. They are methods of the Tester\Assert class but for simplification, we use them further without namespace.

Assert::same($expected, $actual)

$expected must be the same as $actual, or must fulfill expectations. It is the same as PHP operator ===.

Assert::notSame($expected, $actual)

Opposite to Assert::same().

Assert::equal($expected, $actual)

$expected must be equal to $actual. Object identities and array keys order are ignored.

Assert::notEqual($expected, $actual)

Opposite to Assert::equal().

Assert::contains($needle, $actual)

$actual must contain $needle. If $actual is string, it must contain $needle substring. If it is an array, it must contain $needle item.

Assert::notContains($needle, $actual)

Opposite to Assert::contains().


$value must be true, so $value === true.


$value must be truthy, so $value == true.


$value must be false, so $value === false.


$value must be falsey, so $value == false.

Assert::count($count, $value)

$count must be number of elements in $value. Countable is an array or an object implementing Countable.


$value must be null, so $value === null.


$value must be Not a Number.

Assert::type($type, $value)

$value must be of a given type. As $type we can use string:

  • array
  • list – same as the array but keys must start by zero and must be incremented by one
  • bool
  • callable
  • float
  • int or integer
  • null
  • object
  • resource
  • scalar
  • string
  • class name or object directly then must pass $value instanceof $type

Assert::exception($callable, $class, $message = null, $code = null)

On $callable invocation an exception of $class instance must be thrown. If we pass $message, the message of the exception must match (see Assert::match()). And if we pass $code, code of the exception must be the same. For example, this test fails because message of the exception does not match:

Assert::exception(function () {
	throw new App\InvalidValueException('Zero value');
}, App\InvalidValueException::class, 'Value is to low');

The Assert::exception() is unique by returning the thrown exception. So we can test a previous exception:

$e = Assert::exception(function () {
	throw new MyException('Something is wrong', 0, new RuntimeException);
}, MyException::class, 'Something is wrong');

Assert::type(RuntimeException::class, $e->getPrevious());

Assert::error($callable, $type, $message = null)

If we pass a class name as $type, this assertion behaves as absolutely same as Assert::exception().

If $type is one of E_... constants, for example E_WARNING, the $callable must generate this error when invoked. And if we pass $message message of the error must match (see Assert::match()). For example:

Assert::error(function () {
}, E_NOTICE, 'Undefined variable: i');

And the last possibility, if $type is an array the $callable must generate all expected errors. An example shows it best:

Assert::error(function () {
}, [
	[E_NOTICE, 'Undefined variable: a'],
	[E_NOTICE, 'Undefined variable: b'],


Checks that the function $callable does not throw any PHP warning/notice/error or exception. It is useful for testing a piece of code where is no other assertion.

Assert::match($pattern, $actual)

$actual must match to $pattern. We can use two pattern types:

We pass a regular expression as $pattern. To delimit it we must use ~ or #. Other delimiters are not supported. For example test where $var must contain only hexadecimal digits:

Assert::match('#^[0-9a-f]$#i', $var);

The other variant is similar to string comparing but we can use some modifiers in $pattern:

  • %a% one or more of anything except for the end of line characters
  • %a?% zero or more of anything except for the end of line characters
  • %A% one or more of anything including the end of line characters
  • %A?% zero or more of anything including the end of line characters
  • %s% one or more white space characters except for the end of line characters
  • %s?% zero or more white space characters except for the end of line characters
  • %S% one or more of characters except for the white space
  • %S?% zero or more of characters except for the white space
  • %c% a single character of any sort (except for the end of line)
  • %d% one or more digits
  • %d?% zero or more digits
  • %i% signed integer value
  • %f% floating point number
  • %h% one or more HEX digits
  • %w% one or more alphanumeric characters
  • %% one % character


# Again, hexadecimal number test
Assert::match('%h%', $var);

# Generalized path to file and line number
Assert::match('Error in file %a% on line %i%', $errorMessage);

Assert::matchFile($file, $actual)

The assertion is identical to Assert::match() but the pattern is loaded from $file. It is useful for very long strings testing. Test file stands readable.

Assert::fail($message, $actual = null, $expected = null)

This assertion always fails. It is just handy. We can optionally pass expected and actual values.


When comparing more complex structures, the assertions above may not be sufficient when some structure items are of random nature. For example some hashes or timestamps. In that case we can use Tester\Expect objects inside $expected parameter of Assert::equal() and Assert::notEqual() methods as following.

Let's suppose that we test a method that creates a new user and returns its attributes as an array.

use Tester\Expect;

	'id' => 123,
	'username' => 'milo',
	'password' => Expect::match('%h%'),  # random string, hash, but must match some pattern
	'created_at' => Expect::type(DateTimeImmutable::class),  # check type only, not exact value
], User::create(123, 'milo', 'RandomPaSsWoRd'));

With Expect, we can make almost the same assertions as with Assert. So Expect::same(), Expect::match(), Expect::count() and so on are available. Moreover, we can chain them like:

Expect::type(MyIterator::class)->andCount(5);  # item is the MyIterator object and its count is 5

Or, we can write own assertion callbacks.

Expect::that(function ($value) {
	# return false if expectation fails

Failed assertions investigation

The Tester shows where the error is when an assertion fails. When we compare complex structures, the Tester creates dumps of compared values and saves them into directory output. For example when imaginary test Arrays.recursive.phpt fails the dumps will be saved as follows:

└── tests/
    ├── output/
    │   ├── Arrays.recursive.actual    # actual value
    │   └── Arrays.recursive.expected  # expected value
    └── Arrays.recursive.phpt          # failing test

We can change the name of the directory by Tester\Dumper::$dumpDir.

Skipping tests

Some tests can run only under certain circumstances. If these circumstances aren't met, we can skip the tests. For example, required OS type:

	Tester\Environment::skip('Requires UNIX.');

Test will be stopped and marked as s – skipped. Later we find out how to skip the test using the @skip annotation.


Assertions may follow one by one in simple tests. But sometimes it is useful to enclose the assertions to test class and structure them in this way. The class must be descendant of Tester\TestCase and we talk about it simply as about testcase.

use Tester\Assert;

class GreetingTest extends Tester\TestCase
	public function testOne()

	public function testTwo()

# Run testing methods
(new GreetingTest)->run();

We can enrich a testcase by setUp() and tearDown() methods. They are called before/after every testing method:

use Tester\Assert;

class NextTest extends Tester\TestCase
	public function setUp()
		# Preparation

	public function tearDown()
		# Clean-up

	public function testOne()

	public function testTwo()

# Run testing methods
(new NextTest)->run();

Method calls order


If error occurs in a setUp() or tearDown() phase, test will fail. If error occurs in the testing method, the tearDown() method is called anyway, but with suppressed errors in it.

Annotations for TestCase

There are a few annotations available to help us with testing methods. We write them toward the testing method.


It is equal usage of Assert::exception() inside a testing method. But notation is more readable:

 * @throws RuntimeException
public function testOne()

 * @throws LogicException  Wrong argument order
public function testTwo()


This annotation suits when we want to run the testing method multiple times but with different arguments. As an argument we write method name which returns parameters for the testing method. The method must return an array or Traversable. Simple example:

public function getLoopArgs()
	return [
		[1, 2, 3],
		[4, 5, 6],
		[7, 8, 9],

 * @dataProvider getLoopArgs
public function testLoop($a, $b, $c)

The other annotation @dataProvider variation accepts a path to INI file (relatively to test file) as an argument. The method is called so many times as the number of sections contained in INI file. File loop-args.ini:




and the method which uses the INI file:

 * @dataProvider loop-args.ini
public function testLoop($a, $b, $c)

Similarly, we can pass path to a PHP script instead of INI. It must return array or Traversable. File loop-args.php:

 return [
	['a' => 1, 'b' => 2, 'c' => 3],
	['a' => 4, 'b' => 5, 'c' => 6],
	['a' => 7, 'b' => 8, 'c' => 9],

Test file annotations

Following annotations are evaluated only if we run the test by the Tester, not manually as ordinary PHP script.

We write annotations at the beginning of the test file and the typing is case-insensitive. Imaginary example:

 * TEST: Basic database query test.
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 5.5

require __DIR__ . '/../bootstrap.php';


It is not an annotation actually. It only sets the test title which is printed on fail or into logs.


Test is skipped. It is handy for temporary test deactivation.


Test is skipped if is not run by the corresponding PHP version. We write annotation as @phpVersion [operator] version. We can leave out the operator, default is >=. Examples:

 * @phpVersion 5.3.3
 * @phpVersion < 5.5
 * @phpVersion != 5.4.5


Test is skipped if all mentioned PHP extension are not loaded. Multiple extensions can be written in a single annotation, or we can use the annotation multiple times.

 * @phpExtension pdo, pdo_pgsql, pdo_mysql
 * @phpExtension json


We write annotation as @dataProvider file.ini. INI file path is relative to the test file. Test runs as many times as number of sections contained in the INI file. Let's assume the INI file databases.ini:

dsn = "mysql:host="
user = root
password = ******

dsn = "pgsql:host=;dbname=test"
user = postgres
password = ******

dsn = "sqlite::memory:"

and the file database.phpt in the same directory:

 * @dataProvider databases.ini

$args = Tester\Environment::loadData();

The test runs three times and $args will contain values from sections mysql, postgresql or sqlite.

There is one more variation when we write annotations with a question mark as @dataProvider? file.ini. In this case, test is skipped if the INI file doesn't exist.

Annotation possibilities have not been mentioned all yet. We can write conditions after the INI file. Test runs for the given section only if all conditions match. Let's extend the INI file:

dsn = "mysql:host="
user = root
password = ******

[postgresql 8.4]
dsn = "pgsql:host=;dbname=test"
user = postgres
password = ******

[postgresql 9.1]
dsn = "pgsql:host=;dbname=test;port=5433"
user = postgres
password = ******

dsn = "sqlite::memory:"

and we will use annotation with condition:

 * @dataProvider  databases.ini  postgresql, >=9.0

The test runs only once for section postgresql 9.1. Other sections don’t match the conditions.

Similarly, we can pass path to a PHP script instead of INI. It must return array or Traversable. File databases.php:

return [
	'postgresql 8.4' => [
		'dsn' => '...',
		'user' => '...',

	'postgresql 9.1' => [
		'dsn' => '...',
		'user' => '...',


We write it as @multiple N where N is an integer. Test runs exactly N-times.


Annotation has no parameters. We use it when we write a test as Tester\TestCase classes. In this case, the test runs as many times as the number of testing methods. Every testing method runs in a separated process. It can dramatically speed up the whole testing procedure. We recommend usage of this annotation.


We write it as @exitCode N where N is the exit code of the test. For example if exit(10) is called in the test, we write annotation as @exitCode 10. It is considered to fail if the test ends with a different code. Exit code 0 (zero) is verified if we leave out the annotation


Annotation is evaluated only if PHP binary is CGI. It is ignored otherwise. We write it as @httpCode NNN where NNN is expected HTTP code. HTTP code 200 is verified if we leave out the annotation. If we write NNN as a string evaluated as zero, for example any, HTTP code is not checked at all.

@outputMatch a @outputMatchFile

The behavior of annotations is consistent with Assert::match() and Assert::matchFile() assertions. But pattern is found in test’s standard output. A suitable use case is when we assume the test to end by fatal error and we need to verify its output.


It sets INI configuration values for test. For example we write it as @phpIni precision=20 and it works in the same way as if we passed value from the command line by parameter -d precision=20.



Tester\DomQuery class helps to test HTML or XML content. Description of all the methods is in API documentation. Here, we show basic usage:

# HTML which we want to test
$html = $template->render();

# We create DOM structure from HTML
$dom = Tester\DomQuery::fromHtml($html);

# We can test

We use CSS selector as DomQuery::has($selector) parameter.


Tester\FileMock emulates files in memory and helps you to test a code which uses functions like fopen(), file_get_contents() or parse_ini_file(). For example:

# Tested class
class Logger
	private $logFile;

	public function __construct($logFile)
		$this->logFile = $logFile;

	public function log($message)
		file_put_contents($this->logFile, $message . "\n", FILE_APPEND);

# New empty file
$file = Tester\FileMock::create('');

$logger = new Logger($file);

# Created content testing
Assert::same("Login\nLogout\n", file_get_contents($file));


Class Tester\Helpers offers method purge() which creates passed directory but only if doesn't exist yet. If so, it purges all its content. It is handy for temporary directory creation. For example in tests/bootstrap.php:

@mkdir(__DIR__ . '/tmp');  # @ - directory may already exist

define('TEMP_DIR', __DIR__ . '/tmp/' . getmypid());


Later we learn that tests run in parallel. Sometimes we need not to overlap the test running. Typically database tests need to prepare database content and they need nothing disturbs them during running time of the test. In these cases we use Tester\Environment::lock($name, $dir):

Tester\Environment::lock('database', __DIR__ . '/tmp');

The first argument is a lock name. The second one is a path to directory for saving the lock. The test which acquires the lock first runs. Other tests must wait till it is completed.


Classes or methods marked as final are hard to test. Calling the Tester\Environment::bypassFinals() in a test beginning causes that keywords final are removed during the code loading.

require __DIR__ . '/bootstrap.php';


class MyClass extends NormallyFinalClass  # <-- NormallyFinalClass is not final anymore


  • improves error dump readability (coloring included), otherwise, default PHP stack trace is printed
  • enables check that assertions have been called in test, otherwise, tests without (e.g. forgotten) assertions pass too
  • automatically starts code coverage collector when --coverage is used (described later)

Using is optional but recommended.


It could be useful to know if a test is running by the Tester or manually as an ordinary PHP script.

if (getenv(Tester\Environment::RUNNER)) {
	# run by Tester
} else {
	# another way


Tester runs tests in parallel in a given number of threads. We will find a thread number in an environmental variable when we are interested:

echo "I'm running in a thread number " . getenv(Tester\Environment::THREAD).


  • It is not good practice to use exit() and die() to end test with a fail message. For example exit('Error in connection') ends a test with exit code 0 (zero) and it means success. Always use echo 'Error in connection' followed by exit(1).
  • Choose the most accurate assertions. For example Assert::same($a, $b), not Assert::true($a === $b). Only in the first case we get meaningful error message. In the other case we get false should be true only and it says nothing about $a and $b variables contents.
  • Use the Assert::nan() for NAN (Not a Value) testing. NAN value is very specific and assertions Assert::same() or Assert::equal() can behave unpredictably.

API documentation

Generated API documentation is here.

Related blog posts