library tester

nette/tester

Nette Tester: enjoyable unit testing in PHP with code coverage reporter.

, _(*1)

, _(*2)

 , _(*3)

Introduction

Nette Tester is a productive and enjoyable unit testing framework. It's used by the Nette Framework and is capable of testing any PHP code., _(*4)

Documentation is available on the Nette Tester website. Read the blog for new information., _(*5)

 , _(*6)

Support Tester

Do you like Nette Tester? Are you looking forward to the new features?, _(*7)

, _(*8)

Thank you!, _(*9)

 , _(*10)

Installation

The recommended way to install Nette Tester is through Composer:, _(*11)

composer require nette/tester --dev

Alternatively, you can download the tester.phar file., _(*12)

Nette Tester 2.5 is compatible with PHP 8.0 to 8.4. Collecting and processing code coverage information depends on Xdebug or PCOV extension, or PHPDBG SAPI., _(*13)

 , _(*14)

Writing Tests

Imagine that we are testing this simple class:, _(*15)

class Greeting
{
    function say($name)
    {
        if (!$name) {
            throw new InvalidArgumentException('Invalid name.');
        }
        return "Hello $name";
    }
}

So we create test file named greeting.test.phpt:, _(*16)

require 'src/bootstrap.php';

use Tester\Assert;

$h = new Greeting;

// use an assertion function to test say()
Assert::same('Hello John', $h->say('John'));

Thats' all!, _(*17)

Now we run tests from command-line using the tester command:, _(*18)

> tester
 _____ ___  ___ _____ ___  ___
|_   _/ __)( __/_   _/ __)| _ )
  |_| \___ /___) |_| \___ |_|_\  v2.5

PHP 8.2.0 | php -n | 8 threads
.
OK (1 tests, 0 skipped, 0.0 seconds)

Nette Tester prints dot for successful test, F for failed test and S when the test has been skipped., _(*19)

 , _(*20)

Assertions

This table shows all assertions (class Assert means Tester\Assert):, _(*21)

• Assert::same($expected, $actual) - Reports an error if $expected and $actual are not the same.
• Assert::notSame($expected, $actual) - Reports an error if $expected and $actual are the same.
• Assert::equal($expected, $actual) - Like same(), but identity of objects and the order of keys in the arrays are ignored.
• Assert::notEqual($expected, $actual) - Like notSame(), but identity of objects and arrays order are ignored.
• Assert::contains($needle, array $haystack) - Reports an error if $needle is not an element of $haystack.
• Assert::contains($needle, string $haystack) - Reports an error if $needle is not a substring of $haystack.
• Assert::notContains($needle, array $haystack) - Reports an error if $needle is an element of $haystack.
• Assert::notContains($needle, string $haystack) - Reports an error if $needle is a substring of $haystack.
• Assert::true($value) - Reports an error if $value is not true.
• Assert::false($value) - Reports an error if $value is not false.
• Assert::truthy($value) - Reports an error if $value is not truthy.
• Assert::falsey($value) - Reports an error if $value is not falsey.
• Assert::null($value) - Reports an error if $value is not null.
• Assert::nan($value) - Reports an error if $value is not NAN.
• Assert::type($type, $value) - Reports an error if the variable $value is not of PHP or class type $type.
• Assert::exception($closure, $class, $message = null, $code = null) - Checks if the function throws exception.
• Assert::error($closure, $level, $message = null) - Checks if the function $closure throws PHP warning/notice/error.
• Assert::noError($closure) - Checks that the function $closure does not throw PHP warning/notice/error or exception.
• Assert::match($pattern, $value) - Compares result using regular expression or mask.
• Assert::matchFile($file, $value) - Compares result using regular expression or mask sorted in file.
• Assert::count($count, $value) - Reports an error if number of items in $value is not $count.
• Assert::with($objectOrClass, $closure) - Executes function that can access private and protected members of given object via $this.

Testing exceptions:, _(*22)

Assert::exception(function () {
    $h = new Greeting;
    $h->say(null);
}, InvalidArgumentException::class, 'Invalid name.');

Testing PHP errors, warnings or notices:, _(*23)

Assert::error(function () {
    $h = new Greeting;
    echo $h->abc;
}, E_NOTICE, 'Undefined property: Greeting::$abc');

Testing private access methods:, _(*24)

$h = new Greeting;
Assert::with($h, function () {
    // normalize() is internal private method.
    Assert::same('Hello David', $this->normalize('Hello david')); // $this is Greeting
});

 , _(*25)

Tips and features

Running unit tests manually is annoying, so let Nette Tester to watch your folder with code and automatically re-run tests whenever code is changed:, _(*26)

tester -w /my/source/codes

Running tests in parallel is very much faster and Nette Tester uses 8 threads as default. If you wish to run the tests in series use:, _(*27)

tester -j 1

How do you find code that is not yet tested? Use Code-Coverage Analysis. This feature requires you have installed Xdebug or PCOV extension, or you are using PHPDBG SAPI. This will generate nice HTML report in coverage.html., _(*28)

tester . -c php.ini --coverage coverage.html --coverage-src /my/source/codes

We can load Nette Tester using Composer's autoloader. In this case it is important to setup Nette Tester environment:, _(*29)

require 'vendor/autoload.php';

Tester\Environment::setup();

We can also test HTML pages. Let the template engine generate HTML code or download existing page to $html variable. We will check whether the page contains form fields for username and password. The syntax is the same as the CSS selectors:, _(*30)

$dom = Tester\DomQuery::fromHtml($html);

Assert::true($dom->has('input[name="username"]'));
Assert::true($dom->has('input[name="password"]'));

For more inspiration see how Nette Tester tests itself., _(*31)

 , _(*32)

Running tests

The command-line test runner can be invoked through the tester command (or php tester.php). Take a look at the command-line options:, _(*33)

> tester

Usage:
    tester [options] [<test file> | <directory>]...

Options:
    -p <path>                    Specify PHP interpreter to run (default: php).
    -c <path>                    Look for php.ini file (or look in directory) <path>.
    -C                           Use system-wide php.ini.
    -l | --log <path>            Write log to file <path>.
    -d <key=value>...            Define INI entry 'key' with value 'val'.
    -s                           Show information about skipped tests.
    --stop-on-fail               Stop execution upon the first failure.
    -j <num>                     Run <num> jobs in parallel (default: 8).
    -o <console|console-lines|tap|junit|none>
                                 Specify output format.
    -w | --watch <path>          Watch directory.
    -i | --info                  Show tests environment info and exit.
    --setup <path>               Script for runner setup.
    --temp <path>                Path to temporary directory. Default by sys_get_temp_dir().
    --colors [1|0]               Enable or disable colors.
    --coverage <path>            Generate code coverage report to file.
    --coverage-src <path>        Path to source code.
    -h | --help                  This help.