Pomocné třídy
*************


DomQuery
--------
`Tester\DomQuery` je třída rozšiřující `SimpleXMLElement` o metody usnadňující testování obsahu HTML nebo XML.

```php
# v $html je řetězec s HTML dokumentem, v $dom získáme kořenový element
$dom = Tester\DomQuery::fromHtml($html);

# můžeme testovat přítomnost elementů podle CSS selektorů
Assert::true($dom->has('form#registration'));
Assert::true($dom->has('input[name="username"]'));
Assert::true($dom->has('input[type="submit"]'));

# nebo vybrat elementy jako pole DomQuery
$elems = $dom->find('input[data-autocomplete]');

# nebo ověřovat, zda element vyhovuje selektoru (od verze 2.5.3)
Assert::true($elems[0]->matches('[type="submit"]'));
```


FileMock
--------
`Tester\FileMock` emuluje v paměti soubory a usnadňuje tak testování kódu, který používá funkce `fopen()`, `file_get_contents()`, `parse_ini_file()` a podobné. Příklad použití:

```php
# Testovaná třída
class Logger
{
	public function __construct(
		private string $logFile,
	) {
	}

	public function log(string $message): void
	{
		file_put_contents($this->logFile, $message . "\n", FILE_APPEND);
	}
}

# Nový prázdný soubor
$file = Tester\FileMock::create('');

$logger = new Logger($file);
$logger->log('Login');
$logger->log('Logout');

# Testujeme vytvořený obsah
Assert::same("Login\nLogout\n", file_get_contents($file));
```


Assert::with() .[filter]
------------------------
Nejde o aserci, ale pomocníka pro testování privátních metod a property objektů.

```php
class Entity
{
	private $enabled;
	// ...
}

$ent = new Entity;

Assert::with($ent, function () {
	Assert::true($this->enabled); // zpřístupněná privátní $ent->enabled
});
```


Helpers::purge() .[filter]
--------------------------
Metoda `purge()` vytvoří zadaný adresář, a pokud již existuje, smaže celý jeho obsah. Hodí se pro vytvoření dočasného adresáře. Například v `tests/bootstrap.php`:

```php
@mkdir(__DIR__ . '/tmp');  # @ - adresář již může existovat

define('TempDir', __DIR__ . '/tmp/' . getmypid());
Tester\Helpers::purge(TempDir);
```


Environment::lock() .[filter]
-----------------------------
Testy se spouštějí paralelně. Někdy ovšem potřebujeme, aby se běh testů nepřekrýval. Typicky u databázových testů je nutné, aby si test připravil obsah databáze a jiný test mu po čas běhu do databáze nesahal. V těchto testech použijeme `Tester\Environment::lock($name, $dir)`:

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

První parametr je jméno zámku, druhý je cesta k adresáři pro uložení zámku. Test, který získá zámek jako první, proběhne, ostatní testy musí počkat na jeho dokončení.


Environment::bypassFinals() .[filter]
-------------------------------------
Třídy anebo metody označené jako `final` se obtížně testují. Volání `Tester\Environment::bypassFinals()` na začátku testu způsobí, že jsou klíčová slova `final` během načítání kódu vypuštěna.

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

Tester\Environment::bypassFinals();

class MyClass extends NormallyFinalClass  # <-- NormallyFinalClass už není final
{
	// ...
}
```


Environment::setup() .[filter]
------------------------------
- zlepší čitelnost výpisu chyb (včetně obarvování), jinak je vypsán výchozí PHP stack trace
- zapne kontrolu, že byly v testu volány aserce, jinak test bez asercí (například zapomenutých) projde také
- při použití `--coverage` spustí automaticky sběr informací o spuštěném kódu (popsáno dále)
- vypíše stav OK nebo FAILURE na konci skriptu


Environment::setupFunctions() .[filter]{data-version:2.5}
---------------------------------------------------------
Vytvoří globální funkce `test()`, `testException()`, `setUp()` a `tearDown()`, do kterých můžete členit testy.

```php
test('popis testu', function () {
	Assert::same(123, foo());
	Assert::false(bar());
	// ...
});
```


Environment::VariableRunner .[filter]
-------------------------------------
Umožní zjistit, zda byl test puštěn přímo, anebo pomocí Testeru.

```php
if (getenv(Tester\Environment::VariableRunner)) {
	# spuštěno Testerem
} else {
	# spuštěno jinak
}
```


Environment::VariableThread .[filter]
-------------------------------------
Tester spouští testy paralelně v zadaném počtu vláken. Pokud nás zajímá číslo vlákna, zjistíme ho z proměnné prostředí:

```php
echo "Běžím ve vlákně číslo " . getenv(Tester\Environment::VariableThread);
```