12. Configuration & bootstraping¶
Plusieurs étapes vont se succéder au lancement d’atoum, certaines d’entre elles peuvent être influencées par des fichiers spéciaux.
On peut avoir une vue simplifiée de ces fichiers spéciaux et optionnelle en :
- Chargement de l”autoloader
- Chargement du fichier de configuration
- Chargement du fichier de bootstrap
Note
Vous pouvez utiliser atoum –init pour générer ces fichiers.
12.1. L’autoloader¶
Le fichier d’autoload (autoloader) est ce que vous allez utiliser pour définir comment atoum va trouver la classe à tester.
Le nom du fichier par défaut est .autoloader.atoum.php
. atoum le chargera automatiquement s’il se trouve dans le dossier courant. Vous pouvez le définir dans la ligne de commande avec --autoloader-file
ou -af
(voir les options de la ligne de commande). L’objectif du fichier d’autoloader est de permettre de charger les classes nécessaire pour exécuter les tests. Vous pouvez trouver plus d’informations sur
l’auto-chargement des classes dans le manuel php.
Si l’autoloader n’existe pas, atoum essayera de charger le fichier vendor/autoload.php
de composer. Vous n’aurez donc rien à faire dans la majorité des cas. ;).
12.2. Fichier de configuration¶
Le fichier de configuration vous permet de configurer comment atoum fonctionne.
Si vous nommez votre fichier de configuration .atoum.php
, atoum le chargera automatiquement si ce fichier se trouve dans le répertoire courant. Le paramètre -c
est donc optionnel dans ce cas.
Note
La configuration de atoum supporte l’héritage de fichier. Si vous avez un fichier .atoum.php
dans le répertoire parent, il sera également chargé.
Vous pouvez ainsi avoir un fichier de configuration par défaut afin d’avoir le mode loop ou debug activé par défaut.
12.2.1. Exemple existant¶
atoum fourni un fichier d’exemple basique. Suivant le type d’installation de atoum, il y a plusieurs façons de les voir :
12.2.1.1. Depuis une installation PHAR¶
Si vous utlisez l’archive PHAR, il faut les extraire en utilisant la commande suivante :
php atoum.phar -er /path/to/destination/directory
Une fois l’extraction effectuée, vous devriez avoir dans le répertoire /path/to/destination/directory un répertoire nommé resources/configurations/runner.
12.2.2. Couverture du code¶
Par défaut, si PHP dispose de l’extension Xdebug, atoum indique en ligne de commande le taux de couverture du code par les tests venant d’être exécutés. Certains comportements de la couverture de code peuvent être adaptés via les options de l’interface en ligne de commande.
Si le taux de couverture est de 100%, atoum se contente de l’indiquer. Mais dans le cas contraire, il affiche le taux de couverture globale ainsi que celui de chaque méthode de la classe testée sous la forme d’un pourcentage.
$ php tests/units/classes/template.php
> atoum version DEVELOPMENT by Frederic Hardy (/Users/fch/Atoum)
> PHP path: /usr/local/bin/php
> PHP version:
=> PHP 5.3.8 (cli) (built: Sep 21 2011 23:14:37)
=> Copyright (c) 1997-2011 The PHP Group
=> Zend Engine v2.3.0, Copyright (c) 1998-2011 Zend Technologies
=> with Xdebug v2.1.1, Copyright (c) 2002-2011, by Derick Rethans
> mageekguy\atoum\tests\units\template...
[SSSSSSSSSSSSSSSSSSSSSSSSSSS_________________________________][27/27]
=> Test duration: 15.63 seconds.
=> Memory usage: 8.25 Mb.
> Total test duration: 15.63 seconds.
> Total test memory usage: 8.25 Mb.
> Code coverage value: 92.52%
=> Class mageekguy\atoum\template: 91.14%
==> mageekguy\atoum\template::setWith(): 80.00%
==> mageekguy\atoum\template::resetChildrenData(): 25.00%
==> mageekguy\atoum\template::addToParent(): 0.00%
==> mageekguy\atoum\template::unsetAttribute(): 0.00%
=> Class mageekguy\atoum\template\data: 96.43%
==> mageekguy\atoum\template\data::__toString(): 0.00%
> Running duration: 2.36 seconds.
Success (1 test, 27 methods, 485 assertions, 0 error, 0 exception) !
Il est cependant possible d’obtenir une représentation plus précise du taux de couverture du code par les tests, sous la forme d’un rapport au format HTML. Cela peut être trouver dans l’extension report.
12.2.2.1. Rapport de couverture personnalisée¶
Dans ce répertoire, il y a, entre autre chose intéressante, un modèle de fichier de configuration pour atoum nommé coverage.php.dist
qu’il vous faudra copier à l’emplacement de votre choix. Renommez le coverage.php
.
Une fois le fichier copié, il n’y a plus qu’à le modifier à l’aide de l’éditeur de votre choix afin de définir le répertoire dans lequel les fichiers HTML devront être générés ainsi que l’URL à partir de laquelle le rapport devra être accessible.
Par exemple :
$coverageField = new atoum\report\fields\runner\coverage\html(
'Code coverage de mon projet',
'/path/to/destination/directory'
);
$coverageField->setRootUrl('http://url/of/web/site');
Note
Il est également possible de modifier le titre du rapport à l’aide du premier argument du constructeur de la classe mageekguy\atoum\report\fields\runner\coverage\html
.
Une fois ceci en place, vous avez simplement a utiliser le fichier de configuration (ou l’inclure dans le fichier de configuration) lorsque vous lancer les tests, comme ceci :
$ ./bin/atoum -c path/to/coverage.php -d tests/units
Une fois les tests exécutés, atoum génèrera alors le rapport de couverture du code au format HTML dans le répertoire que vous aurez défini précédemment, et il sera lisible à l’aide du navigateur de votre choix.
Note
Le calcul du taux de couverture du code par les tests ainsi que la génération du rapport correspondant peuvent ralentir de manière notable l’exécution des tests. Il peut être alors intéressant de ne pas utiliser systématiquement le fichier de configuration correspondant, ou bien de les désactiver temporairement à l’aide de l’argument -ncc.
12.2.3. Utilisation de rapports standards¶
atoum est fourni avec de nombreux rapports standards : tap, xunit, html, cli, phing, vim, … Il y a aussi quelques rapports funs. Vous trouverez les plus importants ici.
Note
Si vous souhaitez aller plus loin, il y a une extension dédiée aux rapports appelée reports-extension
.
12.2.3.1. Configuration de rapports¶
12.2.3.1.1. Couverture des branches et chemins¶
Dans le fichier de configuration, vous pouvez activer la couverture des branches et chemins à l’aide de l’option enableBranchAndPathCoverage
. Cette action améliorera la qualité de la couverture du code car elle ne se limitera pas à vérifier qu’une fonction est appelée, mais également
que chaque branche l’est également.
Pour faire simple, si vous avez un if
, le rapport changera si vous cherchez le else
. Vous pouvez aussi l’activer via la ligne commande avec l’option –epbc.
$script->enableBranchAndPathCoverage();
=> Class Foo\Bar: Line: 31.46%
# avec la couverture des branches et chemins
=> Class Foo\Bar: Line: 31.46% Path: 1.50% Branch: 26.06%
12.2.3.1.2. Désactiver la couverture pour une classe¶
Si vous souhaitez exclure certaines classes de la couverture de code, vous pouvez utiliser $script->noCodeCoverageForClasses(\myClass::class)
.
12.2.3.2. Rapport HTML¶
Par défaut, atoum fournit un rapport HTML basique. Pour un rapport plus avancé, vous pouvez utiliser reports-extension.
<?php
$report = $script->addDefaultReport();
$coverageField = new atoum\report\fields\runner\coverage\html('Your Project Name', __DIR__ . '/reports');
// Remplacez cette url par l'url racine de votre site de couverture de code.
$coverageField->setRootUrl('http://url/of/web/site');
$report->addField($coverageField);
12.2.3.3. Rapport CLI¶
Le rapport CLI est celui qui s’affiche quand vous lancez le test. Ce rapport a quelques options de configuration disponibles
- hideClassesCoverageDetails: Désactive la couverture d’une classe.
- hideMethodsCoverageDetails: Désactive la couverture d’une méthode.
<?php
$script->addDefaultReport() // les rapports par défaut incluent celui-ci
->hideClassesCoverageDetails()
->hideMethodsCoverageDetails();
12.2.3.3.1. Afficher le logo d’atoum¶
<?php
$report = $script->addDefaultReport();
// Cette ligne ajoute le logo d'atoum à chaque exécution
$report->addField(new atoum\report\fields\runner\atoum\logo());
// Celle-ci va ajouter un logo vert ou rouge après chaque exécution en fonction du status de cette dernière
$report->addField(new atoum\report\fields\runner\result\logo());
12.2.3.4. Rapport Treemap¶
<?php
$report = $script->addDefaultReport();
$coverageHtmlField = new atoum\report\fields\runner\coverage\html('Your Project Name', __DIR__ . '/reports');
// Remplacez cette url par l'url racine de votre site de couverture de code.
$coverageHtmlField->setRootUrl('http://url/of/web/site');
$report->addField($coverageField);
$coverageTreemapField = new atoum\report\fields\runner\coverage\treemap('Your project name', __DIR__ . '/reports');
$coverageTreemapField
->setTreemapUrl('http://url/of/treemap')
->setHtmlReportBaseUrl($coverageHtmlField->getRootUrl());
$report->addField($coverageTreemapField);
12.2.4. Notifications¶
atoum est capable de vous prévenir lorsque les tests sont exécutés en utilisant plusieurs systèmes de notification : Growl, Mac OS X Notification Center, Libnotify.
12.2.4.1. Growl¶
Cette fonctionnalité nécessite la présence de l’exécutable growlnotify
. Pour vérifier s’il est disponible, utilisez la commande suivante :
$ which growlnotify
Vous aurez alors le chemin de l’exécutable ou alors le message growlnotify not found
s’il n’est pas installé.
Il suffit ensuite d’ajouter le code suivant à votre fichier de configuration :
<?php
$images = '/path/to/atoum/resources/images/logo';
$notifier = new \mageekguy\atoum\report\fields\runner\result\notifier\image\growl();
$notifier
->setSuccessImage($images . DIRECTORY_SEPARATOR . 'success.png')
->setFailureImage($images . DIRECTORY_SEPARATOR . 'failure.png')
;
$report = $script->AddDefaultReport();
$report->addField($notifier, array(atoum\runner::runStop));
12.2.4.2. Mac OS X Notification Center¶
Cette fonctionnalité nécessite la présence de l’exécutable terminal-notifier
. Pour vérifier s’il est disponible, utilisez la commande suivante :
$ which terminal-notifier
Vous aurez alors le chemin de l’exécutable ou alors le message terminal-notifier not found
s’il n’est pas installé.
Note
Rendez-vous sur la page Github du projet pour obtenir plus d’information sur l’installation de terminal-notifier
.
Il suffit ensuite d’ajouter le code suivant à votre fichier de configuration :
<?php
$notifier = new \mageekguy\atoum\report\fields\runner\result\notifier\terminal();
$report = $script->AddDefaultReport();
$report->addField($notifier, array(atoum\runner::runStop));
Sous OS X, vous avez la possibilité de définir une commande qui sera exécutée lorsque l’utilisateur cliquera sur la notification.
<?php
$coverage = new atoum\report\fields\runner\coverage\html(
'Code coverage',
$path = sys_get_temp_dir() . '/coverage_' . time()
);
$coverage->setRootUrl('file://' . $path);
$notifier = new \mageekguy\atoum\report\fields\runner\result\notifier\terminal();
$notifier->setCallbackCommand('open file://' . $path . '/index.html');
$report = $script->AddDefaultReport();
$report
->addField($coverage, array(atoum\runner::runStop))
->addField($notifier, array(atoum\runner::runStop))
;
L’exemple ci-dessus montre comment ouvrir le rapport de couverture du code lorsque l’utilisateur clique sur la notification.
12.2.4.3. Libnotify¶
Cette fonctionnalité nécessite la présence de l’exécutable notify-send
. Pour vérifier s’il est disponible, utilisez la commande suivante :
$ which notify-send
Vous aurez alors le chemin de l’exécutable ou alors le message notify-send not found
s’il n’est pas installé.
Il suffit ensuite d’ajouter le code suivant à votre fichier de configuration :
<?php
$images = '/path/to/atoum/resources/images/logo';
$notifier = new \mageekguy\atoum\report\fields\runner\result\notifier\image\libnotify();
$notifier
->setSuccessImage($images . DIRECTORY_SEPARATOR . 'success.png')
->setFailureImage($images . DIRECTORY_SEPARATOR . 'failure.png')
;
$report = $script->AddDefaultReport();
$report->addField($notifier, array(atoum\runner::runStop));
12.2.5. Configuration du test¶
De nombreuses possibilités sont disponibles pour configurer comment atoum va exécuter le test. Vous pouvez utiliser les arguments en ligne de commande ou le fichier de configuration. Un code simple valant une longue explication, l’exemple suivant devrait être explicite :
<?php
$testGenerator = new atoum\test\generator();
// répertoire contenant le test unitaire. (-d)
$testGenerator->setTestClassesDirectory(__DIR__ . '/test/units');
// le namespace du test unitaire.
$testGenerator->setTestClassNamespace('your\project\namespace\tests\units');
// le runner de votre test unitaire.
$testGenerator->setRunnerPath('path/to/your/tests/units/runner.php');
$script->getRunner()->setTestGenerator($testGenerator);
// ou
$runner->setTestGenerator($testGenerator);
Vous pouvez également définir le répertoire du test avec $runner->addTestsFromDirectory(path)
. atoum chargera toutes les classes qui puissent être testées présentes dans ce dossier tout comme vous pouvez faire
avec l’argument en ligne de commande -d.
<?php
$runner->addTestsFromDirectory(__DIR__ . '/test/units');
12.3. Fichier de bootstrap¶
atoum autorise la définition d’un fichier de bootstrap
qui sera exécuté avant chaque méthode de test et qui permet donc d’initialiser l’environnement d’exécution des tests.
Le nom par défaut du fichier est .bootstrap.atoum.php
, atoum chargera le fichier automatiquement, si celui-ci est situé dans le répertoire courant. Vous pouvez le définir en cli avec -bf
ou --bootstrap-file
.
Il devient ainsi possible de définir, par exemple, de lire un fichier de configuration ou de réaliser toute autre opération nécessaire à la bonne exécution des tests.
La définition de ce fichier de bootstrap peut se faire de deux façons différentes, soit en ligne de commande, soit via un fichier de configuration.
$ ./bin/atoum -bf path/to/bootstrap/file
Note
Le fichier de bootstrap n’est pas un fichier de configuration et , n’as pas les même possibilités.
Dans un fichier de configuration, atoum est configurable via la variable $runner
, qui n’est pas définie dans un fichier de bootstrap
.
De plus, ils ne sont pas inclus au même moment, puisque le fichier de configuration est inclus par atoum avant le début de l’exécution des tests mais après le lancement des tests, alors que le fichier de bootstrap
, s’il est défini, est le tout premier fichier inclus par atoum proprement dit. Enfin, le fichier de bootstrap
peut permettre de ne pas avoir à inclure systématiquement le fichier scripts/runner.php
ou l’archive PHAR de atoum dans les classes de test.
Cependant, dans ce cas, il ne sera plus possible d’exécuter directement un fichier de test directement via l’exécutable PHP en ligne de commande.
Pour cela, il suffit d’inclure dans le fichier de bootstrap
le fichier scripts/runner.php
ou l’archive PHAR d’atoum et d’exécuter systématiquement les tests en ligne de commande via scripts/runner.php
ou l’archive PHAR.
Le fichier de bootstrap
doit donc au minimum contenir ceci :
<?php
// si l'archive PHAR est utilisée :
require_once path/to/atoum.phar;
// ou si vous voulez charger le $runner
// require_once path/atoum/scripts/runner.php
12.4. Amusons-nous avec atoum¶
12.4.1. Rapport¶
Les rapports de tests peuvent être décorés afin d’être plus agréables ou sympa à lire. Pour cela, dans le fichier de configuration d’atoum, ajoutez le code suivant
<?php
// Le fichier de configuration par défaut est .atoum.php
// ...
$stdout = new \mageekguy\atoum\writers\std\out;
$report = new \mageekguy\atoum\reports\realtime\nyancat;
$script->addReport($report->addWriter($stdout));
Vous pouvez aussi essayer \mageekguy\atoum\reports\realtime\santa
comme rapport ;)