Spouštění testů
***************

.[perex]
Nejviditelnější součástí Nette Testeru je spouštěč testů z příkazové řádky. Je neobyčejně rychlý a robustní, neboť automaticky spouští všechny testy jako samostatné procesy, a to paralelně ve více vláknech. Také se umí spouštět sám v tzv. watch režimu.

Spouštěč testů voláme z příkazové řádky. Jako parametr uvedeme adresář s testy. Pro aktuální adresář stačí zadat tečku:

/--pre .[terminal]
vendor/bin/tester .
\--

Spouštěč testů prohledá zadaný adresář a všechny podadresáře a vyhledá testy, což jsou soubory `*.phpt` a `*Test.php`. Zároveň čte a vyhodnocuje jejich [anotace|test-annotations], aby věděl, které z nich a jak spouštět.

Každý testovací soubor běží ve vlastním izolovaném PHP procesu a spouštěč jich několik zpracovává najednou - jednotkou paralelismu je tedy soubor. Kód uvnitř jednoho souboru proto běží sekvenčně. [TestCase |TestCase] je jeden soubor, takže jeho metody se ve výchozím stavu vykonávají jedna po druhé v rámci jediného procesu; anotací [@testCase |test-annotations#testCase] docílíte toho, že spouštěč spustí každou testovací metodu jako samostatný paralelní proces.

Poté spustí testy. Během provádění testů vypisuje průběžně výsledky na terminál jako znaky:

- <code style="color: #CCC; background-color: #000">.</code> - test prošel
- <code style="color: #CCC; background-color: #000">s</code> - test byl přeskočen (skipped)
- <code style="color: #FFF; background-color: #900">F</code> - test selhal (failed)

Výstup může vypadat třeba takto:

/--pre .[terminal]
 _____ ___  ___ _____ ___  ___
|_   _/ __)( __/_   _/ __)| _ )
  |_| \___ /___) |_| \___ |_|_\  v2.7.1

PHP 8.5.2 (cli) | php | 8 threads

........s..........................

<span style="color: #FFF; background-color: #090">OK (35 tests, 1 skipped, 1.7 seconds)</span>
\--

Při opakovaném spuštění nejprve provádí testy, které při předchozím běhu selhaly, takže se okamžitě dozvíte, jestli se vám chybu podařilo opravit.

Pokud žádný test neselže, návratový kód Testeru je nula. Jinak je návratový kód nenulový.

Pokud Tester nenajde vůbec žádný test, třeba kvůli překlepu v cestě, skončí také nenulovým kódem. Build na CI serveru tak nemůže projít, aniž by se cokoli otestovalo. .{data-version:2.7.0}


Parametry příkazové řádky
=========================

Přehled všech voleb příkazové řádky získáme spuštěním Testeru bez parametrů, anebo s parametrem `-h`:

/--pre .[terminal]
 _____ ___  ___ _____ ___  ___
|_   _/ __)( __/_   _/ __)| _ )
  |_| \___ /___) |_| \___ |_|_\  v2.7.1

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.
    --version                    Show version and exit.
\--


-p <path> .[filter]
-------------------
Určuje PHP binárku, která se bude používat pro spouštění testů. Standardně je to `php`.

/--pre .[terminal]
tester -p /home/user/php-7.2.0-beta/php-cgi tests
\--


