Awesome Open Source
Awesome Open Source

Nette Tester: enjoyable unit testing

Downloads this Month Tests Build Status Windows Latest Stable Version License

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.

Documentation is available on the Nette Tester website. Read the blog for new information.

Support Tester

Do you like Nette Tester? Are you looking forward to the new features?

Buy me a coffee

Thank you!

Installation

The recommended way to install Nette Tester is through Composer:

composer require nette/tester --dev

Alternatively, you can download the tester.phar file.

  • Nette Tester 2.4 is compatible with PHP 7.2 to 8.1
  • Nette Tester 2.3 is compatible with PHP 7.1 to 8.0
  • Nette Tester 2.1 & 2.2 is compatible with PHP 7.1 to 7.3
  • Nette Tester 2.0 is compatible with PHP 5.6 to 7.3

Collecting and processing code coverage information depends on Xdebug or PCOV extension, or PHPDBG SAPI.

Writing Tests

Imagine that we are testing this simple class:

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

So we create test file named greeting.test.phpt:

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!

Now we run tests from command-line using the tester command:

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

PHP 7.3.3 | 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.

Assertions

This table shows all assertions (class Assert means Tester\Assert):

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

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

Testing PHP errors, warnings or notices:

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

Testing private access methods:

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

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:

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:

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.

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:

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:

$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.

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:

> 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|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.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Php (402,705) 
Unit Testing (1,682) 
Phpunit (561) 
Assertions (511) 
Nette (341) 
Code Coverage (206) 
Xdebug (176) 
Nette Framework (167) 
Related Projects
Advertising 📦 9
All Projects
Application Programming Interfaces 📦 120
Applications 📦 181
Artificial Intelligence 📦 72
Blockchain 📦 70
Build Tools 📦 111
Cloud Computing 📦 79
Code Quality 📦 28
Collaboration 📦 30
Command Line Interface 📦 48
Community 📦 81
Companies 📦 60
Compilers 📦 60
Computer Science 📦 74
Configuration Management 📦 39
Content Management 📦 167
Control Flow 📦 197
Data Formats 📦 77
Data Processing 📦 266
Data Storage 📦 132
Economics 📦 60
Frameworks 📦 198
Games 📦 122
Graphics 📦 103
Hardware 📦 148
Integrated Development Environments 📦 47
Learning Resources 📦 147
Legal 📦 28
Libraries 📦 119
Lists Of Projects 📦 21
Machine Learning 📦 336
Mapping 📦 61
Marketing 📦 15
Mathematics 📦 55
Media 📦 228
Messaging 📦 97
Networking 📦 304
Operating Systems 📦 84
Operations 📦 120
Package Managers 📦 52
Programming Languages 📦 229
Runtime Environments 📦 96
Science 📦 42
Security 📦 375
Social Media 📦 26
Software Architecture 📦 70
Software Development 📦 68
Software Performance 📦 57
Software Quality 📦 127
Text Editors 📦 45
Text Processing 📦 131
User Interface 📦 310
User Interface Components 📦 465
Version Control 📦 29
Virtualization 📦 68
Web Browsers 📦 38
Web Servers 📦 25
Web User Interface 📦 194