README - tharkun/atoum GitHub Wiki

README en version française

atoum, un framework de tests unitaires pour PHP simple, moderne et intuitif !

Tout comme SimpleTest ou PHPUnit, atoum est un framework de tests unitaires spécifique au langage PHP.
Cependant, il a la particularité d'avoir été conçu dès le départ pour :

  • Être Rapide à mettre en œuvre ;
  • Simplifier le développement des tests ;
  • Permettre l'écriture de tests unitaires fiables, lisibles et explicites ;

Pour cela, il utilise massivement les possibilités offertes par PHP 5.3, pour fournir au développeur une nouvelle façon d'écrire des tests unitaires.
Ainsi, il s'installe et s'intégre très facilement dans un projet puisqu'il se présente sous la forme d'une unique archive PHAR, qui est le seul et unique point d'entrée du développeur.
De plus, grâce à son interface fluide, il permet la rédaction des tests unitaires en langage quasiment naturel.
Il facilite également la mise en œuvre du bouchonnage au sein des tests, grâce à une utilisation intelligente des fonctions anonymes et des fermetures.
atoum propose nativement et par défaut d'exécuter chaque test unitaire au sein d'un processus PHP séparé afin d'en garantir l'isolation.
Et évidemment, son utilisation dans le cadre d'un processus d'intégration continue ne pose aucun problème, et de part sa conception, il est très facile de l'adapter à des besoins spécifiques.
atoum réalise de plus tout cela sans sacrifier les performances, puisqu'il a été développé pour avoir une empreinte mémoire réduite tout en autorisant une exécution rapide des tests.
Il est de plus à même de générer des rapports d'exécution des tests unitaires au format Xunit, ce qui lui permet d'être compatible avec des outils d'intégration continue tel que Jenkins.
atoum permet de plus de générer des rapports de couverture de code, afin de permettre la supervision des tests unitaires.
Enfin, même s'il est actuellement développé principalement sous UNIX, il est également fonctionnel sous Windows.

Prérequis pour utiliser atoum

