Nette Tester

https://github.com/nette/tester
Admin
Nette Tester is a productive unit testing framework for PHP that provides assertion functions, code...
Tokens:131,339
Snippets:942
Trust Score:9.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Procedural test suite example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Demonstrates a full procedural test suite using global helpers: setUp, tearDown, test, testException, and testNoError. The output shows a passing test (√) and a failing test (×) that rethrows the underlying AssertException.

```php
<?php
use Tester\Assert;
use Tester\Environment;

require __DIR__ . '/vendor/autoload.php';

Environment::setup();
Environment::setupFunctions(); // loads the global helpers

setUp(function () {
    $GLOBALS['db'] = new Database(':memory:');
});

tearDown(function () {
    $GLOBALS['db']->close();
});

test('inserts a row', function () {
    $GLOBALS['db']->insert('users', ['name' => 'John']);
    Assert::same(1, $GLOBALS['db']->count('users'));
});

test('rejects empty names', function () {
    Assert::exception(fn() => $GLOBALS['db']->insert('users', []), \InvalidArgumentException::class);
});

testException('duplicate email throws', function () {
    $GLOBALS['db']->insert('users', ['email' => 'a@b.c']);
    $GLOBALS['db']->insert('users', ['email' => 'a@b.c']);
}, \PDOException::class, null, '23000');

testNoError('reads configuration', function () {
    $cfg = parse_ini_file(__DIR__ . '/config.ini', true);
    Assert::type('array', $cfg);
});
```

```text
√ inserts a row
× rejects empty names
```

--------------------------------

### Using --setup with the CLI

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Runner.md

Shows a setup.php file that receives the $runner instance and modifies its configuration, then the CLI command to run tests with that setup file. The setup script adds a path, disables envSkipper (illustrative), and sets an environment variable from the system.

```php
// setup.php
$runner->paths[] = 'extra/tests';
$runner->envSkipper = null; // (illustrative: configure whatever the runner exposes)
$runner->setEnvironmentVariable('MY_SECRET', getenv('MY_SECRET'));
```

```bash
tester tests --setup setup.php
```

--------------------------------

### start() method signature

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Starts gathering code coverage. Throws LogicException if already started or engine not supported, RuntimeException if file cannot be opened.

```php
/**
 * Starts gathering the information for code coverage.
 * @throws \LogicException
 */
public static function start(string $file, string $engine): void
```

--------------------------------

### setUp() and tearDown() method signatures

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestCase.md

Hooks that run before and after each test method invocation. setUp() runs once per data set; tearDown() also runs on failure with errors suppressed.

```php
protected function setUp() // returns void; override in subclasses
protected function tearDown() // returns void; override in subclasses
```

--------------------------------

### setUp() / tearDown()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestCase.md

Hooks run before/after each test method's invocation. setUp() runs once per data set; tearDown() is also executed on failure with all errors suppressed.

```APIDOC
## [PHP] setUp() / tearDown()

### Description
Hooks run before/after each test method's invocation. `setUp()` runs once per data set. `tearDown()` is also executed on failure, with all errors/exceptions suppressed (`silentTearDown()`).

### Method
PHP methods

### Endpoint
`protected function setUp()` / `protected function tearDown()`

### Parameters
None

### Returns
- **void** - Both methods return void; override in subclasses

### Source
`src/Framework/TestCase.php:243,251`
```

--------------------------------

### Detection and error handling example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Shows how to detect available engines, handle start errors, and check if collection is active.

```php
use Tester\CodeCoverage\Collector;

$engines = Collector::detectEngines();
if (!$engines) {
    throw new \RuntimeException('No coverage engine available (install Xdebug or PCOV, or run under phpdbg).');
}

[$engine, $version] = $engines[0];
try {
    Collector::start('/tmp/coverage.dat', $engine);
} catch (\LogicException $e) {
    if (Collector::isStarted()) {
        Collector::save(); // merge whatever we have
    } else {
        echo $e->getMessage();
    }
}

echo Collector::isStarted() ? 'collecting' : 'not running';
```

--------------------------------

### start()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Starts gathering code coverage information using the specified engine and writes to the shared coverage file. Throws exceptions on invalid engine or file issues.

```APIDOC
## start()

### Description
Starts the engine (`pcov\start()` / `xdebug_start_code_coverage(XDEBUG_CC_UNUSED | XDEBUG_CC_DEAD_CODE)` / `phpdbg_start_oplog()`) and registers a shutdown function inside a shutdown function calling `save()`, so the merge runs after the test's own shutdown handlers.

### Method
Static method

### Signature
```php
public static function start(string $file, string $engine): void
```

### Parameters
- **file** (string) - Required - Path of the shared coverage file (opened `c+`)
- **engine** (string) - Required - One of `EnginePcov`, `EnginePhpdbg`, `EngineXdebug` (must be among detected)

### Throws
- `\LogicException('Code coverage collector has been already started.')`
- `\LogicException("Code coverage engine '$engine' is not supported.")`
- `\RuntimeException("Cannot open file '$file' for code coverage.")`

### Example
```php
Collector::start('/tmp/coverage.dat', Collector::EnginePcov);
```
```

