Nette Documentation Preview

syntax
Esecuzione di test
******************

.[perex]
La parte più visibile di Nette Tester è il test runner a riga di comando. È estremamente veloce e robusto perché avvia automaticamente tutti i test come processi separati in parallelo su più thread. Può anche essere eseguito da solo nella cosiddetta modalità watch.

Il test runner di Nette Tester viene invocato dalla riga di comando. Come parametro, si passerà la directory del test. Per la directory corrente è sufficiente inserire un punto:

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

Quando viene invocato, il test runner scansiona la directory specificata e tutte le sottodirectory e cerca i test, che sono i file `*.phpt` e `*Test.php`. Legge e valuta anche le loro [annotazioni |test-annotations] per sapere quali e come eseguirli.

Quindi esegue i test. Per ogni test eseguito, il runner stampa un carattere per indicare il progresso:

- <code style="color: #CCC; background-color: #000">.</code> - test superato
- <code style="color: #CCC; background-color: #000">s</code> - il test è stato saltato
- <code style="color: #FFF; background-color: #900">F</code> - test fallito

L'output può apparire come:

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

Quando si esegue di nuovo, vengono prima eseguiti i test falliti durante l'esecuzione precedente, in modo da sapere subito se l'errore è stato risolto.

Il codice di uscita del tester è zero se nessuno fallisce. Altrimenti non è zero.

.[warning]
Il Tester esegue processi PHP senza `php.ini`. Maggiori dettagli nella sezione [Own php.ini |#Own php.ini].


Opzioni della riga di comando .[#toc-command-line-options]
==========================================================

Otteniamo una panoramica delle opzioni da riga di comando eseguendo il Tester senza parametri o con l'opzione `-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> (ad esempio -o junit:output.xml)
                                 Specifica uno o più formati di output con un nome di file opzionale.
    -w | --watch <path>          Watch directory.
    -i | --info                  Show tests environment info and exit.
    --setup <path>               Script for runner setup.
    --temp <path>                Percorso della directory temporanea. Predefinito da 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]
-------------------
Specifica il binario PHP che sarà usato per eseguire i test. Per impostazione predefinita è `php`.

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


-c <path> .[filter]
-------------------
Specifica quale `php.ini` sarà usato durante l'esecuzione dei test. Per impostazione predefinita, non viene usato alcun php.ini. Per ulteriori informazioni, vedere [Proprio php.ini |#Own php.ini].


-C .[filter]
------------
Viene utilizzato un `php.ini` a livello di sistema. Quindi, su piattaforma UNIX, anche tutti i file `/etc/php/{sapi}/conf.d/*.ini`. Vedere la sezione [php.ini |#Own php.ini].


-d <key=value> .[filter]
------------------------
Imposta il valore della direttiva di configurazione PHP per i test. Il parametro può essere usato più volte.

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


-s
---
Verranno mostrate le informazioni sui test saltati.


--stop-on-fail .[filter]
------------------------
Il tester interrompe il test al primo fallimento.


-j <num> .[filter]
------------------
I test vengono eseguiti in un `<num>` in parallelo. Il valore predefinito è 8. Se si desidera eseguire i test in serie, si utilizza il valore 1.


-o <console|console-lines|tap|junit|log|none> .[filter]
-------------------------------------------------------
Formato di uscita. Il formato predefinito è quello della console. È possibile specificare il nome del file in cui verrà scritto l'output (ad esempio, `-o junit:output.xml`). L'opzione `-o` può essere ripetuta più volte per generare più formati contemporaneamente.

- `console`: uguale a quello predefinito, ma in questo caso il logo ASCII non viene stampato
- `console-lines`: simile alla console, ma il risultato di ogni test è elencato su una riga separata con maggiori informazioni
- `tap`: [formato TAP |https://en.wikipedia.org/wiki/Test_Anything_Protocol] adatto all'elaborazione automatica
- `junit`: formato XML JUnit, appropriato anche per l'elaborazione meccanica
- `log`: Visualizza l'avanzamento dei test. Tutti i test falliti, saltati e anche quelli riusciti
- `none`: non viene stampato nulla


''-w | --watch <path>'' .[filter]
---------------------------------
Il Tester non termina al termine dei test, ma continua a eseguire e a osservare i file PHP nella directory indicata. Quando vengono modificati, esegue nuovamente i test. Il parametro può essere usato più volte se si vogliono monitorare più directory.

È utile durante il refactoring di una libreria o il debug dei test.

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


''-i | --info'' .[filter]
-------------------------
Mostra informazioni sull'ambiente di esecuzione del test. Ad esempio:

/--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]
------------------------
Il Tester carica lo script PHP dato all'avvio. La variabile `Tester\Runner\Runner $runner` è disponibile in esso. Supponiamo che il file `tests/runner-setup.php`:

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

ed eseguiamo il Tester:

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


--temp <path> .[filter]
-----------------------
Imposta il percorso della directory per i file temporanei di Tester. Il valore predefinito è restituito da `sys_get_temp_dir()`. Quando il valore predefinito non è valido, viene segnalato.

Se non si è sicuri della directory utilizzata, si può eseguire Tester con il parametro `--info`.


--colori 1|0 .[filter]
----------------------
Il Tester rileva un terminale colorabile in modo predefinito e colora il suo output. Questa opzione sostituisce il rilevamento automatico. È possibile impostare la colorazione a livello globale tramite una variabile d'ambiente di sistema `NETTE_TESTER_COLORS`.


--copertura <path> .[filter]
----------------------------
Il tester genererà un rapporto con una panoramica di quanto il codice sorgente è coperto dai test. Questa opzione richiede l'abilitazione dell'estensione PHP [Xdebug |https://xdebug.org/] o [PCOV |https://github.com/krakjoe/pcov], oppure PHP 7 con PHPDBG SAPI, che è più veloce. L'estensione del file di destinazione determina il formato del contenuto. HTML o Clover XML.

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

La priorità di scelta del meccanismo di raccolta è la seguente:
1) PCOV
2) PHPDBG
3) Xdebug

