Pomocné třídy
*************
HttpAssert .{data-version:2.5.6}
--------------------------------
Třída `Tester\HttpAssert` slouží k testování HTTP serveru. Umožňuje jednoduše provádět HTTP požadavky a ověřovat jejich stavové kódy, hlavičky i obsah odpovědi pomocí fluent interface.
```php
# Základní HTTP požadavek a ověření odpovědi
$response = Tester\HttpAssert::fetch('https://example.com/api/users');
$response
->expectCode(200)
->expectHeader('Content-Type', contains: 'json')
->expectBody(contains: 'users');
```
Metoda `fetch()` standardně vytváří GET požadavek, ale všechny parametry lze přizpůsobit:
```php
HttpAssert::fetch(
'https://api.example.com/users',
method: 'POST',
headers: [
'Authorization' => 'Bearer token123', # asociativní pole
'Accept: application/json', # nebo string formát
],
cookies: ['session' => 'abc123'],
follow: false, # nesledovat redirecty
body: '{"name": "John"}',
timeout: 10, # v sekundách, výchozí je 30
)
->expectCode(201);
```
Pokud server neodpoví v čase daném parametrem `timeout`, požadavek skončí výjimkou a test selže. Server, který přestal odpovídat, tak vaše testy nezablokuje navždy. .{data-version:2.7.0}
Stavové kódy můžete ověřovat metodami `expectCode()` a `denyCode()`. Jako parametr předáte buď konkrétní číslo, nebo validační funkci:
```php
$response
->expectCode(200) # přesný kód
->expectCode(fn($code) => $code < 400) # vlastní validace
->denyCode(404) # nesmí být 404
->denyCode(fn($code) => $code >= 500); # nesmí být chyba serveru
```
Pro práci s hlavičkami slouží metody `expectHeader()` a `denyHeader()`. Můžete kontrolovat existenci hlavičky, její přesnou hodnotu nebo jen část obsahu:
```php
$response
->expectHeader('Content-Type') # hlavička musí existovat
->expectHeader('Content-Type', 'application/json') # přesná hodnota
->expectHeader('Content-Type', contains: 'json') # obsahuje text
->expectHeader('Server', matches: 'nginx %a%') # odpovídá vzoru
->denyHeader('X-Powered-By') # hlavička nesmí existovat
->denyHeader('X-Debug', contains: 'sensitive') # nesmí obsahovat text
->denyHeader('X-Debug', matches: '~debug~i'); # nesmí odpovídat vzoru
```
Obdobně funguje ověřování těla odpovědi prostřednictvím metod `expectBody()` a `denyBody()`:
```php
$response
->expectBody('OK') # přesná hodnota
->expectBody(contains: '"status": "success"') # obsahuje část JSON
->expectBody(matches: '%A% hello %A%') # odpovídá vzoru
->expectBody(fn($body) => json_decode($body) !== null) # vlastní validace
->denyBody('Error occurred') # nesmí mít přesnou hodnotu
->denyBody(contains: 'error') # nesmí obsahovat text
->denyBody(matches: '~exception|fatal~i'); # nesmí odpovídat vzoru
```
Parametr `follow` řídí, jak HttpAssert zachází s HTTP přesměrováními:
```php
# Testování redirectu bez následování (výchozí)
HttpAssert::fetch('https://example.com/redirect', follow: false)
->expectCode(301)
->expectHeader('Location', 'https://example.com/new-url');
# Následování všech redirectů až do konečné odpovědi
HttpAssert::fetch('https://example.com/redirect', follow: true)
->expectCode(200)
->expectBody(contains: 'final content');
```
DomQuery
--------
`Tester\DomQuery` je třída rozšiřující `SimpleXMLElement` o snadné vyhledávání v HTML nebo XML pomocí CSS selektorů.
```php
# vytvoření DomQuery z HTML řetězce
$dom = Tester\DomQuery::fromHtml('
<article class="post">
<h1>Title</h1>
<div class="content">Text</div>
</article>
');
# test existence elementů pomocí CSS selektorů
Assert::true($dom->has('article.post'));
Assert::true($dom->has('h1'));
# nalezení elementů jako pole DomQuery objektů
$headings = $dom->find('h1');
Assert::same('Title', (string) $headings[0]);
# test, zda element odpovídá selektoru (od verze 2.5.3)
$content = $dom->find('.content')[0];
Assert::true($content->matches('div'));
Assert::false($content->matches('p'));
# nalezení nejbližšího předka odpovídajícího selektoru (od 2.5.5)
$article = $content->closest('.post');
Assert::true($article->matches('article'));
```
Pro XML dokumenty použijte metodu `fromXml()`:
```php
$dom = Tester\DomQuery::fromXml('<catalog><item>First</item></catalog>');
Assert::true($dom->has('item'));
```
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));
```
Volitelný druhý parametr `$extension` nastaví příponu souboru ve vygenerované URL, což se hodí, když se testovaný kód rozhoduje podle ní:
```php
$file = Tester\FileMock::create('{"key": "value"}', 'json');
```
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 dobu 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í.
Adresář už musí existovat, jinak `lock()` vyhodí výjimku. .{data-version:2.7.0}
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.0}
-----------------------------------------------------------
Vytvoří globální funkce `test()`, `testException()`, `testNoError()`, `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);
```
{{maintitle: Pomocné třídy v Nette Tester: HttpAssert, DomQuery, FileMock}}
{{description: Pomocné třídy pro testy v PHP: HttpAssert pro testování HTTP odpovědí, DomQuery pro dotazy do HTML, FileMock pro falešné soubory a příprava prostředí.}}
Pomocné třídy
HttpAssert
Třída Tester\HttpAssert slouží k testování HTTP serveru. Umožňuje jednoduše provádět HTTP požadavky a
ověřovat jejich stavové kódy, hlavičky i obsah odpovědi pomocí fluent interface.
# Základní HTTP požadavek a ověření odpovědi
$response = Tester\HttpAssert::fetch('https://example.com/api/users');
$response
->expectCode(200)
->expectHeader('Content-Type', contains: 'json')
->expectBody(contains: 'users');
Metoda fetch() standardně vytváří GET požadavek, ale všechny parametry lze přizpůsobit:
HttpAssert::fetch(
'https://api.example.com/users',
method: 'POST',
headers: [
'Authorization' => 'Bearer token123', # asociativní pole
'Accept: application/json', # nebo string formát
],
cookies: ['session' => 'abc123'],
follow: false, # nesledovat redirecty
body: '{"name": "John"}',
timeout: 10, # v sekundách, výchozí je 30
)
->expectCode(201);
Pokud server neodpoví v čase daném parametrem timeout, požadavek skončí výjimkou a
test selže. Server, který přestal odpovídat, tak vaše testy nezablokuje navždy.
Stavové kódy můžete ověřovat metodami expectCode() a denyCode(). Jako parametr předáte buď
konkrétní číslo, nebo validační funkci:
$response
->expectCode(200) # přesný kód
->expectCode(fn($code) => $code < 400) # vlastní validace
->denyCode(404) # nesmí být 404
->denyCode(fn($code) => $code >= 500); # nesmí být chyba serveru
Pro práci s hlavičkami slouží metody expectHeader() a denyHeader(). Můžete kontrolovat
existenci hlavičky, její přesnou hodnotu nebo jen část obsahu:
$response
->expectHeader('Content-Type') # hlavička musí existovat
->expectHeader('Content-Type', 'application/json') # přesná hodnota
->expectHeader('Content-Type', contains: 'json') # obsahuje text
->expectHeader('Server', matches: 'nginx %a%') # odpovídá vzoru
->denyHeader('X-Powered-By') # hlavička nesmí existovat
->denyHeader('X-Debug', contains: 'sensitive') # nesmí obsahovat text
->denyHeader('X-Debug', matches: '~debug~i'); # nesmí odpovídat vzoru
Obdobně funguje ověřování těla odpovědi prostřednictvím metod expectBody() a denyBody():
$response
->expectBody('OK') # přesná hodnota
->expectBody(contains: '"status": "success"') # obsahuje část JSON
->expectBody(matches: '%A% hello %A%') # odpovídá vzoru
->expectBody(fn($body) => json_decode($body) !== null) # vlastní validace
->denyBody('Error occurred') # nesmí mít přesnou hodnotu
->denyBody(contains: 'error') # nesmí obsahovat text
->denyBody(matches: '~exception|fatal~i'); # nesmí odpovídat vzoru
Parametr follow řídí, jak HttpAssert zachází s HTTP přesměrováními:
# Testování redirectu bez následování (výchozí)
HttpAssert::fetch('https://example.com/redirect', follow: false)
->expectCode(301)
->expectHeader('Location', 'https://example.com/new-url');
# Následování všech redirectů až do konečné odpovědi
HttpAssert::fetch('https://example.com/redirect', follow: true)
->expectCode(200)
->expectBody(contains: 'final content');
DomQuery
Tester\DomQuery je třída rozšiřující SimpleXMLElement o snadné vyhledávání v HTML nebo
XML pomocí CSS selektorů.
# vytvoření DomQuery z HTML řetězce
$dom = Tester\DomQuery::fromHtml('
<article class="post">
<h1>Title</h1>
<div class="content">Text</div>
</article>
');
# test existence elementů pomocí CSS selektorů
Assert::true($dom->has('article.post'));
Assert::true($dom->has('h1'));
# nalezení elementů jako pole DomQuery objektů
$headings = $dom->find('h1');
Assert::same('Title', (string) $headings[0]);
# test, zda element odpovídá selektoru (od verze 2.5.3)
$content = $dom->find('.content')[0];
Assert::true($content->matches('div'));
Assert::false($content->matches('p'));
# nalezení nejbližšího předka odpovídajícího selektoru (od 2.5.5)
$article = $content->closest('.post');
Assert::true($article->matches('article'));
Pro XML dokumenty použijte metodu fromXml():
$dom = Tester\DomQuery::fromXml('<catalog><item>First</item></catalog>');
Assert::true($dom->has('item'));
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í:
# 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));
Volitelný druhý parametr $extension nastaví příponu souboru ve vygenerované URL, což se hodí, když se
testovaný kód rozhoduje podle ní:
$file = Tester\FileMock::create('{"key": "value"}', 'json');
Assert::with()
Nejde o aserci, ale pomocníka pro testování privátních metod a property objektů.
class Entity
{
private $enabled;
// ...
}
$ent = new Entity;
Assert::with($ent, function () {
Assert::true($this->enabled); // zpřístupněná privátní $ent->enabled
});
Helpers::purge()
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:
@mkdir(__DIR__ . '/tmp'); # @ - adresář již může existovat
define('TempDir', __DIR__ . '/tmp/' . getmypid());
Tester\Helpers::purge(TempDir);
Environment::lock()
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 dobu běhu do databáze nesahal. V těchto testech
použijeme Tester\Environment::lock($name, $dir):
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í.
Adresář už musí existovat, jinak lock() vyhodí výjimku.
Environment::bypassFinals()
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.
require __DIR__ . '/bootstrap.php';
Tester\Environment::bypassFinals();
class MyClass extends NormallyFinalClass # <-- NormallyFinalClass už není final
{
// ...
}
Environment::setup()
- 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()
Vytvoří globální funkce test(), testException(), testNoError(), setUp()
a tearDown(), do kterých můžete členit testy.
test('popis testu', function () {
Assert::same(123, foo());
Assert::false(bar());
// ...
});
Environment::VariableRunner
Umožní zjistit, zda byl test puštěn přímo, anebo pomocí Testeru.
if (getenv(Tester\Environment::VariableRunner)) {
# spuštěno Testerem
} else {
# spuštěno jinak
}
Environment::VariableThread
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í:
echo "Běžím ve vlákně číslo " . getenv(Tester\Environment::VariableThread);