--------------------------------

### Standard setup with Environment::setup()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Environment.md

Initializes error handling, colors, and assertion guard. Optionally calls setupFunctions() to enable global test()/setUp()/tearDown() helpers.

```php
<?php
use Tester\Assert;
use Tester\Environment;

require __DIR__ . '/vendor/autoload.php';

Environment::setup(); // error handling, colors, assertion guard
Environment::setupFunctions(); // optional: global test()/setUp()/tearDown() helpers

Assert::same(1 + 1, 2);
```

--------------------------------

### Install Nette Tester via Composer

Source: https://github.com/nette/tester/blob/master/readme.md

Install Nette Tester as a development dependency using Composer. This is the recommended installation method.

```bash
composer require nette/tester --dev
```

--------------------------------

### setUp()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Sets the closure to call before each test() invocation. Stores the closure in a static local variable, keeping only the latest one.

```APIDOC
## setUp()

### Description
Sets the closure to call before each test() invocation. Stores the closure in a static local variable, keeping only the latest one.

### Method
Function call

### Signature
```php
setUp(?Closure $closure): void
```

### Parameters
- **closure** (?Closure) - Required - Callback, or `null` to clear the previously registered one

### Notes
Only one closure per hook is kept (the latest wins).
```

--------------------------------

### Environment::setup()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Environment.md

Initializes the test process by setting up error handling, colors, and loading necessary components. It also reads test annotations and starts code coverage collection if configured.

```APIDOC
## Environment::setup()

### Description
Initializes the test process: calls `setupErrors()` and `setupColors()`; forces loading of `Runner\Job`, `Dumper`, `Assert`; reads file annotations and sets `$checkAssertions`; starts code coverage collector when environment variables are set; adjusts `Dumper` settings under JetBrains-JediTerm.

### Method
`public static function setup(): void`

### Parameters
None

### Return Value
`void`

### Source
`src/Framework/Environment.php:59`
```

--------------------------------

### test(string $description, Closure $closure): void

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Runs a labeled test closure, calling setUp and tearDown around it. Prints a pass/fail marker and rethrows exceptions on failure.

```APIDOC
## test(string $description, Closure $closure): void

### Description
Runs a labeled test closure, calling setUp and tearDown around it. Prints a pass/fail marker and rethrows exceptions on failure.

### Method
Function call

### Signature
```php
function test(string $description, Closure $closure): void
```

### Parameters
- **description** (string) - Required - Label printed with a `√` (pass) or `×` (fail) marker; an empty string suppresses printing
- **closure** (Closure(): mixed) - Required - The test body

### Behavior
- Calls the closure registered by `setUp()` first (via `(new ReflectionFunction('setUp'))->getStaticVariables()['fn']`).
- Runs `$closure()`; on success prints `√ <description>`.
- On `Throwable`, prints `× <description>\n\n` and rethrows (so the runner reports the failure with its stack trace).
- In `finally`, calls the `tearDown()` closure — so `tearDown()` runs even on failure.

### Throws
- `\Exception(__FUNCTION__ . "() expects 2 parameters, $count given.")` when called with more than two arguments (since 2.5.3).
```

--------------------------------

### Output-match test example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestHandler.md

Shows a test using @outputMatch and @exitCode annotations. The test sets up the environment and echoes output that must match the pattern 'Hello %s%!'.

```php
<?php
/**
 * @outputMatch Hello %s%!
 * @exitCode 0
 */

Tester\Environment::setup();
echo "Hello world!";
```

--------------------------------

### Query filtering and annotation parsing example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/DataProvider.md

Demonstrates loading data with a query filter and parsing a @dataProvider annotation. The parseAnnotation call returns file path, query, and optional flag; the example shows how to enforce a required provider.

```php
use Tester\DataProvider;

$data = DataProvider::load(__DIR__ . '/cases.data', 'php >= 8.1');
foreach ($data as $key => $set) {
    echo "$key\n";  // only sets whose key tokens satisfy "php >= 8.1"
}

[$file, $query, $optional] = DataProvider::parseAnnotation('? data.ini, os != windows', __FILE__);
// $file = '/abs/dir/data.ini', $query = 'os != windows', $optional = true
if (!$optional && !isset(DataProvider::load($file)[0])) {
    throw new \Exception('provider required');
}
```

--------------------------------

### Run static analysis with composer phpstan

Source: https://github.com/nette/tester/blob/master/AGENTS.md

Run static analysis on the codebase using the composer script.

```bash
composer phpstan
```

--------------------------------

### Programmatic TestHandler usage

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestHandler.md

Demonstrates manual setup of Runner, TestHandler, and temp directory, then calling initiate() to discover tests and queue jobs. Note that initiate() and assess() are normally called internally by Runner::run().

