Nette Documentation Preview

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

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

Note: No php.ini is used.
PHP 8.3.2 (cli) | php -n | 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ý.

.[warning]
Tester spouští PHP procesy bez `php.ini`. Detailněji v části [#Vlastní php.ini].


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

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.
    -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.
    -j <num>                     Run <num> jobs in parallel (default: 8).
    -o <console|console-lines|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.
    -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.
\--


-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]
-------------------
Určuje, který `php.ini` se bude používat při spouštění testů. Ve výchozím stavu se žádný php.ini nepoužije. Více v části [#Vlastní php.ini].


-C .[filter]
------------
Použije se systémové `php.ini`. Na UNIXu také všechny příslušné INI soubory `/etc/php/{sapi}/conf.d/*.ini`. 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.


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


''-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
\--


''-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, ...
\--


--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 PHP 7 s PHPDBG SAPI, které je rychlejší. Přípona cílového souboru určuje jeho formát. Buď HTML anebo 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í. Pokud sběr dat neprobíhá, nebo je použit Xdebug, volání nemá žádný efekt.

"Ukázka HTML reportu":https://files.nette.org/tester/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
===============
Tester spouští PHP procesy s parametrem `-n`, což znamená, že žádné `php.ini` není načteno. V UNIXu ani ty z `/etc/php/conf.d/*.ini`. To zajistí shodné prostředí pro běh testů, ale také vyřadí všechna PHP rozšíření běžně načtená systémovým PHP.

Chcete-li načítání systémových php.ini souborů zachovat, použijte parametr `-C`.

Pokud nějaká rozšíření nebo speciální INI nastavení pro testy potřebujete, doporučujeme vytvoření vlastního `php.ini` souboru, 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
```

Spuštění Testeru v UNIXu se systémovým `php.ini`, například `tester -c /etc/php/cli/php.ini` nenačte ostatní INI z `/etc/php/conf.d/*.ini`. To je vlastnost PHP, ne Testeru.

Spouštění testů

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:

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, aby věděl, které z nich a jak spouštět.

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

  • . – test prošel
  • s – test byl přeskočen (skipped)
  • F – test selhal (failed)

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

 _____ ___  ___ _____ ___  ___
|_   _/ __)( __/_   _/ __)| _ )
  |_| \___ /___) |_| \___ |_|_\  v2.5.2

Note: No php.ini is used.
PHP 8.3.2 (cli) | php -n | 8 threads

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

OK (35 tests, 1 skipped, 1.7 seconds)

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

Tester spouští PHP procesy bez php.ini. Detailněji v části Vlastní php.ini.

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:

 _____ ___  ___ _____ ___  ___
|_   _/ __)( __/_   _/ __)| _ )
  |_| \___ /___) |_| \___ |_|_\  v2.5.2

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.
    -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.
    -j <num>                     Run <num> jobs in parallel (default: 8).
    -o <console|console-lines|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.
    -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.

-p <path>

Určuje PHP binárku, která se bude používat pro spouštění testů. Standardně je to php.

tester -p /home/user/php-7.2.0-beta/php-cgi tests

-c <path>

Určuje, který php.ini se bude používat při spouštění testů. Ve výchozím stavu se žádný php.ini nepoužije. Více v části Vlastní php.ini.

-C

Použije se systémové php.ini. Na UNIXu také všechny příslušné INI soubory /etc/php/{sapi}/conf.d/*.ini. Více v části Vlastní php.ini.

-d <key=value>

Nastavuje hodnotu PHP konfigurační direktivy pro testy. Parametr může být použit vícekrát.

tester -d max_execution_time=20

-s

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

--stop-on-fail

Tester zastaví testování u prvního selhávajícího testu.

-j <num>

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|tap|junit|log|none>

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
  • tap: TAP formát 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

-w | --watch <path>

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

tester --watch src tests

-i | --info

Zobrazí informace o běhovém prostředí pro testy. Například:

tester -p /usr/bin/php7.1 -c tests/php.ini --info

PHP binary:
/usr/bin/php7.1

PHP version:
7.1.7-1+0~20170711133844.5+jessie~1.gbp5284f4 (cli)

Code coverage engines:
(not available)

Loaded php.ini files:
/var/www/dev/demo/tests/php.ini

PHP temporary directory:
/tmp

Loaded extensions:
Core, ctype, date, dom, ereg, fileinfo, filter, hash, ...

--setup <path>

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:

$runner->outputHandlers[] = new MyOutputHandler;

Tester spustíme:

tester --setup tests/runner-setup.php tests

--temp <path>

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

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>

Tester vygeneruje report s přehledem, kolik zdrojového kódu testy pokrývají. Tato volba vyžaduje instalované PHP rozšíření Xdebug, nebo PCOV, anebo PHP 7 s PHPDBG SAPI, které je rychlejší. Přípona cílového souboru určuje jeho formát. Buď HTML anebo Clover XML.

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í. Pokud sběr dat neprobíhá, nebo je použit Xdebug, volání nemá žádný efekt.

Ukázka HTML reportu s pokrytím kódu.

--coverage-src <path>

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

Tester spouští PHP procesy s parametrem -n, což znamená, že žádné php.ini není načteno. V UNIXu ani ty z /etc/php/conf.d/*.ini. To zajistí shodné prostředí pro běh testů, ale také vyřadí všechna PHP rozšíření běžně načtená systémovým PHP.

Chcete-li načítání systémových php.ini souborů zachovat, použijte parametr -C.

Pokud nějaká rozšíření nebo speciální INI nastavení pro testy potřebujete, doporučujeme vytvoření vlastního php.ini souboru, 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:

[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M

Spuštění Testeru v UNIXu se systémovým php.ini, například tester -c /etc/php/cli/php.ini nenačte ostatní INI z /etc/php/conf.d/*.ini. To je vlastnost PHP, ne Testeru.