Nette Documentation Preview

syntax 
Бігові тести
************

.[perex]
Найбільш помітною частиною Nette Tester є запуск тестів з командного рядка. Він надзвичайно швидкий і надійний, оскільки автоматично запускає всі тести як окремі процеси паралельно в декількох потоках. Він також може запускати себе в так званому режимі спостереження.

Запуск тестового бігуна Nette Tester здійснюється з командного рядка. В якості параметра ми передамо директорію тесту. Для поточного каталогу просто введіть крапку:

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

Після запуску програма виконання тестів просканує вказаний каталог і всі підкаталоги та знайде тести, якими є файли `*.phpt` і `*Test.php`. Він також прочитає і оцінить їхні [анотації |test-annotations], щоб знати, які з них і як запускати.

Після цього він виконує тести. Для кожного виконаного тесту бігун виводить один символ, щоб показати прогрес:

- <code style="color: #CCC; background-color: #000">.</code> - тест пройдено
- <code style="color: #CCC; background-color: #000">s</code> - тест пропущено
- <code style="color: #FFF; background-color: #900">F</code> - тест не пройдено

Виведення може мати вигляд:

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

Коли ви запустите його знову, він спочатку запустить тести, які не вдалось виконати під час попереднього запуску, тому ви одразу дізнаєтесь, чи виправили помилку.

Код виходу тестера дорівнює нулю, якщо жоден тест не завершився невдачею. Ненульовий в іншому випадку.

