Exécuter les tests

La partie la plus visible de Nette Tester est le lanceur de tests en ligne de commande. Il est extrêmement rapide et robuste, car il exécute automatiquement tous les tests comme des processus distincts, en parallèle sur plusieurs threads. Il sait aussi se lancer en mode watch.

Le lanceur de tests s'invoque depuis la ligne de commande. Passez en paramètre le répertoire contenant les tests. Pour le répertoire courant, il suffit d'indiquer un point :

vendor/bin/tester .

Le lanceur de tests parcourt le répertoire indiqué et tous ses sous-répertoires en y cherchant les tests, c'est-à-dire les fichiers se terminant par *.phpt ou *Test.php. Il lit et évalue aussi leurs annotations pour déterminer quels tests exécuter et comment.

Chaque fichier de test s'exécute dans son propre processus PHP isolé, et le lanceur en exécute plusieurs à la fois : l'unité de parallélisme est donc le fichier. Le code d'un même fichier s'exécute par conséquent séquentiellement. Un TestCase vit dans un seul fichier, donc ses méthodes s'exécutent par défaut l'une après l'autre dans un seul processus ; marquez-le de l'annotation @testCase pour que le lanceur exécute plutôt chaque méthode de test comme un processus parallèle distinct.

Il exécute ensuite les tests. Pendant l'exécution, il affiche dans le terminal des caractères indiquant la progression :

. – test réussi
s – test ignoré
F – test échoué

La sortie peut ressembler à ceci :

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

PHP 8.5.2 (cli) | php | 8 threads

........s..........................

OK (35 tests, 1 skipped, 1.7 seconds)

Lors d'une nouvelle exécution, il lance d'abord les tests qui ont échoué la fois précédente, ce qui vous permet de savoir tout de suite si vous avez corrigé l'erreur.

Le code de sortie de Tester est zéro si aucun test n'échoue. Sinon, il est différent de zéro.

Options de la ligne de commande

Vous obtenez un aperçu des options de la ligne de commande en lançant Tester sans paramètres ou avec l'option -h :

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

Usage:
    tester [options] [<test file> | <directory>]...

Options:
    -p <path>                    Specify PHP interpreter to run (default: php).
    -c <path>                    Use custom php.ini, ignore system configuration.
    -C                           With -c, include system configuration as well.
    -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>  (e.g. -o junit:output.xml)
                                 Specify one or more output formats with optional file name.
    -w | --watch <path>          Watch directory.
    -i | --info                  Show tests environment info and exit.
    --setup <path>               Script for runner setup.
    --temp <path>                Path to temporary directory. Default by 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>

Indique le binaire PHP qui sera utilisé pour exécuter les tests. Par défaut, c'est php.

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

-c <path>

Utilise un fichier php.ini personnalisé et ignore la configuration système. C'est utile pour exécuter les tests avec des réglages précis. Voir Son propre php.ini pour plus d'informations.

-C