I test più estesi possono fallire durante l'esecuzione con PHPDBG a causa dell'esaurimento della memoria. La raccolta dei dati di copertura è un'operazione che consuma memoria. In questo caso, può essere utile richiamare `Tester\CodeCoverage\Collector::flush()` all'interno di un test. Essa riverserà i dati raccolti in un file e libererà la memoria. Quando la raccolta dei dati non è in corso o si utilizza Xdebug, la chiamata non ha alcun effetto.

"Un esempio di report HTML":https://files.nette.org/tester/coverage.html con copertura del codice.


--copertura-src <path> .[filter]
--------------------------------
La utilizziamo contemporaneamente all'opzione `--coverage`. L'opzione `<path>` è un percorso al codice sorgente per il quale si genera il rapporto. Può essere usato ripetutamente.


Proprio php.ini .[#toc-own-php-ini]
===================================
Il Tester esegue i processi PHP con l'opzione `-n`, il che significa che non viene caricato `php.ini` (nemmeno quello di `/etc/php/conf.d/*.ini` in UNIX). Questo garantisce lo stesso ambiente per i test eseguiti, ma disattiva anche tutte le estensioni PHP esterne comunemente caricate da PHP di sistema.

Se si vuole mantenere la configurazione di sistema, utilizzare il parametro `-C`.

Se si ha bisogno di alcune estensioni o di alcune impostazioni INI speciali, si consiglia di creare un proprio file `php.ini` e di distribuirlo tra i test. Poi si esegue Tester con l'opzione `-c`, ad esempio `tester -c tests/php.ini`. Il file INI può essere simile a:

```ini
[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M
```

L'esecuzione del Tester con un sistema `php.ini` in UNIX, ad esempio `tester -c /etc/php/cgi/php.ini`, non carica altri INI da `/etc/php/conf.d/*.ini`. Questo è il comportamento di PHP, non del Tester.

Esecuzione di test

La parte più visibile di Nette Tester è il test runner a riga di comando. È estremamente veloce e robusto perché avvia automaticamente tutti i test come processi separati in parallelo su più thread. Può anche essere eseguito da solo nella cosiddetta modalità watch.

Il test runner di Nette Tester viene invocato dalla riga di comando. Come parametro, si passerà la directory del test. Per la directory corrente è sufficiente inserire un punto:

vendor/bin/tester .

Quando viene invocato, il test runner scansiona la directory specificata e tutte le sottodirectory e cerca i test, che sono i file *.phpt e *Test.php. Legge e valuta anche le loro annotazioni per sapere quali e come eseguirli.

Quindi esegue i test. Per ogni test eseguito, il runner stampa un carattere per indicare il progresso:

  • . – test superato
  • s – il test è stato saltato
  • F – test fallito

L'output può apparire come:

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

Quando si esegue di nuovo, vengono prima eseguiti i test falliti durante l'esecuzione precedente, in modo da sapere subito se l'errore è stato risolto.

Il codice di uscita del tester è zero se nessuno fallisce. Altrimenti non è zero.

Il Tester esegue processi PHP senza php.ini. Maggiori dettagli nella sezione Own php.ini.

Opzioni della riga di comando

Otteniamo una panoramica delle opzioni da riga di comando eseguendo il Tester senza parametri o con l'opzione -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> (ad esempio -o junit:output.xml)
                                 Specifica uno o più formati di output con un nome di file opzionale.
    -w | --watch <path>          Watch directory.
    -i | --info                  Show tests environment info and exit.
    --setup <path>               Script for runner setup.
    --temp <path>                Percorso della directory temporanea. Predefinito da 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>

Specifica il binario PHP che sarà usato per eseguire i test. Per impostazione predefinita è php.

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

-c <path>

Specifica quale php.ini sarà usato durante l'esecuzione dei test. Per impostazione predefinita, non viene usato alcun php.ini. Per ulteriori informazioni, vedere Proprio php.ini.

-C

Viene utilizzato un php.ini a livello di sistema. Quindi, su piattaforma UNIX, anche tutti i file /etc/php/{sapi}/conf.d/*.ini. Vedere la sezione php.ini.

-d <key=value>

Imposta il valore della direttiva di configurazione PHP per i test. Il parametro può essere usato più volte.

tester -d max_execution_time=20

-s

Verranno mostrate le informazioni sui test saltati.

--stop-on-fail

Il tester interrompe il test al primo fallimento.

-j <num>

I test vengono eseguiti in un <num> in parallelo. Il valore predefinito è 8. Se si desidera eseguire i test in serie, si utilizza il valore 1.

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

Formato di uscita. Il formato predefinito è quello della console. È possibile specificare il nome del file in cui verrà scritto l'output (ad esempio, -o junit:output.xml). L'opzione -o può essere ripetuta più volte per generare più formati contemporaneamente.

  • console: uguale a quello predefinito, ma in questo caso il logo ASCII non viene stampato
  • console-lines: simile alla console, ma il risultato di ogni test è elencato su una riga separata con maggiori informazioni
  • tap: formato TAP adatto all'elaborazione automatica
  • junit: formato XML JUnit, appropriato anche per l'elaborazione meccanica
  • log: Visualizza l'avanzamento dei test. Tutti i test falliti, saltati e anche quelli riusciti
  • none: non viene stampato nulla

-w | --watch <path>

Il Tester non termina al termine dei test, ma continua a eseguire e a osservare i file PHP nella directory indicata. Quando vengono modificati, esegue nuovamente i test. Il parametro può essere usato più volte se si vogliono monitorare più directory.

È utile durante il refactoring di una libreria o il debug dei test.

tester --watch src tests

-i | --info

Mostra informazioni sull'ambiente di esecuzione del test. Ad esempio:

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>

Il Tester carica lo script PHP dato all'avvio. La variabile Tester\Runner\Runner $runner è disponibile in esso. Supponiamo che il file tests/runner-setup.php:

$runner->outputHandlers[] = new MyOutputHandler;

ed eseguiamo il Tester:

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

--temp <path>

Imposta il percorso della directory per i file temporanei di Tester. Il valore predefinito è restituito da sys_get_temp_dir(). Quando il valore predefinito non è valido, viene segnalato.

Se non si è sicuri della directory utilizzata, si può eseguire Tester con il parametro --info.

--colori 1|0

Il Tester rileva un terminale colorabile in modo predefinito e colora il suo output. Questa opzione sostituisce il rilevamento automatico. È possibile impostare la colorazione a livello globale tramite una variabile d'ambiente di sistema NETTE_TESTER_COLORS.

--copertura <path>

Il tester genererà un rapporto con una panoramica di quanto il codice sorgente è coperto dai test. Questa opzione richiede l'abilitazione dell'estensione PHP XdebugPCOV, oppure PHP 7 con PHPDBG SAPI, che è più veloce. L'estensione del file di destinazione determina il formato del contenuto. HTML o Clover XML.

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

La priorità di scelta del meccanismo di raccolta è la seguente:

  1. PCOV
  2. PHPDBG
  3. Xdebug

I test più estesi possono fallire durante l'esecuzione con PHPDBG a causa dell'esaurimento della memoria. La raccolta dei dati di copertura è un'operazione che consuma memoria. In questo caso, può essere utile richiamare Tester\CodeCoverage\Collector::flush() all'interno di un test. Essa riverserà i dati raccolti in un file e libererà la memoria. Quando la raccolta dei dati non è in corso o si utilizza Xdebug, la chiamata non ha alcun effetto.

Un esempio di report HTML con copertura del codice.

--copertura-src <path>

La utilizziamo contemporaneamente all'opzione --coverage. L'opzione <path> è un percorso al codice sorgente per il quale si genera il rapporto. Può essere usato ripetutamente.

Proprio php.ini

Il Tester esegue i processi PHP con l'opzione -n, il che significa che non viene caricato php.ini (nemmeno quello di /etc/php/conf.d/*.ini in UNIX). Questo garantisce lo stesso ambiente per i test eseguiti, ma disattiva anche tutte le estensioni PHP esterne comunemente caricate da PHP di sistema.

Se si vuole mantenere la configurazione di sistema, utilizzare il parametro -C.

Se si ha bisogno di alcune estensioni o di alcune impostazioni INI speciali, si consiglia di creare un proprio file php.ini e di distribuirlo tra i test. Poi si esegue Tester con l'opzione -c, ad esempio tester -c tests/php.ini. Il file INI può essere simile a:

[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M

L'esecuzione del Tester con un sistema php.ini in UNIX, ad esempio tester -c /etc/php/cgi/php.ini, non carica altri INI da /etc/php/conf.d/*.ini. Questo è il comportamento di PHP, non del Tester.