Introduction aux tests unitaires avec PHPUnit 3.1

Mes remerciements à Guillaume Rossolini pour ses critiques et sa relecture.

Pour aborder ce tutoriel dans les meilleures conditions, vous devez :

• maîtriser le paradigme orienté objet PHP 5.

• Bibliothèque PEAR (Guide d'installation de PEAR).
• Pouvoir exécuter PHP en ligne de commande.

Le langage PHP est un langage de programmation flexible, permissif et facile à appréhender. Les principes et contraintes de conception généralement imposées dans les langages à vocation industrielle (C/C++, Java, etc.) ne s'appliquent pas nécessairement avec PHP.

Le programmeur est seul maître à bord, il choisit la précision avec laquelle il souhaite intégrer un paradigme, que ce soit impératif, fonctionnel ou orienté objet, tout comme il décide de structurer ou non son développement par rapport à des processus éprouvés. Cette grande liberté est à l'origine du succès du langage, mais c'est également son plus grand défaut.

Beaucoup de développeurs PHP qui n'ont pas de formation spécifique en programmation ou qui sont peu expérimentés ne perçoivent pas l'importance d'un processus de développement, et de test en particulier.

L'absence d'une forme structurée de tests engendre notamment les problématiques suivantes.

Le code source n'est pas testé en profondeur : cela a pour conséquence des aléas de « postpublication », plus ou moins critiques. Le plus souvent il s'agit d'instabilités dans l'application ou des problèmes de sécurité classiques.

Le code source n'est pas robuste : toute modification du code source (refactorisation, ajout de fonctionnalités) est susceptible d'engendrer des régressions.

Le code source n'est pas réutilisable, pas transmissible : si un autre développeur doit vous assister ou reprendre votre travail, il sera confronté d'une part à votre code source et d'autre part à l'absence d'un protocole de test uniformisé.

Le code source n'est pas évolutif : il va sans dire, plus votre application aura une structure complexe et plus vous peinerez à déceler des erreurs et problèmes de conception de manière empirique. Vous serez contraint à moyen terme, de reprogrammer entièrement votre application.

Tout ceci aura non seulement un impact sur la fiabilité de votre programme (et vos prestations de service), mais également sur le temps alloué pour le développement et la maintenance du projet, avec les tracas que cela implique pour vous et vos utilisateurs finals.

Bien que les tests unitaires soient primordiaux, ils ne résoudront pas les problèmes d'analyse et conception (au mieux, ils les mettront en évidence), c'est pourquoi vous devez garder en tête que la qualité finale de votre produit dépend de votre méthodologie de travail dans son ensemble.

Cette brève introduction méthodologique fournit un processus et quelques conseils vous permettant d'utiliser les tests unitaires dans vos projets PHP. Elle n'a pas pour but d'être exhaustive, si vous souhaitez avoir d'amples informations sur les sujets abordés, consultez les références en fin de chapitre.

Le processus qui vous est proposé ci-dessus fait abstraction des contraintes liées à la gestion de projet (cahier des charges, organisation interne, etc.) ainsi que de la phase d'analyse. Il est basé sur le développement piloté par les tests (TDD) et s'adresse particulièrement aux développeurs PHP autonomes.

Si vous développez en équipe, la base restera sensiblement la même, mais vous devrez fournir des précisions au niveau de l'organisation et du partage des tâches, notamment.

Le développement piloté par les tests (Test-Driven Development, ou TDD) est une méthode de développement mettant les tests unitaires au premier plan, on peut résumer son processus en cinq étapes :

1. Ajouter un test ;
2. Vérifier qu'il ne passe pas ;
3. Implémenter la fonctionnalité ;
4. Exécuter les tests unitaires - déboguer en cas d'échec ;
5. Refactoriser le code source - exécuter à nouveau les tests unitaires, passer à l'objectif suivant…

En reprenant le processus ci-dessus, vous observerez que l'approche TDD débute dès la phase de conception. Dans l'idéal, la structure de votre application devrait être modélisée dans un éditeur UML puis son squelette généré directement dans des fichiers PHP. Plusieurs éditeurs UML libres fournissent un générateur de code PHP 5 (nativement ou sous forme de plug-in), notamment ArgoUML (multiplate-forme, notation UML 1.4) et StarUML (pour Windows uniquement, notation UML 2.0).

Parallèlement, vous pouvez modéliser des diagrammes entité-relation (ERD) et générer les schémas de vos bases de données à la volée. Pour ce faire il existe notamment les logiciels DBDesigner 4 (logiciel libre et optimisé pour MySQL), MySQL Workbench (version BETA) ainsi que Toad Data Modeler (version freeware ou commerciale).

Dès que le squelette de votre application sera défini, vous pourrez en faire de même avec les tests unitaires, grâce à PHPUnit et son générateur de gabarits.

Enfin en observant la partie implémentation du processus, vous retrouvez les étapes du TDD en bonne et due forme. La refactorisation a été marquée optionnelle, car elle pourrait être effectuée durant l'implémentation de la méthode, mais aussi dans le cadre d'une maintenance générale du code source. La refactorisation peut être considérée comme un objectif de développement à part entière.

D'amples informations

• Cours de conception.
• Tutoriel sur le développement dirigé par les tests (tutoriel avancé).
• Refactorisation.
• Développement de logiciel.

Vous pouvez utiliser PEAR :

pear channel-discover pear.phpunit.de && pear install phpunit/PHPUnit

ou télécharger et installer manuellement le package via : http://pear.phpunit.de/get/

L'utilitaire de ligne de commande phpunit est le principal outil dédié à la configuration et à l'exécution des tests unitaires.

phpunit --help

II-C-1. Générateur de gabarits▲

phpunit --skeleton MyClass

<?php 
// Call MyClassTest::main() if this source file is executed directly.
if (!defined('PHPUnit_MAIN_METHOD')) {
    define('PHPUnit_MAIN_METHOD', 'MyClassTest::main');
}

require_once 'PHPUnit/Framework.php';

require_once 'MyClass.php';

/**
 * Test class for MyClass.
 * Generated by PHPUnit on 2007-08-11 at 20:01:00.
 */
class MyClassTest extends PHPUnit_Framework_TestCase {
    /**
     * Runs the test methods of this class.
     *
     * @access public
     * @static
     */
    public static function main() {
        require_once 'PHPUnit/TextUI/TestRunner.php';

        $suite  = new PHPUnit_Framework_TestSuite('MyClassTest');
        $result = PHPUnit_TextUI_TestRunner::run($suite);
    }

    /**
     * Sets up the fixture, for example, opens a network connection.
     * This method is called before a test is executed.
     *
     * @access protected
     */
    protected function setUp() {
    }

    /**
     * Tears down the fixture, for example, closes a network connection.
     * This method is called after a test is executed.
     *
     * @access protected
     */
    protected function tearDown() {
    }

    /**
     * @todo Implement testMyMethod().
     */
    public function testMyMethod() {
        // Remove the following lines when you implement this test.
        $this->markTestIncomplete(
          'This test has not been implemented yet.'
        );
    }
}

// Call MyClassTest::main() if this source file is executed directly.
if (PHPUnit_MAIN_METHOD == 'MyClassTest::main') {
    MyClassTest::main();
}
?>

@assert (argument1 [, argument2, ...]) operator value

class MyClass extends PHPUnit_Framework_TestCase
{
    /**
     * @assert (1) > 2
     */
    public function myMethod($value)
    {
        return $value;
    }
}

/**
 * Generated from @assert (1) > 2.
 */
public function testMyMethod() {
    $constraint = $this->greaterThan(2);
    $object     = new myClass;
    $value      = $object->myMethod(1);
    $this->assertThat($value, $constraint);
}

PHPUnit offre une solution particulièrement flexible pour organiser vos tests, vous pouvez les exécuter indépendamment les uns des autres, les grouper en suites, ou rassembler les suites elles-mêmes afin d'exécuter le tout en une seule fois.

En reprenant une partie de l'exemple 1.0, vous remarquerez que le générateur de gabarits propose plusieurs éléments dédiés à la composition de tests :

if (!defined('PHPUnit_MAIN_METHOD')) {
    define('PHPUnit_MAIN_METHOD', 'MyClassTest::main');
}

Cette structure définit la première méthode qui sera exécutée si le fichier est appelé directement. Si la classe de test est incluse dans une suite, la définition sera ignorée.

public static function main() {
        require_once 'PHPUnit/TextUI/TestRunner.php';

        $suite  = new PHPUnit_Framework_TestSuite('MyClassTest');
        $result = PHPUnit_TextUI_TestRunner::run($suite);
    }

Par défaut, la méthode statique ::main() fournit une implémentation minimale permettant de lancer le test et éventuellement d'y inclure d'autres éléments (cas de test, suites ou autres instructions).

if (PHPUnit_MAIN_METHOD == 'MyClassTest::main') {
    MyClassTest::main();
}
?>

Finalement, la structure ci-dessus appellera la méthode définie en en-tête (::main, dans le cas précis) si le fichier est exécuté directement.

Pour créer une suite de tests, vous devez instancier la classe PHPUnit_Framework_TestSuite, puis ajouter les tests ou suites de tests qui vous intéressent avec les méthodes ::addTest et (ou) ::addTestSuite, comme le montre l'exemple ci-dessous :

public static function main() {
        require_once 'PHPUnit/TextUI/TestRunner.php';

        $suite  = new PHPUnit_Framework_TestSuite('MyClassTest');
        $suite->addTest('MyOtherClassTest');
        $suite->addTestSuite('MyTestSuite');
        $result = PHPUnit_TextUI_TestRunner::run($suite);
    }

public static function main()
    {
        PHPUnit_TextUI_TestRunner::run(self::suite());
    }

    public static function suite()
    {
        $suite = new PHPUnit_Framework_TestSuite('All Tests');
        $suite->addTest(MyOtherClassTest::suite());

    }

De cette manière, vous obtiendrez un code source mieux décomposé et plus lisible.

Pour lancer un seul cas de test ou une suite :

phpunit MyClass

II-E-1. Lancer une suite de tests▲

<?php

require_once 'PHPUnit/Framework.php';
require_once 'PHPUnit/TextUI/TestRunner.php';
require_once 'MyClass.php';
require_once 'MyClassTest.php';

if (!defined('PHPUnit_MAIN_METHOD')) {
    define('PHPUnit_MAIN_METHOD', 'AllTests::main');
}

class AllTests
{
    public static function main()
    {
        PHPUnit_TextUI_TestRunner::run(self::suite());
    }

    public static function suite()
    {
        $suite = new PHPUnit_Framework_TestSuite('All Tests');
        $suite->addTest(MyClassTest::main());

    }
}

if (PHPUnit_MAIN_METHOD == 'AllTests::main') {
   AllTests::main();
}

?>

php AllTests.php

II-E-2. Indicateurs de résultat▲

Voici un exemple récapitulatif de test unitaire.

La classe MyFile a pour attributs un nom (fileName) et une extension (extension) de fichier.

Le nom de fichier doit être une chaîne de caractères de 1 à 32 caractères alphanumériques (ASCII), trait d'union et sous-tiret compris. Tous les autres caractères sont proscrits.

L'extension de fichier doit être composée de 1 à 5 caractères alphanumériques (ASCII).

Diagramme de classe UML de MyFile :

1. Le squelette de la classe MyFile est généré à partir du diagramme de classe susmentionné.
2. Le gabarit de cas de test MyFileTest est généré à partir du squelette de la classe MyFile.

Implémentation du cas de test MyFileTest :

<?php
// Call MyFileTest::main() if this source file is executed directly.
if (!defined('PHPUnit_MAIN_METHOD')) {
    define('PHPUnit_MAIN_METHOD', 'MyFileTest::main');
}

require_once 'PHPUnit/Framework.php';

require_once 'MyFile.php';

/**
 * Test class for MyFile.
 * Generated by PHPUnit on 2007-08-12 at 19:25:50.
 */
class MyFileTest extends PHPUnit_Framework_TestCase {
    /**
     * Runs the test methods of this class.
     *
     * @access public
     * @static
     */
    public static function main() {
        require_once 'PHPUnit/TextUI/TestRunner.php';

        $suite  = new PHPUnit_Framework_TestSuite('MyFileTest');
        $result = PHPUnit_TextUI_TestRunner::run($suite);
    }

    public function testSetFileName() 
    {    
        $file = new MyFile;
        
        $this->assertTrue($file->setFileName('newfile'));
        $this->assertTrue($file->setFileName('newfile1'));
        $this->assertTrue($file->setFileName('new_file'));
        $this->assertTrue($file->setFileName('new-file'));
        
        $this->assertFalse($file->setFileName(null));
        $this->assertFalse($file->setFileName('ThisFileNameIsVeryLongTooLongReallyTooLong'));
        $this->assertFalse($file->setFileName('NewFileWith.ext'));
        $this->assertFalse($file->setFileName('àfile'));
        $this->assertFalse($file->setFileName(1));
    }

    public function testSetExtension() 
    {    
        $file = new MyFile('newFile');
        
        $this->assertTrue($file->setExtension('txt'));
        
        $this->assertFalse($file->setExtension(null));    
        $this->assertFalse($file->setExtension('abcdef'));
        $this->assertFalse($file->setExtension('é'));
        $this->assertFalse($file->setExtension(1));
    }

    public function testGetFileName() 
    {    
        $exceptedFileName = 'newFile';
        
        $file = new MyFile($exceptedFileName);
        
        $this->assertEquals($exceptedFileName, $file->getFileName());
    }

    public function testGetExtension() 
    {
        $exceptedExtension = 'txt';
        
        $file = new MyFile('newFile', $exceptedExtension);
        
        $this->assertEquals($exceptedExtension, $file->getExtension());
    }
}

// Call MyFileTest::main() if this source file is executed directly.
if (PHPUnit_MAIN_METHOD == 'MyFileTest::main') {
    MyFileTest::main();
}
?>

Implémentation de la classe MyFile

<?php

class MyFile 
{
    protected $fileName;

    protected $extension;

    public function __construct($fileName = null, $extension = null) 
    {
        if (!is_null($fileName)) {
            $this->setFileName($fileName);
        }
        
        if (!is_null($extension)) {
            $this->setExtension($extension);
        }
    }
    
    /**
     * Affecte un nom de fichier (de 1 à 32 caractères alphanumériques, trait d'union et sous-tiret compris).
     * @param string $fileName
     * @return boolean
     */
    public function setFileName($fileName) 
    {
        if (!is_string($fileName)) {
            return false;
        }
        
        if (!preg_match('/^[a-z0-9-_]{1,32}$/i',$fileName)) {
            return false;
        } 
        
        $this->fileName = $fileName;
        
        return true;                
    }

    /**
     * Affecte une extension de fichier (de 1 à 5 caractères alphanumériques).
     * @param string $extension
     * @return boolean
     */    
    public function setExtension($extension) 
    {
        if (!is_string($extension)) {
            return false;
        }

        if (!preg_match('/^[a-z0-9]{1,5}$/i',$extension)) {
            return false;
        }
        
        $this->extension = $extension;
        
        return true;    
    }

    /**
     * Retourne le nom de fichier.
     *
     * @return string
     */
    public function getFilename() 
    {
        return $this->fileName;
    }

    /**
     * Retourne l'extension du fichier
     *
     * @return string
     */    
    public function getExtension() 
    {
        return $this->extension;
    }
}

?>

Exécution du test unitaire :

phpunit MyFileTest
PHPUnit 3.1.7 by Sebastian Bergmann.

....

Time: 0 seconds

OK (4 tests)

• Site officiel de PHPUnit.

Ressources Developpez.com 

• PHPEclipse : Programmez librement pour le Web, par Jean-Pierre Grossglauser.
• PHPEdit, un IDE complet pour PHP, par Guillaume Rossolini.
• Compte-rendu de la Conférence Internationale PHP 2006, par Guillaume Rossolini.