```php
use Tester\Runner\Job;
use Tester\Runner\PhpInterpreter;
use Tester\Runner\Runner;
use Tester\Runner\TestHandler;

$runner = new Runner(new PhpInterpreter(PHP_BINARY));
$runner->paths = ['tests/'];
$handler = new TestHandler($runner);
$handler->setTempDirectory(sys_get_temp_dir() . '/tester');

// discovery → variants → jobs (normally done by Runner::run() → findTests())
$handler->initiate(__DIR__ . '/tests/case.test.phpt');
foreach ($runner->getJobCount() ? [$handler] : [] as $h) { /* jobs are queued inside the Runner */ }
$runner->run();
```

--------------------------------

### Example class Greeting in Greeting.php

Source: https://github.com/nette/tester/blob/master/readme.md

A simple PHP class with a method that throws an exception for invalid input and returns a greeting string.

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

--------------------------------

### Environment::setupColors()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Environment.md

Determines whether to use ANSI colors based on environment variables and terminal capabilities. Starts an output buffer that strips ANSI sequences when colors are disabled.

```APIDOC
## Environment::setupColors()

### Description
Sets `$useColors` from `NETTE_TESTER_COLORS` if present; otherwise autodetects based on SAPI, `NO_COLOR` env var, and terminal VT100 support. Starts an output buffer that strips ANSI sequences when colors are off.

### Method
`public static function setupColors(): void`

### Parameters
None

### Return Value
`void`

### Source
`src/Framework/Environment.php:87`
```

--------------------------------

### testException(string $description, Closure $function, string $class, ?string $message = null, int|string|null $code = null): void

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Runs a labeled test that asserts the closure throws a specific exception. Delegates to test() with Assert::exception, so setUp()/tearDown() run.

```APIDOC
## testException(string $description, Closure $function, string $class, ?string $message = null, int|string|null $code = null): void

### Description
Runs a labeled test that asserts the closure throws a specific exception. Delegates to test() with Assert::exception, so setUp()/tearDown() run.

### Method
Function call

### Signature
```php
function testException(
    string $description,
    Closure $function,
    string $class,
    ?string $message = null,
    int|string|null $code = null,
): void
```

### Parameters
- **description** (string) - Required - Test label
- **function** (Closure(): mixed) - Required - Closure expected to throw
- **class** (string, class-string<Throwable>) - Required - Expected exception class
- **message** (?string) - Optional, default `null` - Expected message (mask/regexp), `null` disables
- **code** (int|string|null) - Optional, default `null` - Expected exception code

### Behavior
Delegates to `test($description, fn() => Assert::exception($function, $class, $message, $code))`, so `setUp()`/`tearDown()` run (changed in 2.6.0).
```

--------------------------------

### setUp() and tearDown() function signatures

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Sets the closure to call before or after each test() invocation. Each stores the closure in a static local variable read by test() via reflection. Only one closure per hook is kept (the latest wins).

```php
/**
 * Sets the closure to call before each test() invocation.
 * @param (Closure(): mixed)|null $closure
 */
function setUp(?Closure $closure): void
```

```php
/**
 * Sets the closure to call after each test() invocation.
 * @param (Closure(): mixed)|null $closure
 */
function tearDown(?Closure $closure): void
```

--------------------------------

### Manual start/stop example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Shows manual usage of Collector::start(), flush(), and automatic save() at shutdown. Normally handled via runner's --coverage flow.

```php
use Tester\CodeCoverage\Collector;

Collector::start('/tmp/coverage.dat', Collector::EnginePcov);
// ... run the code under test ...
Collector::flush();          // write intermediate results (PHPDBG)
// at shutdown, save() merges automatically
```

--------------------------------

### PHP provider example with load()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/DataProvider.md

Shows a PHP data provider file returning an array of test cases, and how to load a filtered subset using DataProvider::load(). The query 'square 2' filters to only that key.

```php
// data.provider.php
return [
    'square 2' => [2, 4],
    'square 3' => [3, 9],
    'square 0' => [0, 0],
];

// test code
$data = DataProvider::load(__DIR__ . '/data.provider.php', 'square 2');
// ['square 2' => [2, 4]]
```

--------------------------------

### Environment::setupErrors()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Environment.md

Configures error reporting for clean test output and installs exception and shutdown handlers. Converts certain errors to exceptions and handles fatal errors and assertion checks.

```APIDOC
## Environment::setupErrors()

### Description
Configures error reporting: `error_reporting(E_ALL)`, `display_errors=1`, `html_errors=0`, `log_errors=0`, `zend.exception_ignore_args=0`. Installs an exception handler that dumps exceptions and exits with appropriate codes. Converts recoverable/user errors to `\ErrorException`. Registers shutdown handlers for fatal errors and final output.

### Method
`public static function setupErrors(): void`

### Parameters
None

### Return Value
`void`

### Source
`src/Framework/Environment.php:110`
```

--------------------------------

### isStarted() method signature

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Returns true after a successful start() (the shared file handle is open).

```php
public static function isStarted(): bool
```

--------------------------------

### Run a single test as a plain script

Source: https://github.com/nette/tester/blob/master/AGENTS.md