atoum nécéssite absolument une version de PHP supérieure ou égale à 5.3 pour fonctionner.
Si vous souhaitez utiliser atoum via son archive PHAR, il faut de plus que [PHP](http://www.php.net] dispose du module phar, Normalement disponible par défaut.
Afin de vérifier que vous disposez de ce module sous UNIX, il vous suffit d'exécuter la commande suivante dans votre terminal :

# php -m | grep -i phar

Si Phar ou un équivalent s'affiche, le module est installé.
La génération des rapports au format Xunit nécessite le module xml.
Afin de vérifier que vous disposez de ce module sous UNIX, il vous suffit d'exécuter la commande suivante dans votre terminal :

# php -m | grep -i xml

Si Xml ou un équivalent s'affiche, le module est installé.

L'extension Xdebug est quand à elle requise si vous désirez surveiller le taux de couverture de votre code par vos tests unitaires. Afin de vérifier que vous disposez de ce module sous UNIX, il vous suffit d'exécuter la commande suivante dans votre terminal :

# php -m | grep -i xdebug

Si Xdebug ou un équivalent s'affiche, le module est installé.--

Un framework de tests unitaires opérationnel en 5 minutes !

Étape 1 : Installez atoum

Il suffit pour cela que vous téléchargiez son archive PHAR et la stockiez à l'emplacement de votre choix, par exemple dans /path/to/project/tests/mageekguy.atoum.phar.
Cette archive PHAR contient la dernière version de développement ayant passé avec succès l'intégralité des tests unitaires d'atoum.
Le code source d'atoum est également disponible via son dépôt sur github.

Étape 2 : Écrivez votre test

À l'aide de votre éditeur favori, créez le fichier path/to/project/tests/units/helloWorld.php et ajoutez-y le code suivant :

<?php

namespace vendor\project\tests\units;

require_once 'path/to/mageekguy.atoum.phar';

include_once 'path/to/project/classes/helloWorld.php';

use mageekguy\atoum;
use vendor\project;

class helloWorld extends atoum\test
{
   public function testSay()
   {
      $helloWorld = new project\helloWorld();

      $this->assert
         ->string($helloWorld->say())->isEqualTo('Hello World !')
      ;
   }
}

?>

Étape 3 : Exécutez votre test en ligne de commande

Lancer votre terminal et exécutez l'instruction suivante :

# php path/to/test/file[enter]

Vous devez obtenir le résultat suivant, ou équivalent :

> Atoum version XXX by Frédéric Hardy.
Error: Unattended exception: Tested class 'vendor\project\helloWorld' does not exist for test class 'vendor\project\tests\units\helloWorld'

Étape 4 : Écrivez la classe correspondant à votre test

À nouveau à l'aide de votre éditeur favori, créez le fichier path/to/project/classes/helloWorld.php et ajoutez-y le code suivant :

<?php

namespace vendor\project;

class helloWorld
{
   public function say()
   {
      return 'Hello World !';
   }
}

?>

Étape 5 : Exécutez à nouveau votre test

Toujours votre terminal, exécutez une nouvelle fois l'instruction suivante :

# php path/to/test/file[enter]

Vous devez cette fois obtenir le résultat suivant, ou équivalent :

> Atoum version 288 by Frédéric Hardy.
> Run vendor\project\tests\units\helloWorld...
[S___________________________________________________________][1/1]
=> Test duration: 0.00 second.
=> Memory usage: 0.25 Mb.
> Total test duration: 0.00 second.
> Total test memory usage: 0.25 Mb.
> Code coverage value: 100.00%
> Running duration: 0.08 second.
> Success (1 test, 1 method, 2 assertions, 0 error, 0 exception) !

Étape 6 : Complétez vos tests et recommencez le cycle à partir de l'étape 3

<?php

namespace vendor\project\tests\units;

require_once 'path/to/mageekguy.atoum.phar';

include_once 'path/to/project/classes/helloWorld.php';

use mageekguy\atoum;
use vendor\project;

class helloWorld extends atoum\test
{
   public function test__construct()
   {
      $helloWorld = new project\helloWorld();

      $this->assert
         ->string($helloWorld->say())->isEqualTo('Hello !')
         ->string($helloWorld->say($name = 'Frédéric Hardy'))->isEqualTo('Hello ' . $name . ' !')
      ;
   }
}

?>

Pour aller plus loin

La documentation d'atoum est en cours de rédaction et la seule ressource disponible actuellement est le présent document.
Cependant, si vous désirez explorer plus en avant et immédiatement les possibilités d'atoum, nous vous conseillons :

  • D'exécuter dans votre terminal soit la commande php mageekguy.atoum.phar -h, soit php scripts/runner.php -h ;
  • D'explorer le contenu du répertoire configurations des sources d'atoum, car il contient des exemples de fichier de configuration ;
  • D'explorer le contenu du répertoire tests/units/classes des sources d'atoum, car il contient l'ensemble de ses tests unitaires ;
  • De lire les supports de conférence à son sujet disponible en ligne ;
  • De rejoindre le canal IRC ##atoum sur le réseau freenode ;
  • De poser vos questions par courrier électronique à l'adresse support[AT]atoum(DOT)org ;

Dépannage

L'archive PHAR de atoum semble ne pas fonctionner

Dans ce cas, la première chose à faire est de vous assurer que vous disposez de la dernière version de l'archive.
Pour cela, il suffit de la télécharger à nouveau.
Si elle ne fonctionne toujours pas, exécutez dans un terminal la commande suivante :

# php -n mageekguy.atoum.phar -v

Si vous obtenez le numéro de version d'atoum, c'est que le problème provient de votre configuration de PHP.
Dans la plupart des cas, il s'agit d'extensions, qui sont soit incompatible avec le format PHAR, soit qui empêche l'exécution des archives PHAR par sécurité.
L'extension ioncube semble par exemple incompatible avec les archives PHAR et il faut donc la désactiver si vous l'utilisez, en commentant dans votre php.ini la ligne suivante en la préfixant par le caractère ; :

zend_extension = /path/to/ioncube_loader*.*

L'extension suhosin empêche quand à elle l'exécution des PHAR, et il faut donc modifier sa configuration par défaut afin de pouvoir utiliser atoum, en ajoutant la ligne suivante dans votre fichier php.ini :

suhosin.executor.include.whitelist="phar"

Enfin, si l'exécution d'atoum provoque à l'écran l'affichage de caractères du style ???%, c'est que la directive detect_unicode de votre fichier php.ini est à 1.
Pour résoudre le problème, il suffit donc de la passer à 0 en éditant votre fichier php.ini ou en exécutant atoum à l'aide de la commande suivante :

# php -d detect_unicode=0 mageekguy.atoum.phar [options]

Si ces trois manipulations ne permettent pas à atoum de fonctionner, nous vous invitons à envoyer un courrier électronique à l'adresse support[AT]atoum(DOT)org, décrivant précisément votre configuration ainsi que votre problème.
Vous pouvez également demander de l'aide aux développeurs d'atoum sur le canal IRC ##atoum sur le réseau freenode.

Error: Constant COMPILER_HALT_OFFSET already defined /path/to/mageekguy.atoum.phar

Cette erreur est provoquée par le fait que l'archive PHAR de atoum est incluse à au moins un endroit dans votre code à l'aide de include ou require. Pour résoudre ce problème, il suffit donc d'inclure l'archive uniquement via include_once ou require_once, afin d'empêcher qu'elle ne soit incluse plusieurs fois.