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 :

  1. Chargement de l”autoloader
  2. Chargement du fichier de configuration
  3. 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.1.2. Depuis une installation composer

Dans le cas où vous utilisez atoum en ayant cloné le dépôt Github ou l’ayant installé via Composer, les modèles se trouvent dans /path/to/atoum/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 ;)