Nette Documentation Preview

syntax
Izvajanje testov
****************

.[perex]
Najbolj viden del programa Nette Tester je program za izvajanje testov v ukazni vrstici. Je izjemno hiter in robusten, saj samodejno zažene vse teste kot ločene procese vzporedno v več niti. Prav tako se lahko sam izvaja v tako imenovanem načinu opazovanja.

Nette Tester Test Runner se sproži iz ukazne vrstice. Kot parameter bomo posredovali imenik testov. Za trenutni imenik vpišemo samo piko:

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

Ko ga prikličemo, bo testni izvajalec pregledal navedeni imenik in vse podimenike ter poiskal teste, ki so datoteke `*.phpt` in `*Test.php`. Prav tako prebere in oceni njihove [opombe, |test-annotations] da ve, katere in kako naj jih izvede.

Nato izvede teste. Za vsak opravljen test izvajalec izpiše en znak, ki označuje napredek:

- <code style="color: #CCC; background-color: #000">.</code> - test je bil opravljen
- <code style="color: #CCC; background-color: #000">s</code> - test je bil preskočen
- <code style="color: #FFF; background-color: #900">F</code> - test ni uspel

Izpis je lahko videti takole:

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

Ob ponovnem zagonu se najprej izvedejo testi, ki so bili med prejšnjim zagonom neuspešni, tako da boste takoj vedeli, ali ste napako odpravili.

Izhodna koda testerja je nič, če noben test ni uspešen. V nasprotnem primeru je neničelna.