A single test file is a plain runnable PHP script; execute it directly with php.

```bash
php tests/Framework/Assert.same.phpt
```

--------------------------------

### Colored output example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Ansi.md

Demonstrates colorize(), color(), reset(), and stripAnsi() for colored console output and stripping codes for plain files.

```php
use Tester\Ansi;

echo Ansi::colorize('PASSED', 'lime') . "\n";
echo Ansi::colorize('FAILED', 'white/red') . "\n";
echo Ansi::color('yellow') . 'warning' . Ansi::reset() . "\n";

// strip color codes for plain files
$plain = Ansi::stripAnsi(Ansi::colorize('info', 'blue')); // 'info'
```

--------------------------------

### test() function signature

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Defines the test() helper that runs a labeled closure with setUp/tearDown. Requires setupFunctions() to be loaded. Throws an exception if called with more than two arguments.

```php
/**
 * Runs a labeled test closure, calling setUp and tearDown around it.
 * @param Closure(): mixed $closure
 */
function test(string $description, Closure $closure): void
```

--------------------------------

### Annotated .phpt test example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestHandler.md

Shows a file-level annotated test with @dataProvider, @phpVersion, and @timeout annotations. The data comes via Environment::loadData() or $argv, and the test asserts the greeting result.

```php
<?php
/**
 * TEST: Greets the user
 * @dataProvider greeting.data, format = polite
 * @phpVersion >= 8.1
 * @timeout 20
 */

require __DIR__ . '/vendor/autoload.php';

Tester\Environment::setup();

[$name, $expected] = ...; // data comes via Environment::loadData() or $argv
Tester\Assert::same($expected, greet($name));
```

--------------------------------

### Run test suite with in-repo runner

Source: https://github.com/nette/tester/blob/master/AGENTS.md

Use the in-repo runner (not vendor/bin) to execute the full test suite or a single test file. The -s flag is used for the suite.

```bash
src/tester tests -s
```

```bash
src/tester tests/Framework/Assert.same.phpt -s
```

--------------------------------

### initiate() method signature

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestHandler.md

Declares the public method that reads annotations, builds base Test objects, and dispatches initiate* methods to generate variants. Each resulting Test gets a Job with resolved @timeout and is registered via Runner::addJob().

```php
public function initiate(string $file): void
```

--------------------------------

### Selectors and XPath with DomQuery

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/DomQuery.md

Shows how to use CSS selectors with find() and has(), and how to convert a CSS selector to XPath using css2xpath(). The example uses fromXml() to parse XML content.

```php
$dom = DomQuery::fromXml('<root><item id="a" class="x">1</item><item id="b">2</item></root>');

Assert::count(2, $dom->find('item'));
Assert::true($dom->has('item.x'));
Assert::true($dom->has('item[id="a"]'));
Assert::true($dom->has('item[id^="a"]'));

echo DomQuery::css2xpath('div#main > p.lead'); // '//div[@id=\'main\']/*[contains(concat(...," lead ")]'
```

--------------------------------

### Tester\DomQuery - Testing HTML pages

Source: https://github.com/nette/tester/blob/master/readme.md

Parses HTML and checks for elements using CSS selectors. The example verifies the presence of username and password input fields.

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

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

--------------------------------

### testException() function signature

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Defines the testException() helper that asserts a closure throws a specific exception. Delegates to test() with Assert::exception, so setUp/tearDown run.

```php
/**
 * Runs a labeled test that asserts the closure throws a specific exception.
 * @param Closure(): mixed $function
 * @param class-string<Throwable> $class
 */
function testException(
    string $description,
    Closure $function,
    string $class,
    ?string $message = null,
    int|string|null $code = null,
): void
```

--------------------------------

### Merging from multiple processes (conceptual)

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Conceptual example of how the runner merges coverage from multiple processes. Positive entries always win over negative ones.

```php
// process A and process B both call start($sharedFile, 'Xdebug') + save()
// save() serializes A, then B locks, reads A's data, and merges B on top
// positive entries always win over negative ones from other processes
```

--------------------------------

### Attribute metadata and skip example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestCase.md

Shows using #[Throws] and #[DataProvider] attributes (which take precedence over docblocks) and calling $this->skip() to conditionally skip a test on non-Windows platforms. The test is run by instantiating the class and calling run().

```php
use Tester\Attributes\DataProvider;
use Tester\Attributes\Throws;
use Tester\TestCase;

class MoneyTest extends TestCase
{
    #[Throws(\InvalidArgumentException::class, 'amount must be positive')]
    public function testNegativeAmount(): void
    {
        new Money(-1);
    }

    #[DataProvider('providePrices')]
    public function testTotal(int $a, int $b, int $total): void
    {
        Assert::same($total, (new Money($a))->add($b)->total());
    }

    public function testWindowsOnly(): void
    {
        if (PHP_OS_FAMILY !== 'Windows') {
            $this->skip('Windows only');
        }
    }

    protected function providePrices(): array
    {
        return ['set1' => [1, 2, 3], 'set2' => [10, 20, 30]];
    }
}

(new MoneyTest)->run();
```