.[warning]
Тестер запускає PHP-процеси без `php.ini`. Більш детально в розділі [Власний php.ini |#Own php.ini].


Параметри командного рядка .[#toc-command-line-options]
=======================================================

Огляд параметрів командного рядка можна отримати, запустивши тестер без параметрів або з опцією `-h`:

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

Использование:
    tester [параметры] [<тестовый файл> | <каталог>]...

Параметры:
    -p <путь>                    Укажите интерпретатор PHP для запуска (по умолчанию: php).
    -c <path>                    Искать php.ini файл (или искать в директории) <path>.
    -C                           Использовать общесистемный php.ini.
    -d <ключ=значение>...        Определить INI-запись 'key' со значением 'value'.
    -s                           Показать информацию о пропущенных тестах.
    --stop-on-fail               Остановить выполнение при первом сбое.
    -j <num>                     Выполнять <num> заданий параллельно (по умолчанию: 8).
    -o <console|console-lines|tap|junit|log|none> (наприклад, -o junit:output.xml)
                                 Вкажіть один або декілька форматів виводу з необов'язковим ім'ям файлу.
    -w | --watch <путь>          Каталог просмотра.
    -i | --info                  Показать информацию об окружении тестов и выйти.
    --setup <путь>               Сценарий для настройки бегущей строки.
    --temp <path>                Шлях до тимчасового каталогу. За замовчуванням визначається функцією sys_get_temp_dir().
    --colors [1|0]               Включить или отключить цвета.
    --coverage <путь>            Генерировать отчет о покрытии кода в файл.
    --coverage-src <путь>        Путь к исходному коду.
    -h | --help                  Это справка.
\--


-p <path> .[filter]
-------------------
Вказує двійковий файл PHP, який буде використано для запуску тестів. За замовчуванням це `php`.

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


-c <path> .[filter]
-------------------
Вказує, який `php.ini` буде використовуватися під час запуску тестів. За замовчуванням php.ini не використовується. Докладнішу інформацію наведено у розділі Власний [php.ini |#Own php.ini].


-C .[filter]
------------
Використовується загальносистемний `php.ini`. Отже, на платформі UNIX всі файли `/etc/php/{sapi}/conf.d/*.ini` також. Див. розділ [Власний php.ini |#Own php.ini].


-d <key=value> .[filter]
------------------------
Задає значення директиви конфігурації PHP для тестів. Параметр можна використовувати декілька разів.

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


-s
---
Буде показано інформацію про пропущені тести.


--stop-on-fail .[filter]
------------------------
Тестер припиняє тестування після першого невдалого тесту.


-j <num> .[filter]
------------------
Тести виконуються в `<num>` паралельними прецесіями. Значення за замовчуванням 8. Якщо ми хочемо запускати тести послідовно, ми використовуємо значення 1.


-o <console|console-lines|tap|junit|log|none> .[filter]
-------------------------------------------------------
Формат виводу. За замовчуванням використовується формат консолі. Ви можете вказати назву файлу, до якого буде записано вивід (наприклад, `-o junit:output.xml`). Параметр `-o` можна повторити декілька разів, щоб згенерувати одразу декілька форматів.

- `console`: те саме, що і за замовчуванням, але у цьому випадку не виводиться ASCII-логотип
- `console-lines`: аналогічно консолі, але результат кожного тесту виводиться в окремому рядку з додатковою інформацією
- `tap`: [формат TAP |https://en.wikipedia.org/wiki/Test_Anything_Protocol], придатний для машинної обробки
- `junit`: формат JUnit XML, також придатний для машинної обробки
- `log`: Прогрес тестування вихідних даних. Всі невдалі, пропущені та успішні тести
- `none`: нічого не друкується


''-w | --watch <path>'' .[filter]
---------------------------------
Тестер не завершує роботу після завершення тестів, а продовжує працювати і переглядати PHP-файли у вказаному каталозі. При зміні параметра він запускає тести знову. Параметр можна використовувати декілька разів, якщо ми хочемо відстежувати декілька каталогів.

Це зручно під час рефакторингу бібліотеки або налагодження тестів.

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


''-i | --info'' .[filter]
-------------------------
Показує інформацію про середовище виконання тесту. Наприклад:

/--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]
------------------------
При запуску тестер завантажує даний PHP-скрипт. У ньому доступна змінна `Tester\Runner\Runner $runner`. Нехай це буде файл `tests/runner-setup.php`:

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

і запустимо тестер:

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


--temp <path> .[filter]
-----------------------
Задає шлях до каталогу для тимчасових файлів Тестера. Значення за замовчуванням повертається `sys_get_temp_dir()`. Якщо значення за замовчуванням невірне, ви отримаєте відповідне повідомлення.

Якщо ми не впевнені, який каталог використовується, ми можемо запустити Tester з параметром `--info`.


--colors 1|0 .[filter]
----------------------
За замовчуванням тестер виявляє термінал з підтримкою кольорів і розфарбовує його вивід. Цей параметр перекриває автоматичне визначення. Ми можемо глобально налаштувати розфарбування за допомогою системної змінної оточення `NETTE_TESTER_COLORS`.


--coverage <path> .[filter]
---------------------------
Тестер згенерує звіт з оглядом того, яку частину вихідного коду покрито тестами. Ця опція вимагає розширення PHP [Xdebug |https://xdebug.org/] або увімкненого [PCOV |https://github.com/krakjoe/pcov], або PHP 7 з PHPDBG SAPI, що є швидшим. Розширення файлу призначення визначає формат вмісту. HTML або Clover XML.

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

Пріоритетність вибору механізму збору наступна:
1) PCOV
2) PHPDBG
3) Xdebug

Під час запуску PHPDBG обширні тести можуть завершитися невдачею через вичерпання пам'яті. Збір даних про покриття є операцією, що споживає багато пам'яті. У цьому випадку може допомогти виклик `Tester\CodeCoverage\Collector::flush()` всередині тесту. Він збереже зібрані дані у файл і звільнить пам'ять. Коли збір даних не виконується або використовується Xdebug, виклик не має ніякого ефекту.

"Приклад HTML-звіту":https://files.nette.org/tester/coverage.html з покриттям коду.


--coverage-src <path> .[filter]
-------------------------------
Використовуємо одночасно з опцією `--coverage`. Параметр `<path>` це шлях до вихідного коду, для якого ми генеруємо звіт. Його можна використовувати багаторазово.


Власний php.ini .[#toc-own-php-ini]
===================================
Тестер запускає PHP-процеси з опцією `-n`, що означає, що ніяких `php.ini` не завантажується (навіть з `/etc/php/conf.d/*.ini` в UNIX). Це забезпечує однакове середовище для запуску тестів, але також деактивує всі зовнішні розширення PHP, які зазвичай завантажуються системним PHP.

Якщо ви хочете зберегти конфігурацію системи, використовуйте параметр `-C`.

Якщо вам потрібні деякі розширення або якісь особливі налаштування INI, ми рекомендуємо створити власний файл `php.ini` і розповсюдити його серед тестів. Після цього запускаємо тестер з параметром `-c`, наприклад, `tester -c tests/php.ini`. INI-файл може мати такий вигляд:

```ini
[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M
```

Запуск тестера з системним `php.ini` в UNIX, наприклад, `tester -c /etc/php/cgi/php.ini`, не завантажує інші INI-файли з `/etc/php/conf.d/*.ini`. Це поведінка PHP, а не тестера.

Бігові тести

Найбільш помітною частиною Nette Tester є запуск тестів з командного рядка. Він надзвичайно швидкий і надійний, оскільки автоматично запускає всі тести як окремі процеси паралельно в декількох потоках. Він також може запускати себе в так званому режимі спостереження.

Запуск тестового бігуна Nette Tester здійснюється з командного рядка. В якості параметра ми передамо директорію тесту. Для поточного каталогу просто введіть крапку:

vendor/bin/tester .

Після запуску програма виконання тестів просканує вказаний каталог і всі підкаталоги та знайде тести, якими є файли *.phpt і *Test.php. Він також прочитає і оцінить їхні анотації, щоб знати, які з них і як запускати.

Після цього він виконує тести. Для кожного виконаного тесту бігун виводить один символ, щоб показати прогрес:

  • . – тест пройдено
  • s – тест пропущено
  • F – тест не пройдено

Виведення може мати вигляд:

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

Коли ви запустите його знову, він спочатку запустить тести, які не вдалось виконати під час попереднього запуску, тому ви одразу дізнаєтесь, чи виправили помилку.

Код виходу тестера дорівнює нулю, якщо жоден тест не завершився невдачею. Ненульовий в іншому випадку.

Тестер запускає PHP-процеси без php.ini. Більш детально в розділі Власний php.ini.

Параметри командного рядка

Огляд параметрів командного рядка можна отримати, запустивши тестер без параметрів або з опцією -h:

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

Использование:
    tester [параметры] [<тестовый файл> | <каталог>]...

Параметры:
    -p <путь>                    Укажите интерпретатор PHP для запуска (по умолчанию: php).
    -c <path>                    Искать php.ini файл (или искать в директории) <path>.
    -C                           Использовать общесистемный php.ini.
    -d <ключ=значение>...        Определить INI-запись 'key' со значением 'value'.
    -s                           Показать информацию о пропущенных тестах.
    --stop-on-fail               Остановить выполнение при первом сбое.
    -j <num>                     Выполнять <num> заданий параллельно (по умолчанию: 8).
    -o <console|console-lines|tap|junit|log|none> (наприклад, -o junit:output.xml)
                                 Вкажіть один або декілька форматів виводу з необов'язковим ім'ям файлу.
    -w | --watch <путь>          Каталог просмотра.
    -i | --info                  Показать информацию об окружении тестов и выйти.
    --setup <путь>               Сценарий для настройки бегущей строки.
    --temp <path>                Шлях до тимчасового каталогу. За замовчуванням визначається функцією sys_get_temp_dir().
    --colors [1|0]               Включить или отключить цвета.
    --coverage <путь>            Генерировать отчет о покрытии кода в файл.
    --coverage-src <путь>        Путь к исходному коду.
    -h | --help                  Это справка.

-p <path>

Вказує двійковий файл PHP, який буде використано для запуску тестів. За замовчуванням це php.

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

-c <path>

Вказує, який php.ini буде використовуватися під час запуску тестів. За замовчуванням php.ini не використовується. Докладнішу інформацію наведено у розділі Власний php.ini.

-C

Використовується загальносистемний php.ini. Отже, на платформі UNIX всі файли /etc/php/{sapi}/conf.d/*.ini також. Див. розділ Власний php.ini.

-d <key=value>

Задає значення директиви конфігурації PHP для тестів. Параметр можна використовувати декілька разів.

tester -d max_execution_time=20

-s

Буде показано інформацію про пропущені тести.

--stop-on-fail

Тестер припиняє тестування після першого невдалого тесту.

-j <num>

Тести виконуються в <num> паралельними прецесіями. Значення за замовчуванням 8. Якщо ми хочемо запускати тести послідовно, ми використовуємо значення 1.

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

Формат виводу. За замовчуванням використовується формат консолі. Ви можете вказати назву файлу, до якого буде записано вивід (наприклад, -o junit:output.xml). Параметр -o можна повторити декілька разів, щоб згенерувати одразу декілька форматів.

  • console: те саме, що і за замовчуванням, але у цьому випадку не виводиться ASCII-логотип
  • console-lines: аналогічно консолі, але результат кожного тесту виводиться в окремому рядку з додатковою інформацією
  • tap: формат TAP, придатний для машинної обробки
  • junit: формат JUnit XML, також придатний для машинної обробки
  • log: Прогрес тестування вихідних даних. Всі невдалі, пропущені та успішні тести
  • none: нічого не друкується

-w | --watch <path>

Тестер не завершує роботу після завершення тестів, а продовжує працювати і переглядати PHP-файли у вказаному каталозі. При зміні параметра він запускає тести знову. Параметр можна використовувати декілька разів, якщо ми хочемо відстежувати декілька каталогів.

Це зручно під час рефакторингу бібліотеки або налагодження тестів.

tester --watch src tests

-i | --info

Показує інформацію про середовище виконання тесту. Наприклад:

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>

При запуску тестер завантажує даний PHP-скрипт. У ньому доступна змінна Tester\Runner\Runner $runner. Нехай це буде файл tests/runner-setup.php:

$runner->outputHandlers[] = new MyOutputHandler;

і запустимо тестер:

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

--temp <path>

Задає шлях до каталогу для тимчасових файлів Тестера. Значення за замовчуванням повертається sys_get_temp_dir(). Якщо значення за замовчуванням невірне, ви отримаєте відповідне повідомлення.

Якщо ми не впевнені, який каталог використовується, ми можемо запустити Tester з параметром --info.

--colors 1|0

За замовчуванням тестер виявляє термінал з підтримкою кольорів і розфарбовує його вивід. Цей параметр перекриває автоматичне визначення. Ми можемо глобально налаштувати розфарбування за допомогою системної змінної оточення NETTE_TESTER_COLORS.

--coverage <path>

Тестер згенерує звіт з оглядом того, яку частину вихідного коду покрито тестами. Ця опція вимагає розширення PHP Xdebug або увімкненого PCOV, або PHP 7 з PHPDBG SAPI, що є швидшим. Розширення файлу призначення визначає формат вмісту. HTML або Clover XML.

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

Пріоритетність вибору механізму збору наступна:

  1. PCOV
  2. PHPDBG
  3. Xdebug

Під час запуску PHPDBG обширні тести можуть завершитися невдачею через вичерпання пам'яті. Збір даних про покриття є операцією, що споживає багато пам'яті. У цьому випадку може допомогти виклик Tester\CodeCoverage\Collector::flush() всередині тесту. Він збереже зібрані дані у файл і звільнить пам'ять. Коли збір даних не виконується або використовується Xdebug, виклик не має ніякого ефекту.

Приклад HTML-звіту з покриттям коду.

--coverage-src <path>

Використовуємо одночасно з опцією --coverage. Параметр <path> це шлях до вихідного коду, для якого ми генеруємо звіт. Його можна використовувати багаторазово.

Власний php.ini

Тестер запускає PHP-процеси з опцією -n, що означає, що ніяких php.ini не завантажується (навіть з /etc/php/conf.d/*.ini в UNIX). Це забезпечує однакове середовище для запуску тестів, але також деактивує всі зовнішні розширення PHP, які зазвичай завантажуються системним PHP.

Якщо ви хочете зберегти конфігурацію системи, використовуйте параметр -C.

Якщо вам потрібні деякі розширення або якісь особливі налаштування INI, ми рекомендуємо створити власний файл php.ini і розповсюдити його серед тестів. Після цього запускаємо тестер з параметром -c, наприклад, tester -c tests/php.ini. INI-файл може мати такий вигляд:

[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M

Запуск тестера з системним php.ini в UNIX, наприклад, tester -c /etc/php/cgi/php.ini, не завантажує інші INI-файли з /etc/php/conf.d/*.ini. Це поведінка PHP, а не тестера.