Nette Documentation Preview

syntax 
Przeprowadzanie testów
**********************

.[perex]
Najbardziej widoczną częścią Nette Tester jest uruchamianie testów z linii poleceń. Jest on niezwykle szybki i wytrzymały, ponieważ automatycznie uruchamia wszystkie testy jako osobne procesy równolegle w wielu wątkach. Może też uruchamiać się sam w tzw. trybie watch.

Test runner Nette Tester jest wywoływany z linii poleceń. Jako parametr przekazujemy katalog z testami. Dla katalogu bieżącego wystarczy wpisać kropkę:

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

Po wywołaniu, test runner skanuje podany katalog i wszystkie podkatalogi i szuka testów, którymi są pliki `*.phpt` i `*Test.php`. Czyta również i ocenia ich [adnotacje |test-annotations], aby wiedzieć, które z nich i jak uruchomić.

Następnie wykonuje testy. Dla każdego wykonanego testu, runner drukuje jeden znak, aby wskazać postęp:

- <code style="color: #CCC; background-color: #000">.</code> - test przeszedł
- <code style="color: #CCC; background-color: #000">s</code> - test został pominięty
- <code style="color: #FFF; background-color: #900">F</code> - test nie powiódł się

Dane wyjściowe mogą wyglądać jak:

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

Kiedy uruchomisz go ponownie, najpierw uruchamia on testy, które nie powiodły się podczas poprzedniego uruchomienia, więc od razu będziesz wiedział, czy naprawiłeś błąd.

Kod wyjścia testera jest zerowy, jeśli żaden z nich się nie powiódł. W przeciwnym razie niezerowy.