--------------------------------

### Classic test case with providers

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestCase.md

Shows a standard Tester\TestCase subclass with setUp, simple assertions, exception testing, and a data provider. The test is run by instantiating the class and calling run().

```php
use Tester\Assert;
use Tester\TestCase;

class GreetingTest extends TestCase
{
    private Greeting $greeting;

    protected function setUp(): void
    {
        $this->greeting = new Greeting;
    }

    public function testSay(): void
    {
        Assert::same('Hello John', $this->greeting->say('John'));
    }

    public function testSayInvalid(): void
    {
        Assert::exception(fn() => $this->greeting->say(null), \InvalidArgumentException::class);
    }

    /** @dataProvider provideNumbers */
    public function testAdd(int $a, int $b, int $expected): void
    {
        Assert::same($expected, $a + $b);
    }

    public function provideNumbers(): array
    {
        return [[1, 2, 3], [4, 5, 9]];
    }
}

(new GreetingTest)->run();
```

--------------------------------

### tester command-line usage and options

Source: https://github.com/nette/tester/blob/master/readme.md

Shows the full usage and options for the `tester` command (or `php tester.php`). Includes options for specifying the PHP interpreter, custom php.ini, INI entries, skipping tests, timeouts, parallel jobs, output formats, watching directories, slowest tests, environment info, setup scripts, temporary directory, colors, and code coverage.

```text
> tester

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

Options:
    -p <path>                    Specify PHP interpreter to run (default: php).
    -c <path>                    Use custom php.ini, ignore system configuration.
    -C                           With -c, include system configuration as well.
    -d <key=value>...            Define INI entry 'key' with value 'value'.
    -s                           Show information about skipped tests.
    --stop-on-fail               Stop execution upon the first failure.
    --timeout <seconds>          Time limit for each test in seconds, can be overridden by @timeout.
    -j <num>                     Run <num> jobs in parallel (default: 8).
    -o <console|console-lines|github|tap|junit|log|none>  (e.g. -o junit:output.xml)
                                 Specify one or more output formats with optional file name.
    -w | --watch <path>          Watch directory.
    --slowest [<count>]          Print the 10 (or <count>) slowest tests after the run.
    -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.
```

--------------------------------

### Custom OutputHandler in a --setup script or programmatic runner

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/OutputHandlers.md

Define a custom output handler by implementing the `Tester\Runner\OutputHandler` interface. The example collects results and logs failures via `error_log`. Wire it into the runner with `$runner->outputHandlers[] = $slack;` before calling `$runner->run()`.

```php
use Tester\Runner\OutputHandler;
use Tester\Runner\Test;

$slack = new class implements OutputHandler {
    public array $results = [];
    public function begin(): void {}
    public function prepare(Test $test): void {}
    public function finish(Test $test): void {
        $this->results[] = $test->getResult();
        if ($test->getResult() === Test::Failed) {
            error_log("FAILED: {$test->getSignature()}\n{$test->getOutput()}");
        }
    }
    public function end(): void {
        error_log('summary: ' . json_encode($this->results));
    }
};

// wire it: $runner->outputHandlers[] = $slack; — before $runner->run()
```

--------------------------------

### Testing rendered HTML with DomQuery

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/DomQuery.md

Use DomQuery::fromHtml() to parse HTML and Assert methods to verify form inputs and login form presence. The example uses $latte->renderToString() to generate HTML, but file_get_contents() can be used instead.

```php
use Tester\Assert;
use Tester\DomQuery;

$html = $latte->renderToString($template, $params); // or file_get_contents('...')
$dom = DomQuery::fromHtml($html);

Assert::true($dom->has('input[name="username"]'));
Assert::true($dom->has('input[name="password"]'));
Assert::count(1, $dom->find('form.login'));
```

--------------------------------

### isStarted()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Checks whether the code coverage collector has been successfully started. Returns true after a successful start() call.

```APIDOC
## isStarted()

### Description
`true` after a successful `start()` (the shared file handle is open).

### Method
Static method

### Signature
```php
public static function isStarted(): bool
```

### Return Value
- **bool** - `true` if the collector has been started, `false` otherwise.

### Example
```php
if (Collector::isStarted()) {
    // collector is running
}
```
```

--------------------------------

### help()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CommandLine.md

Echoes the constructor's help string to the output.

```APIDOC
## help()

### Description
Echoes the help string provided to the constructor.

### Method
help

### Signature
```php
public function help(): void
```

### Parameters
None.

### Return Value
- **void** - No return value.
```

--------------------------------

### Error handling and PhpParser usage

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageGenerators.md

Shows how to handle exceptions from generators and parse a source file with PhpParser. The first try block catches invalid data files, the second catches missing extensions, and the parser example demonstrates extracting class information.