-c <path> .[filter]
-------------------
Použije vlastní `php.ini` soubor a ignoruje systémovou konfiguraci. Více v části [#Vlastní php.ini].


-C .[filter]
------------
Při použití společně s `-c` zachová i systémovou konfiguraci (neignoruje ji). Více v části [#Vlastní php.ini].


-d <key=value> .[filter]
------------------------
Nastavuje hodnotu PHP konfigurační direktivy pro testy. Parametr může být použit vícekrát.

/--pre .[terminal]
tester -d max_execution_time=20
\--


-s
---
Zobrazí se informace o přeskočených testech.


--stop-on-fail .[filter]
------------------------
Tester zastaví testování u prvního selhávajícího testu.


--timeout <seconds> .[filter]{data-version:2.7.0}
-------------------------------------------------
Nastaví časový limit v sekundách pro každý test. Bez něj test, který se zasekne, třeba když čeká na server, který nikdy neodpoví, nebo uvízne v nekonečné smyčce, nechá čekat celé testování. Na CI serveru to znamená úlohu, která skončí, až když ji server sám ukončí, a vy se nedozvíte, který test za to mohl.

S časovým limitem Tester po vypršení času proces testu ukončí, test označí jako selhaný a pokračuje s ostatními:

/--pre .[terminal]
tester --timeout 30 tests
\--

Ve výpisu chyb pak uvidíte, který test se zasekl:

/--pre .[terminal]
-- FAILED: database.phpt
   Timed out after 30 s
\--

Ve výchozím stavu testy žádný časový limit nemají. Jednotlivý test si může nastavit vlastní limit, nebo ho vypnout, anotací [@timeout |test-annotations#timeout].


-j <num> .[filter]
------------------
Určuje, kolik paralelních procesů s testy se spustí. Výchozí hodnota je 8. Chceme-li, aby všechny testy proběhly v sérii, použijeme hodnotu 1.


-o <console|console-lines|github|tap|junit|log|none> .[filter]
--------------------------------------------------------------
Nastaví formát výstupu. Výchozí je formát pro konzoli. Můžete uvést jméno souboru, do kterého se výstup zapíše (např. `-o junit:output.xml`). Volbu `-o` lze zopakovat vícekrát a vygenerovat tak více formátů najednou.

- `console`: shodné s výchozím formátem, ale v tomto případě se nezobrazí ASCII logo
- `console-lines`: podobné jako console, ale výsledek každého testu je uveden na samostatném řádku s dalšími informacemi
- `github`: anotace pro [GitHub Actions |https://docs.github.com/en/actions], díky kterým se selhaný test zobrazí v pull requestu přímo u řádku, kde selhal, i s chybovou hláškou .{data-version:2.7.0}
- `tap`: [TAP formát |https://en.wikipedia.org/wiki/Test_Anything_Protocol] vhodný pro strojové zpracování
- `junit`: XML formát JUnit, taktéž vhodný pro strojové zpracování
- `log`: Výstupy průběhu testování. Všechny neúspěšné, přeskočené a také úspěšné testy
- `none`: nic se nevypisuje

Když Tester běží na GitHub Actions, přidá formát `github` sám. V běžném workflow tak nemusíte nic nastavovat a selhané testy uvidíte v pull requestu hned, přičemž výstup do konzole zůstává jako obvykle. Pokud formát standardního výstupu zvolíte sami přes `-o`, například `-o tap`, Tester to respektuje a anotace nepřidá, aby se oba výstupy nesmíchaly. .{data-version:2.7.0}


''-w | --watch <path>'' .[filter]
---------------------------------
Po dokončení testování Tester neskončí, ale zůstane běžet a sleduje PHP soubory v uvedeném adresáři. Při změně spustí testy znova. Parametr může být použit vícekrát, pokud chceme sledovat více adresářů.

Hodí se při refactoringu knihovny nebo ladění testů.

/--pre .[terminal]
tester --watch src tests
\--


''--slowest [<count>]'' .[filter]{data-version:2.7.0}
-----------------------------------------------------
Po dokončení testů vypíše nejpomalejší testy a jak dlouho který běžel. Hodí se, když se testování začne zpomalovat a chcete vědět, kterým testům se věnovat nejdřív. Ve výchozím stavu jich vypíše 10, jiný počet můžete uvést za volbou:

/--pre .[terminal]
tester --slowest 3 tests

...

Slowest tests:
· database.phpt in 1.049 s
· mail.phpt in 0.475 s
· form.phpt in 0.089 s
\--


''-i | --info'' .[filter]
-------------------------
Zobrazí informace o běhovém prostředí pro testy. Například:

/--pre .[terminal]
tester -p /usr/bin/php7.1 -c tests/php.ini --info

<span style="color: #0F0">PHP binary:</span>
/usr/bin/php7.1

<span style="color: #0F0">PHP version:</span>
7.1.7-1+0~20170711133844.5+jessie~1.gbp5284f4 (cli)

<span style="color: #0F0">Code coverage engines:</span>
(not available)

<span style="color: #0F0">Loaded php.ini files:</span>
/var/www/dev/demo/tests/php.ini

<span style="color: #0F0">PHP temporary directory:</span>
/tmp

<span style="color: #0F0">Loaded extensions:</span>
Core, ctype, date, dom, ereg, fileinfo, filter, hash, ...
\--


''--version'' .[filter]{data-version:2.7.1}
-------------------------------------------
Vypíše jen verzi Testeru, například `Nette Tester 2.7.1`, a skončí. Na rozdíl od úvodního banneru se tento výstup snadno zpracuje ve skriptech.


--setup <path> .[filter]
------------------------
Tester při startu načte zadaný PHP skript. V něm je k dispozici proměnná `Tester\Runner\Runner $runner`. Předpokládejme soubor `tests/runner-setup.php` s obsahem:

```php
$runner->outputHandlers[] = new MyOutputHandler;
```

Tester spustíme:

/--pre .[terminal]
tester --setup tests/runner-setup.php tests
\--


--temp <path> .[filter]
-----------------------
Nastaví cestu k adresáři pro dočasné soubory Testeru. Výchozí hodnotu vrací `sys_get_temp_dir()`. Není-li výchozí hodnota validní, budete upozorněni.

Pokud si nejsme jisti, jaký adresář se používá, spustíme Tester s parametrem `--info`.


--colors 1|0 .[filter]
----------------------
Ve výchozím stavu Tester detekuje barevný terminál a obarvuje svůj výstup. Tato volba autodetekci přebíjí. Globálně můžeme obarvování nastavit systémovou proměnnou prostředí `NETTE_TESTER_COLORS`.


--coverage <path> .[filter]
---------------------------
Tester vygeneruje report s přehledem, kolik zdrojového kódu testy pokrývají. Tato volba vyžaduje instalované PHP rozšíření [Xdebug |https://xdebug.org/], nebo [PCOV |https://github.com/krakjoe/pcov], anebo PHPDBG SAPI, které je rychlejší. Přípona cílového souboru určuje jeho formát. Buď HTML, nebo Clover XML.

/--pre .[terminal]
tester tests --coverage coverage.html  # HTML report
tester tests --coverage coverage.xml   # Clover XML report
\--

Priorita výběru mechanismu je následující:
1) PCOV
2) PHPDBG
3) Xdebug

Při použití PHPDBG můžeme u obsáhlých testů narazit na selhání testu kvůli vyčerpání paměti. Sběr informací o pokrytém kódu je paměťově náročný. V tomto případě nám pomůže volání `Tester\CodeCoverage\Collector::flush()` uvnitř testu. Zapíše nasbíraná data na disk a paměť uvolní. Volání má efekt jen s enginem PHPDBG; při PCOV, Xdebugu nebo když sběr dat neprobíhá, je bez efektu.

"Ukázka HTML reportu":attachment:coverage.html s pokrytím kódu.


--coverage-src <path> .[filter]
-------------------------------
Použijeme současně s volbou `--coverage`. `<path>` je cesta ke zdrojovým kódům, pro které se report generuje. Může se použít opakovaně.


Vlastní php.ini
===============
Pro testy můžete použít vlastní `php.ini` soubor. Pokud potřebujete specifická rozšíření nebo speciální INI nastavení, doporučujeme vytvořit vlastní `php.ini`, který bude distribuován s testy. Tester pak spouštíme s parametrem `-c`, například `tester -c tests/php.ini tests`, kde INI soubor může vypadat takto:

```ini
[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M
```

Při použití `-c` Tester **ignoruje systémovou konfiguraci** (spouští PHP s příznakem `-n`). Chcete-li zachovat i systémovou konfiguraci, přidejte volbu `-C`: `tester -c tests/php.ini -C tests`. Ani při kombinaci `-c` a `-C` se nenačtou v UNIXu ostatní INI soubory z `/etc/php/conf.d/*.ini`. To je vlastnost PHP, ne Testeru.

.[note]
Do verze 2.6 Tester bez uvedení `-c` spouštěl PHP s parametrem `-n`, tedy bez php.ini; volba `-C` toto potlačila. Od verze 2.6 se systémové php.ini načítá automaticky. Chování při použití `-c` zůstává stejné.

{{maintitle: Spouštění testů v Nette Tester: příkazová řádka a parametry}}
{{description: Spouštěč testů Nette Tester pouští každý test jako samostatný proces, paralelně ve více vláknech. Všechny parametry, watch režim a vlastní php.ini.}}