.[warning]
Tester izvaja procese PHP brez `php.ini`. Več podrobnosti najdete v razdelku [Lastni php.ini |#Own php.ini].


Možnosti ukazne vrstice .[#toc-command-line-options]
====================================================

Pregled možnosti ukazne vrstice dobimo tako, da zaženemo Tester brez parametrov ali z možnostjo `-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> (npr. -o junit:output.xml)
                                 Določite enega ali več izhodnih formatov z neobveznim imenom datoteke.
    -w | --watch <path>          Watch directory.
    -i | --info                  Show tests environment info and exit.
    --setup <path>               Script for runner setup.
    --temp <path>                Pot do začasnega imenika. Privzeto s 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]
-------------------
Določa binarni strežnik PHP, ki se bo uporabljal za izvajanje testov. Privzeto je `php`.

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


-c <path> .[filter]
-------------------
Določa, kateri `php.ini` se bo uporabljal pri izvajanju testov. Privzeto se ne uporablja php.ini. Za več informacij glejte [Lastni php.ini |#Own php.ini].


-C .[filter]
------------
Uporabi se sistemski `php.ini`. Tako so na platformi UNIX uporabljene tudi vse datoteke `/etc/php/{sapi}/conf.d/*.ini`. Oglejte si razdelek [Lastni php.ini |#Own php.ini].


-d <key=value> .[filter]
------------------------
Nastavi vrednost konfiguracijske direktive PHP za teste. Parameter lahko uporabite večkrat.

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


-s
---
Prikazane bodo informacije o preskočenih testih.


--stop-on-fail .[filter]
------------------------
Tester ustavi testiranje ob prvem neuspešnem testu.


-j <num> .[filter]
------------------
Testi se izvajajo v `<num>` vzporednih procesih. Privzeta vrednost je 8. Če želimo teste izvajati zaporedno, uporabimo vrednost 1.


-o <console|console-lines|tap|junit|log|none> .[filter]
-------------------------------------------------------
Izhodni format. Privzeta je konzolna oblika. Določite lahko ime datoteke, v katero se bo zapisal izpis (npr. `-o junit:output.xml`). Možnost `-o` lahko večkrat ponovite, da ustvarite več formatov naenkrat.

- `console`: enako kot privzeto, vendar se v tem primeru logotip ASCII ne izpiše.
- `console-lines`: podobno kot v konzoli, vendar je rezultat vsakega testa naveden v ločeni vrstici z več informacijami
- `tap`: [format TAP, |https://en.wikipedia.org/wiki/Test_Anything_Protocol] primeren za strojno obdelavo
- `junit`: format JUnit XML, primeren tudi za strojno obdelavo
- `log`: Izpis poteka testiranja. Vsi neuspešni, preskočeni in tudi uspešni testi
- `none`: nič se ne izpiše


''-w | --watch <path>'' .[filter]
---------------------------------
Tester se po končanih testih ne konča, temveč se še naprej izvaja in opazuje datoteke PHP v danem imeniku. Ob spremembi ponovno izvede teste. Parameter lahko uporabimo večkrat, če želimo spremljati več imenikov.

To je priročno med refaktorizacijo knjižnice ali odpravljanjem napak pri testih.

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


''-i | --info'' .[filter]
-------------------------
Prikaže informacije o okolju, v katerem se izvaja test. Na primer:

/--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 ob zagonu naloži dano skripto PHP. V njej je na voljo spremenljivka `Tester\Runner\Runner $runner`. Predpostavimo datoteko `tests/runner-setup.php`:

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

in zaženemo Tester:

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


--temp <path> .[filter]
-----------------------
Nastavi pot do imenika za začasne datoteke Testerja. Privzeto vrednost vrne `sys_get_temp_dir()`. Če privzeta vrednost ni veljavna, boste na to opozorjeni.

Če nismo prepričani, kateri imenik se uporablja, lahko zaženemo Tester s parametrom `--info`.


--colors 1|0 .[filter]
----------------------
Tester privzeto zazna terminal z možnostjo obarvanja in obarva svoj izhod. Ta možnost je nad samodejnim zaznavanjem. Obarvanje lahko globalno nastavimo s sistemsko okoljsko spremenljivko `NETTE_TESTER_COLORS`.


--coverage <path> .[filter]
---------------------------
Tester bo ustvaril poročilo s pregledom, koliko je izvorna koda pokrita s testi. Ta možnost zahteva omogočeno razširitev PHP [Xdebug |https://xdebug.org/] ali [PCOV |https://github.com/krakjoe/pcov] ali PHP 7 s PHPDBG SAPI, ki je hitrejši. Ciljna končnica datoteke določa obliko vsebine. HTML ali Clover XML.

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

Prednostna izbira mehanizma za zbiranje je naslednja:
1) PCOV
2) PHPDBG
3) Xdebug

Obsežni testi lahko med izvajanjem s PHPDBG zaradi izčrpanosti pomnilnika ne uspejo. Zbiranje podatkov o pokritosti je operacija, ki porabi veliko pomnilnika. V tem primeru lahko pomaga klicanje `Tester\CodeCoverage\Collector::flush()` znotraj testa. Ta bo zbrane podatke spraznil v datoteko in sprostil pomnilnik. Če zbiranje podatkov ni v teku ali če se uporablja Xdebug, klic nima učinka.

"Primer poročila HTML":https://files.nette.org/tester/coverage.html s pokritostjo kode.


--coverage-src <path> .[filter]
-------------------------------
Uporabljamo jo hkrati z možnostjo `--coverage`. Možnost `<path>` je pot do izvorne kode, za katero ustvarjamo poročilo. Uporabimo jo lahko večkrat.


Lastni php.ini .[#toc-own-php-ini]
==================================
Tester izvaja procese PHP z možnostjo `-n`, kar pomeni, da se ne naloži noben `php.ini` (niti tisti iz `/etc/php/conf.d/*.ini` v sistemu UNIX). S tem je zagotovljeno enako okolje za zagon testov, hkrati pa so deaktivirane vse zunanje razširitve PHP, ki jih sistemski PHP običajno naloži.

Če želite ohraniti sistemsko konfiguracijo, uporabite parameter `-C`.

Če potrebujete nekatere razširitve ali posebne nastavitve INI, priporočamo, da ustvarite lastno datoteko `php.ini` in jo razdelite med teste. Nato zaženemo tester z možnostjo `-c`, npr. `tester -c tests/php.ini`. Datoteka INI je lahko videti takole:

```ini
[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M
```

Zagon Testerja s sistemsko možnostjo `php.ini` v sistemu UNIX, npr. `tester -c /etc/php/cgi/php.ini`, ne naloži drugih INI iz `/etc/php/conf.d/*.ini`. To je obnašanje PHP in ne Testerja.

Izvajanje testov

Najbolj viden del programa Nette Tester je program za izvajanje testov v ukazni vrstici. Je izjemno hiter in robusten, saj samodejno zažene vse teste kot ločene procese vzporedno v več niti. Prav tako se lahko sam izvaja v tako imenovanem načinu opazovanja.

Nette Tester Test Runner se sproži iz ukazne vrstice. Kot parameter bomo posredovali imenik testov. Za trenutni imenik vpišemo samo piko:

vendor/bin/tester .

Ko ga prikličemo, bo testni izvajalec pregledal navedeni imenik in vse podimenike ter poiskal teste, ki so datoteke *.phpt in *Test.php. Prav tako prebere in oceni njihove opombe, da ve, katere in kako naj jih izvede.

Nato izvede teste. Za vsak opravljen test izvajalec izpiše en znak, ki označuje napredek:

  • . – test je bil opravljen
  • s – test je bil preskočen
  • F – test ni uspel

Izpis je lahko videti takole:

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

Ob ponovnem zagonu se najprej izvedejo testi, ki so bili med prejšnjim zagonom neuspešni, tako da boste takoj vedeli, ali ste napako odpravili.

Izhodna koda testerja je nič, če noben test ni uspešen. V nasprotnem primeru je neničelna.

Tester izvaja procese PHP brez php.ini. Več podrobnosti najdete v razdelku Lastni php.ini.

Možnosti ukazne vrstice

Pregled možnosti ukazne vrstice dobimo tako, da zaženemo Tester brez parametrov ali z možnostjo -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> (npr. -o junit:output.xml)
                                 Določite enega ali več izhodnih formatov z neobveznim imenom datoteke.
    -w | --watch <path>          Watch directory.
    -i | --info                  Show tests environment info and exit.
    --setup <path>               Script for runner setup.
    --temp <path>                Pot do začasnega imenika. Privzeto s 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>

Določa binarni strežnik PHP, ki se bo uporabljal za izvajanje testov. Privzeto je php.

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

-c <path>

Določa, kateri php.ini se bo uporabljal pri izvajanju testov. Privzeto se ne uporablja php.ini. Za več informacij glejte Lastni php.ini.

-C

Uporabi se sistemski php.ini. Tako so na platformi UNIX uporabljene tudi vse datoteke /etc/php/{sapi}/conf.d/*.ini. Oglejte si razdelek Lastni php.ini.

-d <key=value>

Nastavi vrednost konfiguracijske direktive PHP za teste. Parameter lahko uporabite večkrat.

tester -d max_execution_time=20

-s

Prikazane bodo informacije o preskočenih testih.

--stop-on-fail

Tester ustavi testiranje ob prvem neuspešnem testu.

-j <num>

Testi se izvajajo v <num> vzporednih procesih. Privzeta vrednost je 8. Če želimo teste izvajati zaporedno, uporabimo vrednost 1.

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

Izhodni format. Privzeta je konzolna oblika. Določite lahko ime datoteke, v katero se bo zapisal izpis (npr. -o junit:output.xml). Možnost -o lahko večkrat ponovite, da ustvarite več formatov naenkrat.

  • console: enako kot privzeto, vendar se v tem primeru logotip ASCII ne izpiše.
  • console-lines: podobno kot v konzoli, vendar je rezultat vsakega testa naveden v ločeni vrstici z več informacijami
  • tap: format TAP, primeren za strojno obdelavo
  • junit: format JUnit XML, primeren tudi za strojno obdelavo
  • log: Izpis poteka testiranja. Vsi neuspešni, preskočeni in tudi uspešni testi
  • none: nič se ne izpiše

-w | --watch <path>

Tester se po končanih testih ne konča, temveč se še naprej izvaja in opazuje datoteke PHP v danem imeniku. Ob spremembi ponovno izvede teste. Parameter lahko uporabimo večkrat, če želimo spremljati več imenikov.

To je priročno med refaktorizacijo knjižnice ali odpravljanjem napak pri testih.

tester --watch src tests

-i | --info

Prikaže informacije o okolju, v katerem se izvaja test. Na primer:

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 ob zagonu naloži dano skripto PHP. V njej je na voljo spremenljivka Tester\Runner\Runner $runner. Predpostavimo datoteko tests/runner-setup.php:

$runner->outputHandlers[] = new MyOutputHandler;

in zaženemo Tester:

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

--temp <path>

Nastavi pot do imenika za začasne datoteke Testerja. Privzeto vrednost vrne sys_get_temp_dir(). Če privzeta vrednost ni veljavna, boste na to opozorjeni.

Če nismo prepričani, kateri imenik se uporablja, lahko zaženemo Tester s parametrom --info.

--colors 1|0

Tester privzeto zazna terminal z možnostjo obarvanja in obarva svoj izhod. Ta možnost je nad samodejnim zaznavanjem. Obarvanje lahko globalno nastavimo s sistemsko okoljsko spremenljivko NETTE_TESTER_COLORS.

--coverage <path>

Tester bo ustvaril poročilo s pregledom, koliko je izvorna koda pokrita s testi. Ta možnost zahteva omogočeno razširitev PHP Xdebug ali PCOV ali PHP 7 s PHPDBG SAPI, ki je hitrejši. Ciljna končnica datoteke določa obliko vsebine. HTML ali Clover XML.

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

Prednostna izbira mehanizma za zbiranje je naslednja:

  1. PCOV
  2. PHPDBG
  3. Xdebug

Obsežni testi lahko med izvajanjem s PHPDBG zaradi izčrpanosti pomnilnika ne uspejo. Zbiranje podatkov o pokritosti je operacija, ki porabi veliko pomnilnika. V tem primeru lahko pomaga klicanje Tester\CodeCoverage\Collector::flush() znotraj testa. Ta bo zbrane podatke spraznil v datoteko in sprostil pomnilnik. Če zbiranje podatkov ni v teku ali če se uporablja Xdebug, klic nima učinka.

Primer poročila HTML s pokritostjo kode.

--coverage-src <path>

Uporabljamo jo hkrati z možnostjo --coverage. Možnost <path> je pot do izvorne kode, za katero ustvarjamo poročilo. Uporabimo jo lahko večkrat.

Lastni php.ini

Tester izvaja procese PHP z možnostjo -n, kar pomeni, da se ne naloži noben php.ini (niti tisti iz /etc/php/conf.d/*.ini v sistemu UNIX). S tem je zagotovljeno enako okolje za zagon testov, hkrati pa so deaktivirane vse zunanje razširitve PHP, ki jih sistemski PHP običajno naloži.

Če želite ohraniti sistemsko konfiguracijo, uporabite parameter -C.

Če potrebujete nekatere razširitve ali posebne nastavitve INI, priporočamo, da ustvarite lastno datoteko php.ini in jo razdelite med teste. Nato zaženemo tester z možnostjo -c, npr. tester -c tests/php.ini. Datoteka INI je lahko videti takole:

[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M

Zagon Testerja s sistemsko možnostjo php.ini v sistemu UNIX, npr. tester -c /etc/php/cgi/php.ini, ne naloži drugih INI iz /etc/php/conf.d/*.ini. To je obnašanje PHP in ne Testerja.