```php
use Tester\CodeCoverage\Generators\CloverXMLGenerator;
use Tester\CodeCoverage\Generators\HtmlGenerator;

try {
    new HtmlGenerator('/tmp/missing.dat');
} catch (\Exception $e) {
    echo $e->getMessage(); // "Content of file '/tmp/missing.dat' is invalid."
}

try {
    new CloverXMLGenerator('/tmp/coverage.dat');
} catch (\LogicException $e) {
    echo $e->getMessage(); // requires dom + tokenizer extensions
}

// parse a source file with PhpParser
$parser = new Tester\CodeCoverage\PhpParser;
$info = $parser->parse(file_get_contents('/path/to/Class.php'));
echo $info->classes['Class']['start'];
```

--------------------------------

### Environment::setupFunctions()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Environment.md

Loads global helper functions for tests. This method must be called to make the global functions available.

```APIDOC
## Environment::setupFunctions()

### Description
Loads `src/Framework/functions.php`, defining global helpers `test()`, `testException()`, `testNoError()`, `setUp()`, `tearDown()`.

### Method
`public static function setupFunctions(): void`

### Parameters
None

### Return Value
`void`

### Source
`src/Framework/Environment.php:154`
```

--------------------------------

### initiate(string $file): void

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/TestHandler.md

Reads annotations from a test file, builds the base Test, and creates variants based on initiate* methods. Each resulting Test is queued as a Job in the Runner.

```APIDOC
## initiate(string $file): void

### Description
Reads annotations, builds the base `Test`, then for every matching `initiate*` method replaces the test set with the returned variants (each variant either replaced/skipped — `prepareTest()` + `finishTest()` immediately — or queued). Finally, each resulting `Test` gets a `Job` (`initiateSkip`-style skips are not scheduled): `new Job($test, $php, envVars)` with the resolved `@timeout` and registered via `Runner::addJob()`.

### Method
initiate

### Endpoint
TestHandler::initiate

### Parameters
#### Path Parameters
- **file** (string) - Required - Test file path

### Response
#### Success Response (void)
No return value.
```

--------------------------------

### Environment::setup()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Environment.md

Sets up the in-process test environment, including error handling, colors, code coverage, assertion tracking, locking, data loading, and skipping. Typically called at the top of every test file.

```APIDOC
## Environment::setup()

### Description
Sets up the in-process test environment, including error handling, colors, code coverage, assertion tracking, locking, data loading, and skipping. Typically called at the top of every test file.

### Method
setup()

### Usage
Tester\Environment::setup();

### Notes
- Also invoked by `src/bootstrap.php` when loaded directly.
- Import: `use Tester\Environment;`
```

--------------------------------

### new CommandLine(help, defaults)

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CommandLine.md

Creates a command-line parser instance. The help string defines the grammar for options and arguments, and defaults provide initial values and hidden options.

```APIDOC
## new CommandLine(help, defaults)

### Description
Creates a command-line parser instance. The help string defines the grammar for options and arguments, and defaults provide initial values and hidden options.

### Constructor
`new CommandLine(string $help, array $defaults = [])`

### Parameters
- **$help** (string) - Required - Usage and options description that defines the grammar.
- **$defaults** (array) - Optional - Default values for options and arguments, including hidden options.

### Example
```php
$cmd = new CommandLine(
    "Usage:\n"
    . "    mytool [options] [<input>]\n\n"
    . "Options:\n"
    . "    -j <num>        Threads (default: 8).\n"
    . "    -o <console|tap|none>  Output format.\n"
    . "    -v              Verbose.\n",
    [
        'input' => [CommandLine::Value => getcwd()],
        '--debug' => [], // hidden option
    ],
);
```
```

--------------------------------

### Engine constants for code coverage

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Defines the engine names used by detectEngines() and start().

```php
public const
    EnginePcov = 'PCOV',
    EnginePhpdbg = 'PHPDBG',
    EngineXdebug = 'Xdebug';
```

--------------------------------

### Console progress re-drawing example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Ansi.md

Shows hideCursor(), clearLine(), and showCursor() to re-draw a progress indicator on the same line.

```php
echo Ansi::hideCursor();
for ($i = 0; $i <= 100; $i += 10) {
    echo "\rProgress: $i%" . Ansi::clearLine();
    usleep(50_000);
}
echo "\n" . Ansi::showCursor();
```

--------------------------------

### save() method signature

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Collects line maps, locks the file, merges with array_replace_recursive, and rewrites. Throws LogicException if not started.

```php
/** @throws \LogicException */
public static function save(): void
```

--------------------------------

### run method

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Runner.md

Runs the entire test suite. It calls begin() on output handlers, discovers tests, sorts jobs by cached results, runs up to threadCount jobs in parallel, and returns true when no test failed.

```php
public function run(): bool
```

--------------------------------

### Width-aware table rendering example

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Ansi.md

Uses pad() and truncate() to align table columns with emoji counted as double width.

```php
$rows = [
    ['Name', 'Score'],
    ['Žluťoučký kůň', '42'],
    ['😀🙏', '7'],
];
foreach ($rows as $row) {
    echo Ansi::pad($row[0], 20) . '|' . Ansi::pad($row[1], 6, ' ', STR_PAD_LEFT) . "\n";
}
// emoji count double width, so columns stay aligned
echo Ansi::truncate('A very long heading that should be shortened', 25); // 'A very long heading…'
```