.[warning]
Tester uruchamia procesy PHP bez `php.ini`. Więcej szczegółów w sekcji [Własny php.ini |#Own php.ini].


Opcje wiersza poleceń .[#toc-command-line-options]
==================================================

Przegląd opcji wiersza poleceń uzyskujemy uruchamiając Tester bez parametrów lub z opcją `-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> (np. -o junit:output.xml)
                                 Określa jeden lub więcej formatów wyjściowych z opcjonalną nazwą pliku.
    -w | --watch <path>          Watch directory.
    -i | --info                  Show tests environment info and exit.
    --setup <path>               Script for runner setup.
    --temp <path>                Ścieżka do katalogu tymczasowego. Domyślna przez 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]
-------------------
Określa binarkę PHP, która będzie używana do uruchamiania testów. Domyślnie jest to `php`.

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


-c <path> .[filter]
-------------------
Określa, która strona `php.ini` będzie używana podczas uruchamiania testów. Domyślnie, nie jest używany żaden php.ini. Zobacz [Własne php.ini |#Own php.ini], aby uzyskać więcej informacji.


-C .[filter]
------------
Używany jest ogólnosystemowy `php.ini`. Czyli na platformie UNIX wszystkie pliki `/etc/php/{sapi}/conf.d/*.ini` również. Patrz rozdział [Własny php.ini |#Own php.ini].


-d <key=value> .[filter]
------------------------
Ustawia wartość dyrektywy konfiguracyjnej PHP dla testów. Parametr może być użyty wielokrotnie.

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


-s
---
Zostanie wyświetlona informacja o pominiętych testach.


--stop-on-fail .[filter]
------------------------
Tester zatrzymuje testowanie po pierwszym nieudanym teście.


-j <num> .[filter]
------------------
Testy są uruchamiane w `<num>` równoległych procesach. Domyślna wartość to 8. Jeśli chcemy uruchamiać testy szeregowo, używamy wartości 1.


-o <console|console-lines|tap|junit|log|none> .[filter]
-------------------------------------------------------
Format wyjścia. Domyślnie jest to format konsolowy. Można określić nazwę pliku, do którego zostaną zapisane dane wyjściowe (np. `-o junit:output.xml`). Opcja `-o` może być powtarzana wielokrotnie w celu wygenerowania wielu formatów jednocześnie.

- `console`: taki sam jak domyślny, ale w tym przypadku nie jest wypisywane logo ASCII
- `console-lines`: podobny do konsoli, ale wynik każdego testu jest wyświetlany w osobnym wierszu z większą ilością informacji
- `tap`: [format TAP |https://en.wikipedia.org/wiki/Test_Anything_Protocol] odpowiedni do przetwarzania maszynowego
- `junit`: format JUnit XML, odpowiedni również do przetwarzania maszynowego
- `log`: Wyświetla postęp testowania. Wszystkie nieudane, pominięte, a także udane testy
- `none`: nic nie jest drukowane


''-w | --watch <path>'' .[filter]
---------------------------------
Tester nie kończy pracy po zakończeniu testów, ale cały czas uruchamia i obserwuje pliki PHP w danym katalogu. W przypadku zmiany, uruchamia testy ponownie. Parametr może być użyty wielokrotnie, jeśli chcemy monitorować wiele katalogów.

Jest to przydatne podczas refaktoryzacji biblioteki lub debugowania testów.

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


''-i | --info'' .[filter]
-------------------------
Pokazuje informacje o środowisku uruchomionego testu. Na przykład:

/--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 przy starcie ładuje podany skrypt PHP. Dostępna jest w nim zmienna `Tester\Runner\Runner $runner`. Załóżmy, że plik `tests/runner-setup.php`:

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

i uruchamiamy Tester:

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


--temp <path> .[filter]
-----------------------
Ustawia ścieżkę do katalogu dla plików tymczasowych Testera. Domyślna wartość jest zwracana przez `sys_get_temp_dir()`. Gdy wartość domyślna nie jest prawidłowa, zostaniesz o tym poinformowany.

Jeśli nie jesteśmy pewni, który katalog jest używany, możemy uruchomić Tester z parametrem `--info`.


--colors 1|0 .[filter]
----------------------
Tester domyślnie wykrywa terminal obsługujący kolory i koloruje swoje wyjście. Ta opcja jest nad autodetekcją. Możemy ustawić kolorowanie globalnie przez systemową zmienną środowiskową `NETTE_TESTER_COLORS`.


--coverage <path> .[filter]
---------------------------
Tester wygeneruje raport z przeglądem tego, jak bardzo kod źródłowy jest pokryty przez testy. Opcja ta wymaga włączonego rozszerzenia PHP [Xdebug |https://xdebug.org/] lub [PCOV |https://github.com/krakjoe/pcov], albo PHP 7 z PHPDBG SAPI, które jest szybsze. Rozszerzenie pliku docelowego określa format zawartości. HTML lub Clover XML.

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

Priorytet wyboru mechanizmu zbierania jest następujący:
1) PCOV
2) PHPDBG
3) Xdebug

Rozległe testy mogą się nie powieść podczas uruchamiania przez PHPDBG z powodu wyczerpania pamięci. Zbieranie danych o pokryciu jest operacją zużywającą pamięć. W takim przypadku, wywołanie `Tester\CodeCoverage\Collector::flush()` wewnątrz testu może pomóc. Spłucze ona zebrane dane do pliku i zwolni pamięć. Jeśli zbieranie danych nie jest w toku lub używany jest Xdebug, wywołanie nie ma żadnego efektu.

"Przykład raportu HTML":https://files.nette.org/tester/coverage.html z pokryciem kodu.


--coverage-src <path> .[filter]
-------------------------------
Używamy go jednocześnie z opcją `--coverage`. Opcja `<path>` jest ścieżką do kodu źródłowego, dla którego generujemy raport. Może być używana wielokrotnie.


Własny php.ini .[#toc-own-php-ini]
==================================
Tester uruchamia procesy PHP z opcją `-n`, co oznacza, że nie jest ładowany żaden `php.ini` (nawet ten z `/etc/php/conf.d/*.ini` w UNIX). Zapewnia to to samo środowisko dla uruchamianych testów, ale też dezaktywuje wszystkie zewnętrzne rozszerzenia PHP powszechnie ładowane przez systemowe PHP.

Jeśli chcesz zachować konfigurację systemową, użyj parametru `-C`.

Jeśli potrzebujesz jakichś rozszerzeń lub specjalnych ustawień INI, zalecamy stworzenie własnego pliku `php.ini` i rozesłanie go pomiędzy testami. Następnie uruchamiamy Tester z opcją `-c`, np. `tester -c tests/php.ini`. Plik INI może wyglądać tak:

```ini
[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M
```

Uruchomienie Testera z systemem `php.ini` w systemie UNIX, np. `tester -c /etc/php/cgi/php.ini`, nie wczytuje innych INI z `/etc/php/conf.d/*.ini`. To jest zachowanie PHP, a nie Testera.

Przeprowadzanie testów

Najbardziej widoczną częścią Nette Tester jest uruchamianie testów z linii poleceń. Jest on niezwykle szybki i wytrzymały, ponieważ automatycznie uruchamia wszystkie testy jako osobne procesy równolegle w wielu wątkach. Może też uruchamiać się sam w tzw. trybie watch.

Test runner Nette Tester jest wywoływany z linii poleceń. Jako parametr przekazujemy katalog z testami. Dla katalogu bieżącego wystarczy wpisać kropkę:

vendor/bin/tester .

Po wywołaniu, test runner skanuje podany katalog i wszystkie podkatalogi i szuka testów, którymi są pliki *.phpt i *Test.php. Czyta również i ocenia ich adnotacje, aby wiedzieć, które z nich i jak uruchomić.

Następnie wykonuje testy. Dla każdego wykonanego testu, runner drukuje jeden znak, aby wskazać postęp:

  • . – test przeszedł
  • s – test został pominięty
  • F – test nie powiódł się

Dane wyjściowe mogą wyglądać jak:

 _____ ___  ___ _____ ___  ___
|_   _/ __)( __/_   _/ __)| _ )
  |_| \___ /___) |_| \___ |_|_\  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)

Kiedy uruchomisz go ponownie, najpierw uruchamia on testy, które nie powiodły się podczas poprzedniego uruchomienia, więc od razu będziesz wiedział, czy naprawiłeś błąd.

Kod wyjścia testera jest zerowy, jeśli żaden z nich się nie powiódł. W przeciwnym razie niezerowy.

Tester uruchamia procesy PHP bez php.ini. Więcej szczegółów w sekcji Własny php.ini.

Opcje wiersza poleceń

Przegląd opcji wiersza poleceń uzyskujemy uruchamiając Tester bez parametrów lub z opcją -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> (np. -o junit:output.xml)
                                 Określa jeden lub więcej formatów wyjściowych z opcjonalną nazwą pliku.
    -w | --watch <path>          Watch directory.
    -i | --info                  Show tests environment info and exit.
    --setup <path>               Script for runner setup.
    --temp <path>                Ścieżka do katalogu tymczasowego. Domyślna przez 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>

Określa binarkę PHP, która będzie używana do uruchamiania testów. Domyślnie jest to php.

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

-c <path>

Określa, która strona php.ini będzie używana podczas uruchamiania testów. Domyślnie, nie jest używany żaden php.ini. Zobacz Własne php.ini, aby uzyskać więcej informacji.

-C

Używany jest ogólnosystemowy php.ini. Czyli na platformie UNIX wszystkie pliki /etc/php/{sapi}/conf.d/*.ini również. Patrz rozdział Własny php.ini.

-d <key=value>

Ustawia wartość dyrektywy konfiguracyjnej PHP dla testów. Parametr może być użyty wielokrotnie.

tester -d max_execution_time=20

-s

Zostanie wyświetlona informacja o pominiętych testach.

--stop-on-fail

Tester zatrzymuje testowanie po pierwszym nieudanym teście.

-j <num>

Testy są uruchamiane w <num> równoległych procesach. Domyślna wartość to 8. Jeśli chcemy uruchamiać testy szeregowo, używamy wartości 1.

-o <console|console-lines|tap|junit|log|none>

Format wyjścia. Domyślnie jest to format konsolowy. Można określić nazwę pliku, do którego zostaną zapisane dane wyjściowe (np. -o junit:output.xml). Opcja -o może być powtarzana wielokrotnie w celu wygenerowania wielu formatów jednocześnie.

  • console: taki sam jak domyślny, ale w tym przypadku nie jest wypisywane logo ASCII
  • console-lines: podobny do konsoli, ale wynik każdego testu jest wyświetlany w osobnym wierszu z większą ilością informacji
  • tap: format TAP odpowiedni do przetwarzania maszynowego
  • junit: format JUnit XML, odpowiedni również do przetwarzania maszynowego
  • log: Wyświetla postęp testowania. Wszystkie nieudane, pominięte, a także udane testy
  • none: nic nie jest drukowane

-w | --watch <path>

Tester nie kończy pracy po zakończeniu testów, ale cały czas uruchamia i obserwuje pliki PHP w danym katalogu. W przypadku zmiany, uruchamia testy ponownie. Parametr może być użyty wielokrotnie, jeśli chcemy monitorować wiele katalogów.

Jest to przydatne podczas refaktoryzacji biblioteki lub debugowania testów.

tester --watch src tests

-i | --info

Pokazuje informacje o środowisku uruchomionego testu. Na przykład:

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 przy starcie ładuje podany skrypt PHP. Dostępna jest w nim zmienna Tester\Runner\Runner $runner. Załóżmy, że plik tests/runner-setup.php:

$runner->outputHandlers[] = new MyOutputHandler;

i uruchamiamy Tester:

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

--temp <path>

Ustawia ścieżkę do katalogu dla plików tymczasowych Testera. Domyślna wartość jest zwracana przez sys_get_temp_dir(). Gdy wartość domyślna nie jest prawidłowa, zostaniesz o tym poinformowany.

Jeśli nie jesteśmy pewni, który katalog jest używany, możemy uruchomić Tester z parametrem --info.

--colors 1|0

Tester domyślnie wykrywa terminal obsługujący kolory i koloruje swoje wyjście. Ta opcja jest nad autodetekcją. Możemy ustawić kolorowanie globalnie przez systemową zmienną środowiskową NETTE_TESTER_COLORS.

--coverage <path>

Tester wygeneruje raport z przeglądem tego, jak bardzo kod źródłowy jest pokryty przez testy. Opcja ta wymaga włączonego rozszerzenia PHP Xdebug lub PCOV, albo PHP 7 z PHPDBG SAPI, które jest szybsze. Rozszerzenie pliku docelowego określa format zawartości. HTML lub Clover XML.

tester tests --coverage coverage.html  # HTML report
tester tests --coverage coverage.xml   # Clover XML report

Priorytet wyboru mechanizmu zbierania jest następujący:

  1. PCOV
  2. PHPDBG
  3. Xdebug

Rozległe testy mogą się nie powieść podczas uruchamiania przez PHPDBG z powodu wyczerpania pamięci. Zbieranie danych o pokryciu jest operacją zużywającą pamięć. W takim przypadku, wywołanie Tester\CodeCoverage\Collector::flush() wewnątrz testu może pomóc. Spłucze ona zebrane dane do pliku i zwolni pamięć. Jeśli zbieranie danych nie jest w toku lub używany jest Xdebug, wywołanie nie ma żadnego efektu.

Przykład raportu HTML z pokryciem kodu.

--coverage-src <path>

Używamy go jednocześnie z opcją --coverage. Opcja <path> jest ścieżką do kodu źródłowego, dla którego generujemy raport. Może być używana wielokrotnie.

Własny php.ini

Tester uruchamia procesy PHP z opcją -n, co oznacza, że nie jest ładowany żaden php.ini (nawet ten z /etc/php/conf.d/*.ini w UNIX). Zapewnia to to samo środowisko dla uruchamianych testów, ale też dezaktywuje wszystkie zewnętrzne rozszerzenia PHP powszechnie ładowane przez systemowe PHP.

Jeśli chcesz zachować konfigurację systemową, użyj parametru -C.

Jeśli potrzebujesz jakichś rozszerzeń lub specjalnych ustawień INI, zalecamy stworzenie własnego pliku php.ini i rozesłanie go pomiędzy testami. Następnie uruchamiamy Tester z opcją -c, np. tester -c tests/php.ini. Plik INI może wyglądać tak:

[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M

Uruchomienie Testera z systemem php.ini w systemie UNIX, np. tester -c /etc/php/cgi/php.ini, nie wczytuje innych INI z /etc/php/conf.d/*.ini. To jest zachowanie PHP, a nie Testera.