Utilisée avec -c, elle inclut aussi la configuration système (ne l'ignore pas). Voir la section Son propre php.ini.

-d <key=value>

Définit la valeur d'une directive de configuration PHP pour les tests. Ce paramètre peut être utilisé plusieurs fois.

tester -d max_execution_time=20

-s

Affiche des informations sur les tests ignorés.

--stop-on-fail

Tester arrête les tests dès le premier test qui échoue.

-j <num>

Indique le nombre de processus parallèles dans lesquels exécuter les tests. La valeur par défaut est 8. Pour exécuter les tests séquentiellement, utilisez la valeur 1.

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

Définit le format de sortie. Le format par défaut est console. Vous pouvez indiquer le nom du fichier dans lequel la sortie sera écrite (par exemple -o junit:output.xml). L'option -o peut être répétée plusieurs fois pour générer plusieurs formats à la fois.

console : identique au format par défaut, mais le logo ASCII n'est pas affiché
console-lines : semblable à console, mais le résultat de chaque test est indiqué sur une ligne distincte avec des informations supplémentaires
tap : format TAP, adapté au traitement automatisé
junit : format JUnit XML, lui aussi adapté au traitement automatisé
log : affiche le déroulement des tests. Contient tous les tests échoués, ignorés et aussi réussis
none : rien n'est affiché

-w | --watch <path>

Après avoir terminé les tests, Tester ne se termine pas mais continue de tourner en surveillant les fichiers PHP du répertoire indiqué. Lorsqu'un fichier change, il relance les tests. Ce paramètre peut être utilisé plusieurs fois si vous voulez surveiller plusieurs répertoires.

Utile lors du refactoring d'une bibliothèque ou du débogage des tests.

tester --watch src tests

-i | --info

Affiche des informations sur l'environnement d'exécution des tests. Par exemple :

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 charge au démarrage le script PHP indiqué. La variable Tester\Runner\Runner $runner y est disponible. Supposons un fichier tests/runner-setup.php au contenu suivant :

$runner->outputHandlers[] = new MyOutputHandler;

Nous lançons Tester avec :

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

--temp <path>

Définit le chemin du répertoire des fichiers temporaires de Tester. La valeur par défaut est celle renvoyée par sys_get_temp_dir(). Vous serez averti si la valeur par défaut n'est pas valide.

Si vous ne savez pas quel répertoire est utilisé, lancez Tester avec le paramètre --info.

--colors 1|0

Par défaut, Tester détecte si le terminal prend en charge les couleurs et colorise sa sortie en conséquence. Cette option remplace la détection automatique. Vous pouvez régler la colorisation globalement à l'aide de la variable d'environnement NETTE_TESTER_COLORS.

--coverage <path>

Tester génère un rapport indiquant quelle part du code source est couverte par les tests. Cette option exige que l'extension PHP Xdebug ou PCOV soit installée, ou bien le SAPI PHPDBG, qui est plus rapide. L'extension du fichier cible détermine son format : HTML ou Clover XML.

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

La priorité de choix du moteur de couverture est la suivante :

PCOV
PHPDBG
Xdebug

Avec PHPDBG, des tests volumineux peuvent échouer par épuisement de la mémoire. La collecte des informations de couverture de code consomme beaucoup de mémoire. Dans ce cas, appeler Tester\CodeCoverage\Collector::flush() dans votre test peut aider. Cela écrit les données collectées sur le disque et libère la mémoire. L'appel n'a d'effet qu'avec le moteur PHPDBG ; avec PCOV, Xdebug, ou quand la collecte de données n'est pas en cours, il ne fait rien.

Voir un `exemple de rapport HTML de couverture de code.

--coverage-src <path>

S'utilise avec l'option --coverage. <path> est le chemin du code source pour lequel le rapport est généré. Peut être utilisée plusieurs fois.

Son propre php.ini

Vous pouvez utiliser un fichier php.ini personnalisé pour vos tests. Si vous avez besoin d'extensions particulières ou de réglages INI spécifiques, nous recommandons de créer votre propre fichier php.ini et de le distribuer avec vos tests. Lancez ensuite Tester avec l'option -c, par exemple tester -c tests/php.ini tests. Le fichier INI peut ressembler à ceci :

[PHP]

extension=php_pdo_mysql.dll
extension=php_pdo_pgsql.dll

memory_limit=512M

Avec -c, Tester ignore la configuration système (lance PHP avec le drapeau -n). Si vous voulez inclure aussi la configuration système, ajoutez l'option -C : tester -c tests/php.ini -C tests. Même en combinant -c et -C, les autres fichiers INI de /etc/php/conf.d/*.ini ne sont pas chargés sous UNIX. C'est un comportement de PHP, pas propre à Tester.

Avant la version 2.6, sans -c, Tester lançait PHP avec le drapeau -n, c'est-à-dire sans php.ini ; l'option -C supprimait ce comportement. Depuis la version 2.6, le php.ini système est chargé par défaut. Le comportement avec -c reste inchangé.