--------------------------------

### Mutators compose in order

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/FileMutator.md

Multiple mutators run in registration order, each receiving the output of the previous one. This example chains two mutators.

```php
FileMutator::addMutator(fn(string $code): string => str_replace('foo(', 'fooMock(', $code));
FileMutator::addMutator(fn(string $code): string => preg_replace('#^<\?php#', '<?php declare(strict_types=1);', $code));
```

--------------------------------

### save()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CodeCoverageCollector.md

Collects line maps from the active engine, merges with existing data under an exclusive lock, and rewrites the serialized coverage file. Throws if not started.

```APIDOC
## save()

### Description
Collects `[positive, negative]` line maps from the active engine, takes an exclusive lock (`flock(LOCK_EX)`), reads the existing serialized coverage, merges with `array_replace_recursive($negative, $original, $positive)` — *covered* (positive) data wins over earlier *uncovered* (negative) data across processes — then rewrites the serialized file. Throws `\LogicException('Code coverage collector has not been started.')` when not started.

### Method
Static method

### Signature
```php
public static function save(): void
```

### Throws
- `\LogicException('Code coverage collector has not been started.')`

### Example
```php
Collector::save(); // merge whatever we have
```
```

--------------------------------

### CommandLine constructor with defaults

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CommandLine.md

Parses command-line options from a help text. The help string defines option names, arguments, repeatability, enums, and defaults. The defaults array can provide extra metadata like RealPath, Normalizer, Value, or hidden options.

```php
/** @param array<string, array<string, mixed>> $defaults */
public function __construct(
    private string $help,
    array $defaults = [],
)
```

--------------------------------

### tearDown()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Sets the closure to call after each test() invocation. Stores the closure in a static local variable, keeping only the latest one.

```APIDOC
## tearDown()

### Description
Sets the closure to call after each test() invocation. Stores the closure in a static local variable, keeping only the latest one.

### Method
Function call

### Signature
```php
tearDown(?Closure $closure): void
```

### Parameters
- **closure** (?Closure) - Required - Callback, or `null` to clear the previously registered one

### Notes
Only one closure per hook is kept (the latest wins).
```

--------------------------------

### Utilities: errorTypeToString, escapeArg, findCommonDirectory, prepareTempDir

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Helpers.md

Demonstrates various helper utilities: converting error types to strings, escaping arguments (non-Windows), finding common directory paths, and preparing a temporary directory.

```php
echo Helpers::errorTypeToString(E_WARNING);              // 'E_WARNING'
echo Helpers::escapeArg('file with spaces.php');         // 'file\ with\ spaces.php' (non-Windows)
$common = Helpers::findCommonDirectory(['/a/b/c.php', '/a/b/d/e.php']); // '/a/b'
$temp = Helpers::prepareTempDir(sys_get_temp_dir());     // '<sys_get_temp_dir()>/Tester'
```

--------------------------------

### Annotation parsing with Helpers::parseDocComment

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Helpers.md

Parses a doc comment to extract annotations. The example shows a TEST annotation, @dataProvider, and @skip, with the resulting array structure.

```php
$src = <<<'PHP'
/**
 * TEST: greets a user
 * @dataProvider data.ini
 * @skip when running without ext
 */
PHP;

$annotations = Helpers::parseDocComment($src);
// ['0' => 'TEST: greets a user', 'dataprovider' => 'data.ini', 'skip' => 'when running without ext']
```

--------------------------------

### prepareTempDir()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Helpers.md

Prepares a temporary directory under a given base path. This method is marked as internal and used for the `--temp` option.

```APIDOC
## prepareTempDir()

### Description
Prepares a temporary directory under a given base path. This method is marked as internal and used for the `--temp` option.

### Method
`public static function prepareTempDir(string $path): string`

### Parameters
- `path` (string) - Required - Base directory that must exist and be writable

### Return Value
- `string` - The path to the `Tester` subdirectory (created if needed)

### Exceptions
- `\RuntimeException` - Thrown when the base path is not a writable directory or the `Tester` subdirectory cannot be created.
```

--------------------------------

### CommandLine::__construct

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/CommandLine.md

Creates a command-line argument parser from a help text. The help text defines the option grammar, including option names, arguments, repeatability, enums, and defaults.

```APIDOC
## CommandLine::__construct

### Description
Creates a command-line argument parser from a help text. The help text defines the option grammar, including option names, arguments, repeatability, enums, and defaults.

### Method
Constructor

### Signature
```php
public function __construct(
    private string $help,
    array $defaults = [],
)
```

### Parameters
- **help** (string) - Required - Usage text; parsed line-by-line into option metadata.
- **defaults** (array<string, array<string, mixed>>) - Optional - Extra option metadata (RealPath, Normalizer, Value, hidden options); merged into the parsed metadata.

### Description of Parsing
For each help line it extracts: the option name (aliases, e.g. `-w`/`--watch`, map to the last listed name), argument placeholder (`<…>` required, `[…]` optional), repeatability from a trailing `...`, enum values from `<a|b|c>`, and the default from a `(default: …)` parenthetical.

### Exceptions
- Throws `\InvalidArgumentException("Unable to parse '…'.")` when a line's grammar cannot be matched.

```

