tester restruct

tester/cs/@menu.texy

@@ -1,4 +1,5 @@
 - [Úvod |homepage]
-- [Přehled |overview]
-- [Dokumentace |documentation]
+- [Průvodce |guide]
+- [Psaní testů |writing-tests]
+- [Spouštení testů |running-tests]
 - [GitHub |https://github.com/nette/tester]

tester/cs/overview.texy → tester/cs/guide.texy

@@ -74,25 +74,17 @@ Tester spouštíme z příkazové řádky. Zkusme to, bez parametrů pouze vypí
 
 /--
 cd demo
-php vendor/nette/tester/src/tester.php  # při instalaci Composerem
-php tester/src/tester.php               # při ruční instalaci
+vendor/bin/tester            # při instalaci Composerem pod UNIX
+vendor\bin\tester            # při instalaci Composerem pod Windows
+php tester/src/tester.php    # při ruční instalaci
 \--
 
-Při použití Composeru doporučujeme spouštění ještě snadnější:
-
-/--
-cd demo
-vendor/bin/tester      # UNIX
-vendor\bin\tester.bat  # Windows
-\--
-
-.[note]
 Pro zjednodušení budeme dále uvádět pouze příkaz **tester**. Ke spuštění je ale nutné použít jeden z výše popsaných způsobů s úplnou cestou.
 
 
 
-Spouštíme testy
-===============
+Píšeme testy
+============
 Naše aplikace zatím žádné testy nemá. Vytvoříme jednoduchou třídu, kterou budeme testovat, a umístíme ji do souboru `src/Greeting.php`
 
 /--php
@@ -146,7 +138,7 @@ cd tests
 php greeting.phpt
 \--
 
-Test jsme spustili jako běžný PHP skript. Ikdyž se to zdá jako maličkost, je v tom ukryt velký potenciál. Test můžeme krokovat v IDE anebo načíst přes webový prohlížeč.
+Test jsme spustili jako běžný PHP skript. I když se to zdá jako maličkost, je v tom ukryt velký potenciál. Test můžeme krokovat v IDE anebo načíst přes webový prohlížeč.
 
 První spuštění nám odhalí syntaktické chyby a pokud jsme nikde neudělali překlep, test skončí bez chyby. Zkusme v testu změnit tvrzení na `Assert::same('Hi John', $o->say('John'));` a sledujme, co se při spuštění stane.
 
@@ -174,7 +166,7 @@ Tester projde zadané adresáře, vytvoří si seznam nalezených testů a potom
 Tester vyhledává `*.phpt` a `*Test.php` soubory. Jako první spouští testy, které při předchozím běhu selhaly.
 
 .[warning]
-Tester spouští PHP procesy s parametrem **-n**, tedy bez **php.ini**. Detailněji v kapitole [documentation#Vlastní php.ini].
+Tester spouští PHP procesy s parametrem **-n**, tedy bez **php.ini**. Detailněji v kapitole [running-tests#Vlastní php.ini].
 
 
 Vyhodnocení testů
@@ -221,28 +213,6 @@ V testech bylo zmíněno trochu tajemné `Tester\Environment::setup()` volání.
 Použití je volitelné, ale doporučované.
 
 
-Environment::RUNNER
--------------------
-Může být užitečné vědět, jestli jsme test spustili ručně, anebo pomocí Testeru.
-
-/--php
-if (getenv(Tester\Environment::RUNNER)) {
-	# spuštěno Testerem
-} else {
-	# spuštěno jinak
-}
-\--
-
-
-Environment::THREAD
--------------------
-Dále se dozvíme, že 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::THREAD).
-\--
-
-
 Adresářová struktura
 ====================
 Může se zdát předčasné o tom hovořit, ale dobře strukturované adresáře s testy ušetří hodně práce. Testy rozdělíme do podadresářů podle jmenného prostoru testované třídy:

tester/cs/running-tests.texy

@@ -0,0 +1,191 @@
+Spouštění testů
+***************
+
+Tester spouštíme z příkazové řádky. Bez parametrů pouze vypíše nápovědu.
+
+/--
+vendor/bin/tester      # UNIX
+vendor\bin\tester      # Windows
+\--
+
+Pro zjednodušení budeme dále uvádět pouze příkaz **tester**. Ke spuštění je ale nutné použít jeden z výše popsaných způsobů s úplnou cestou.
+
+Jako parametr uvedeme adresář s testy. Pro aktuální adresář stačí zadat tečku:
+
+/--
+tester .
+\--
+
+Tester projde adresář a podadresáře, vytvoří si seznam nalezených testů a potom je provádí. Každý test spustí jako nový PHP proces, každý test tak probíhá zcela izolovaně od ostatních.
+
+.[tip]
+Tester vyhledává `*.phpt` a `*Test.php` soubory. Jako první spouští testy, které při předchozím běhu selhaly.
+
+.[warning]
+Tester spouští PHP procesy s parametrem **-n**, tedy bez **php.ini**. Detailněji v kapitole [#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`.
+
+-p <path>
+---------
+Pro spouštění testů použije Tester tuto PHP binárku:
+
+/--
+tester -p /home/user/php-7.2.0-beta/php-cgi tests
+\--
+
+
+-c <path>
+---------
+Volba je stejná jako pro PHP binárku. Pro testy bude použit zadaný **php.ini**. Ve výchozím stavu se žádný php.ini nepoužije. Příklad, kdy distribuujeme php.ini s testy:
+
+/--
+tester -c tests/php.ini tests
+\--
+
+
+-C
+---
+Použije se systémové **php.ini**. Na UNIXu také všechny příslušné INI soubory `/etc/php/{sapi}/conf.d/*.ini`.
+
+
+-l | --log <path>
+-----------------
+Do souboru bude zapsán průběh testování. Všechny selhané, přeskočené, ale i úspěšné testy:
+
+/--
+tester --log /var/log/tests.log tests
+\--
+
+
+-d <key=value>
+--------------
+Volba je stejná jako pro PHP binárku. Pro testy definuje INI hodnotu. Parametr může být použit vícekrát.
+
+
+-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|tap|junit|none>
+---------------------------
+Nastaví formát výstupu. Výchozí je formát pro konzoli.
+
+- `console`: shodné s výchozím formátem, ale v tomto případě se nezobrazí ASCII logo
+- `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í
+- `none`: nic se nevypisuje
+
+
+-w | --watch <path>
+-------------------
+Po dokončení testování Tester neskončí, ale zůstane běžet a sleduje zadaný adresář. Při změně spustí testy znova. Parametr může být použit vícekrát. Hodí se při tvorbě a ladění testů.
+
+
+-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)
+
+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:
+
+/--php
+$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í hodnota podle `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 |http://xdebug.org/], 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
+\--
+
+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>
+---------------------
+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**, žádné **php.ini** není načteno. V UNIXu ani ty z `/etc/php/conf.d/*.ini`. To zajistí co nejčistší 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
+\--
+
+.[note]
+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.
+
+{{composer: nette/tester}}