--------------------------------

### Pointing a parser at mock code with include

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/FileMock.md

Creates a mock PHP file and shows that shell_exec with the mock:// path only works if the wrapper is registered in the child process; prefer include/require in-process. The include requires a valid path, so use realpath where needed.

```php
use Tester\FileMock;

$script = FileMock::create('<?php echo "hi";', 'php');
$output = shell_exec('php ' . escapeshellarg($script) . ' 2>/dev/null'); // mock:// stream is visible to child processes only if the wrapper is registered there too — prefer include/require in-process:
$result = include $script; // requires $script to be a valid path for include; use realpath where needed
```

--------------------------------

### testNoError()

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/GlobalFunctions.md

Runs a labeled test that asserts the closure generates no errors or exceptions. Throws an exception for extra arguments and runs inside test().

```APIDOC
## testNoError()

### Description
Runs a labeled test that asserts the closure generates no errors or exceptions. Throws an exception for extra arguments and runs inside test().

### Method
Function call

### Signature
```php
testNoError(string $description, Closure $function): void
```

### Parameters
- **description** (string) - Required - Test label
- **function** (Closure(): mixed) - Required - Closure checked with `Assert::noError()`

### Throws
- `\Exception(__FUNCTION__ . "() expects 2 parameters, $count given.")` for extra arguments

### Notes
Runs inside `test()`.
```

--------------------------------

### Creating and evolving a test

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Test.md

Shows how to create a Test instance, set a title, add arguments, and set a result. Demonstrates the immutable with*() pattern and the LogicException thrown when modifying a test with a result.

```php
use Tester\Runner\Test;

$test = new Test(__DIR__ . '/foo.test.phpt');
$test = $test->withTitle('tests the foo');
$test = $test->withArguments([
    'dataprovider' => ['set1|/path/data.ini'],   // yields --dataprovider=set1|/path/data.ini
    'multiple' => [0],                             // yields --multiple=0
]);
echo $test->getSignature(); // '/path/foo.test.phpt --dataprovider=... --multiple=0'

$test = $test->withResult(Test::Skipped, 'requires iconv', 0.014);
echo $test->getOutput();    // '' (nothing captured)

try {
    $test->withResult(Test::Passed, null);
} catch (\LogicException $e) {
    echo $e->getMessage(); // 'Result of test is already set to 3 with message ...'
}
```

--------------------------------

### Helpers::prepareTempDir

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Helpers.md

Prepares a temporary directory for Tester usage. Creates a subdirectory named 'Tester' under the given base directory.

```APIDOC
## Helpers::prepareTempDir

### Description
Prepares a temporary directory for Tester usage. Creates a subdirectory named 'Tester' under the given base directory.

### Method
`Helpers::prepareTempDir(string $baseDir): string`

### Parameters
- **$baseDir** (string) - Required - Base directory for the temporary directory.

### Return Value
- **string** - The path to the prepared temporary directory.

### Example
```php
$temp = Helpers::prepareTempDir(sys_get_temp_dir()); // '<sys_get_temp_dir()>/Tester'
```
```

--------------------------------

### Test file greeting.test.phpt

Source: https://github.com/nette/tester/blob/master/readme.md

A test file that sets up the Tester environment, includes the class, and uses an assertion to verify the say() method.

```php
use Tester\Assert;

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Greeting.php';

Tester\Environment::setup();

$h = new Greeting;

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

--------------------------------

### Environment::Version

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/Environment.md

Package version string constant.

```APIDOC
## Environment::Version

### Description
Package version string constant.

### Value
'2.7.0'
```

--------------------------------

### Catching and inspecting a failure

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/AssertException.md

Shows how to catch an AssertException from Assert::same() and access its properties: origMessage, getMessage() (substituted), expected, actual, and getPrevious(). The example uses arrays to demonstrate the diff.

```php
use Tester\Assert;
use Tester\AssertException;

try {
    Assert::same(['a' => 1], ['a' => 2]);
} catch (AssertException $e) {
    echo $e->origMessage;             // '%1 should be %2'
    echo $e->getMessage();            // '[a => 1] should be [a => 2]' (substituted)
    echo $e->expected;                // ['a' => 1]  (as array)
    echo $e->actual;                  // ['a' => 2]
    echo get_class($e->getPrevious()); // previous, if any
}
```

--------------------------------

### withPhpIniOption() method signature

Source: https://github.com/nette/tester/blob/master/_autodocs/api-reference/PhpInterpreter.md

Returns a clone with a -d name[=value] option appended to the command line.

```php
public function withPhpIniOption(string $name, ?string $value = null): static
```
Tokens:
Raw