<?xml version="1.0" encoding="ISO-8859-1" ?>
<page title="Documentation sur le rapporteur de test" here="Le rapporteur de test">
    <long_title>Documentation SimpleTest : le rapporteur de test</long_title>
    <content>
        <introduction>
            <p>
                SimpleTest suit plutt plus que moins le modle MVC (Modle-Vue-Contrleur). Les classes &quot;reporter&quot; sont les vues et les modles sont vos scnarios de test et leur hirarchie. Le contrleur est le plus souvent masqu  l'utilisateur de SimpleTest  moins de vouloir changer la faon dont les tests sont effectivement excuts, auquel cas il est possible de surcharger les objets &quot;runner&quot; (ceux de l'excuteur) depuis l'intrieur d'un scnario de test. Comme d'habitude avec MVC, le contrleur est plutt indfini et il existe d'autres endroits pour contrler l'excution des tests.
            </p>
        </introduction>
        <section name="html" title="Les rsultats rapports au format HTML">
            <p>
                L'affichage par dfaut est minimal  l'extrme. Il renvoie le succs ou l'chec avec les barres conventionnelles - rouge et verte - et affichent une trace d'arborescence des groupes de test pour chaque assertion errone. Voici un tel chec...
                <div class="demo">
                    <h1>File test</h1>
                    <span class="fail">Fail</span>: createnewfile->True assertion failed.<br />
                    <div style="padding: 8px; margin-top: 1em; background-color: red; color: white;">1/1 test cases complete.
                    <strong>0</strong> passes, <strong>1</strong> fails and <strong>0</strong> exceptions.</div>
                </div>
                Alors qu'ici tous les tests passent...
                <div class="demo">
                    <h1>File test</h1>
                    <div style="padding: 8px; margin-top: 1em; background-color: green; color: white;">1/1 test cases complete.
                    <strong>1</strong> passes, <strong>0</strong> fails and <strong>0</strong> exceptions.</div>
                </div>
                La bonne nouvelle, c'est qu'il existe pas mal de points dans la hirarchie de l'affichage pour crer des sous-classes.
            </p>
            <p>
                Pour l'affichage bas sur des pages web, il y a la classe <code>HtmlReporter</code> avec la signature suivante...
<php><![CDATA[
class HtmlReporter extends SimpleReporter {
    public HtmlReporter($encoding) { ... }
    public makeDry(boolean $is_dry) { ... }
    public void paintHeader(string $test_name) { ... }
    public void sendNoCacheHeaders() { ... }
    public void paintFooter(string $test_name) { ... }
    public void paintGroupStart(string $test_name, integer $size) { ... }
    public void paintGroupEnd(string $test_name) { ... }
    public void paintCaseStart(string $test_name) { ... }
    public void paintCaseEnd(string $test_name) { ... }
    public void paintMethodStart(string $test_name) { ... }
    public void paintMethodEnd(string $test_name) { ... }
    public void paintFail(string $message) { ... }
    public void paintPass(string $message) { ... }
    public void paintError(string $message) { ... }
    public void paintException(string $message) { ... }
    public void paintMessage(string $message) { ... }
    public void paintFormattedMessage(string $message) { ... }
    protected string _getCss() { ... }
    public array getTestList() { ... }
    public integer getPassCount() { ... }
    public integer getFailCount() { ... }
    public integer getExceptionCount() { ... }
    public integer getTestCaseCount() { ... }
    public integer getTestCaseProgress() { ... }
}
]]></php>
                Voici ce que certaines de ces mthodes veulent dire. Premirement les mthodes d'affichage que vous voudrez probablement surcharger...
                <ul class="api">
                    <li>
                        <code>HtmlReporter(string $encoding)</code><br />
                        est le constructeur. Notez que le test unitaire initie le lien  l'affichage plutt que l'oppos. L'affichage est principalement un receveur passif des vnements de tests. Cela permet d'adapter facilement l'affichage pour d'autres systmes en dehors des tests unitaires, tel le suivi de la charge de serveurs. L'&quot;encoding&quot; est le type d'encodage que vous souhaitez utiliser pour l'affichage du test. Pour pouvoir effectuer un rendu correct de la sortie de dbogage quand on utilise le testeur web, il doit correspondre  l'encodage du site test. Les chanes de caractres disponibles sont indiques dans la fonction PHP <a href="http://www.php.net/manual/fr/function.htmlentities.php">html_entities()</a>.
                    </li>
                    <li>
                        <code>void paintHeader(string $test_name)</code><br />
                        est appel une fois, au dbut du test quand l'vnement de dmarrage survient. Le premier vnement de dmarrage est souvent dlivr par le groupe de tests du niveau le plus haut et donc c'est de l que le <code>$test_name</code> arrive. Il peint les titres de la page, CSS, la balise &quot;body&quot;, etc. Il ne renvoie rien du tout (<code>void</code>).
                    </li>
                    <li>
                        <code>void paintFooter(string $test_name)</code><br />
                        est appel  la toute fin du test pour fermer les balises ouvertes par l'entte de la page. Par dfaut il affiche aussi la barre rouge ou verte et le dcompte final des rsultats. En fait la fin des tests arrive quand l'vnement de fin de test arrive avec le mme nom que celui qui l'a initi au mme niveau. Le nid des tests en quelque sorte. Fermer le dernier test finit l'affichage.
                    </li>
                    <li>
                        <code>void paintMethodStart(string $test_name)</code><br />
                        est appel au dbut de chaque mthode de test. Normalement le nom vient de celui de la mthode. Les autres vnements de dpart de test se comportent de la mme manire sauf que celui du groupe de tests indique au rapporteur le nombre de scnarios de test qu'il contient. De la sorte le rapporteur peut afficher une barre de progrs au fur et  mesure que l'excuteur passe en revue les scnarios de test.
                    </li>
                    <li>
                        <code>void paintMethodEnd(string $test_name)</code><br />
                        clt le test lanc avec le mme nom.
                    </li>
                    <li>
                        <code>void paintFail(string $message)</code><br />
                        peint un chec. Par dfaut il ne fait qu'afficher le mot &quot;fail&quot;, une trace d'arborescence affichant la position du test en cours et le message transmis par l'assertion.
                    </li>
                    <li>
                        <code>void paintPass(string $message)</code><br />
                        ne fait rien, par dfaut.
                    </li>
                    <li>
                        <code>string _getCss()</code><br />
                        renvoie les styles CSS sous la forme d'une chane  l'attention de la mthode d'enttes d'une page. Des styles additionnels peuvent tre ajouts ici si vous ne surchargez pas les enttes de la page. Vous ne voudrez pas utiliser cette mthode dans des enttes d'une page surcharge si vous souhaitez inclure le feuille de style CSS d'origine.
                    </li>
                </ul>
                Il y a aussi des accesseurs pour aller chercher l'information sur l'tat courant de la suite de test. Vous les utiliserez pour enrichir l'affichage...
                <ul class="api">
                    <li>
                        <code>array getTestList()</code><br />
                        est la premire mthode trs commode pour les sous-classes. Elle liste l'arborescence courante des tests sous la forme d'une liste de noms de tests. Le premier test -- celui le plus proche du coeur -- sera le premier dans la liste et la mthode de test en cours sera la dernire.
                    </li>
                    <li>
                        <code>integer getPassCount()</code><br />
                        renvoie le nombre de succs atteint. Il est ncessaire pour l'affichage  la fin.
                    </li>
                    <li>
                        <code>integer getFailCount()</code><br />
                        renvoie de la mme manire le nombre d'checs.
                    </li>
                    <li>
                        <code>integer getExceptionCount()</code><br />
                        renvoie quant  lui le nombre d'erreurs.
                    </li>
                    <li>
                        <code>integer getTestCaseCount()</code><br />
                        est le nombre total de scnarios lors de l'excution des tests. Il comprend aussi les tests groups.
                    </li>
                    <li>
                        <code>integer getTestCaseProgress()</code><br />
                        est le nombre de scnarios raliss jusqu' prsent.
                    </li>
                </ul>
                Une modification simple : demander  l'HtmlReporter d'afficher aussi bien les succs que les checs et les erreurs...
<php><![CDATA[
<strong>class ShowPasses extends HtmlReporter {
    
    function paintPass($message) {
        parent::paintPass($message);
        print "&<span class=\"pass\">Pass</span>: ";
        $breadcrumb = $this->getTestList();
        array_shift($breadcrumb);
        print implode("-&gt;", $breadcrumb);
        print "-&gt;$message<br />\n";
    }
    
    function _getCss() {
        return parent::_getCss() . ' .pass { color: green; }';
    }
}</strong>
]]></php>
            </p>
            <p>
                Une mthode qui a beaucoup fait jaser reste la mthode <code>makeDry()</code>. Si vous lancez cette mthode, sans paramtre, sur le rapporteur avant que la suite de test ne soit excute alors aucune mthode de test ne sera appele. Vous continuerez  avoir les vnements entrants et sortants des mthodes et scnarios de test, mais aucun succs ni chec ou erreur, parce que le code de test ne sera pas excut.
            </p>
            <p>
                La raison ? Pour permettre un affichage complexe d'une IHM (ou GUI) qui permettrait la slection de scnarios de test individuels. Afin de construire une liste de tests possibles, ils ont besoin d'un rapport sur la structure du test pour l'affichage, par exemple, d'une vue en arbre de la suite de test. Avec un rapporteur lanc sur une excution sche qui ne renverrait que les vnements d'affichage, cela devient facilement ralisable.
            </p>
        </section>
        <section name="autre" title="Etendre le rapporteur">
            <p>
                Plutt que de modifier l'affichage existant, vous voudrez peut-tre produire une prsentation HTML compltement diffrente, ou mme gnrer une version texte ou XML. Plutt que de surcharger chaque mthode dans  <code>HtmlReporter</code> nous pouvons nous rendre une tape plus haut dans la hirarchie de classe vers <code>SimpleReporter</code> dans le fichier source <em>simple_test.php</em>.
            </p>
            <p>
                Un affichage sans rien, un canevas vierge pour votre propre cration, serait...
<php><![CDATA[
<strong>require_once('simpletest/simple_test.php');</strong>

class MyDisplay extends SimpleReporter {<strong>
    </strong>
    function paintHeader($test_name) {
    }
    
    function paintFooter($test_name) {
    }
    
    function paintStart($test_name, $size) {<strong>
        parent::paintStart($test_name, $size);</strong>
    }
    
    function paintEnd($test_name, $size) {<strong>
        parent::paintEnd($test_name, $size);</strong>
    }
    
    function paintPass($message) {<strong>
        parent::paintPass($message);</strong>
    }
    
    function paintFail($message) {<strong>
        parent::paintFail($message);</strong>
    }
}
]]></php>
                Aucune sortie ne viendrait de cette classe jusqu' un ajout de votre part.
            </p>
        </section>
        <section name="cli" title="Le rapporteur en ligne de commande">
            <p>
                SimpleTest est aussi livr avec un rapporteur en ligne de commande, minime lui aussi. L'interface imite celle de JUnit, sauf qu'elle envoie les messages d'erreur au fur et  mesure de leur arrive. Pour utiliser le rapporteur en ligne de commande, il suffit de l'intervertir avec celui de la version HTML...
<php><![CDATA[
<?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');

    $test = &new GroupTest('File test');
    $test->addTestFile('tests/file_test.php');
    $test->run(<strong>new TextReporter()</strong>);
?>
]]></php>
                Et ensuite d'invoquer la suite de test  partir d'une ligne de commande...
<pre class="shell">
php file_test.php
</pre>
                Bien sr vous aurez besoin d'installer PHP en ligne de commande. Une suite de test qui passerait toutes ses assertions ressemble ...
<pre class="shell">
File test
OK
Test cases run: 1/1, Failures: 0, Exceptions: 0
</pre>
                Un chec dclenche un affichage comme...
<pre class="shell">
File test
1) True assertion failed.
	in createnewfile
FAILURES!!!
Test cases run: 1/1, Failures: 1, Exceptions: 0
</pre>
            </p>
            <p>
                Une des principales raisons pour utiliser une suite de test en ligne de commande tient dans l'utilisation possible du testeur avec un processus automatis. Pour fonctionner comme il faut dans des scripts shell le script de test devrait renvoyer un code de sortie non-nul suite  un chec. Si une suite de test choue la valeur <code>false</code> est renvoye par la mthode <code>SimpleTest::run()</code>. Nous pouvons utiliser ce rsultat pour terminer le script avec la bonne valeur renvoye...
<php><![CDATA[
<?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');

    $test = &new GroupTest('File test');
    $test->addTestFile('tests/file_test.php');
    <strong>exit ($test->run(new TextReporter()) ? 0 : 1);</strong>
?>
]]></php>
                Bien sr l'objectif n'est pas de crer deux scripts de test, l'un en ligne de commande et l'autre pour un navigateur web, pour chaque suite de test. Le rapporteur en ligne de commande inclut une mthode pour dterminer l'environnement d'excution...
<php><![CDATA[
<?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');

    $test = &new GroupTest('File test');
    $test->addTestFile('tests/file_test.php');
    <strong>if (TextReporter::inCli()) {</strong>
        exit ($test->run(new TextReporter()) ? 0 : 1);
    <strong>}</strong>
    $test->run(new HtmlReporter());
?>
]]></php>
                Il s'agit l de la forme utilise par SimpleTest lui-mme.
            </p>
        </section>
        <section name="xml" title="Test distant">
            <p>
                SimpleTest est livr avec une classe <code>XmlReporter</code> utilise pour de la communication interne. Lors de son excution, le rsultat ressemble ...
<pre class="shell"><![CDATA[
<?xml version="1.0"?>
<run>
  <group size="4">
    <name>Remote tests</name>
    <group size="4">
      <name>Visual test with 48 passes, 48 fails and 4 exceptions</name>
      <case>
        <name>testofunittestcaseoutput</name>
        <test>
          <name>testofresults</name>
          <pass>This assertion passed</pass>
          <fail>This assertion failed</fail>
        </test>
        <test>
          ...
        </test>
      </case>
    </group>
  </group>
</run>
]]></pre>
                Vous pouvez utiliser ce format avec le parseur fourni dans SimpleTest lui-mme. Il s'agit de <code>SimpleTestXmlParser</code> et se trouve <em>xml.php</em>  l'intrieur du paquet SimpleTest...
<php><![CDATA[
<?php
    require_once('simpletest/xml.php');
    
    ...
    $parser = &new SimpleTestXmlParser(new HtmlReporter());
    $parser->parse($test_output);
?>
]]></php>
                <code>$test_output</code> devrait tre au format XML,  partir du rapporteur XML, et pourrait venir d'une excution en ligne de commande d'un scnario de test.  Le parseur envoie des vnements au rapporteur exactement comme tout autre excution de test. Il y a des occasions bizarres dans lesquelles c'est en fait trs utile.
            </p>
            <p>
                Un problme des trs grandes suites de test , c'est qu'elles peuvent venir  bout de la limite de mmoire par dfaut d'un process PHP - 8Mb. En plaant la sortie des groupes de test dans du XML et leur excution dans des process diffrents, le rsultat peut tre pars  nouveau pour agrger les rsultats avec moins d'impact sur le test au premier niveau.
            </p>
            <p>
                Parce que la sortie XML peut venir de n'importe o, a ouvre des possibilits d'agrgation d'excutions de test depuis des serveur distants. Un scnario de test pour le raliser existe dj  l'intrieur du framework SimpleTest, mais il est encore exprimental...
<php><![CDATA[
<?php
    <strong>require_once('../remote.php');</strong>
    require_once('../reporter.php');
    
    $test_url = ...;
    $dry_url = ...;
    
    $test = &new GroupTest('Remote tests');
    $test->addTestCase(<strong>new RemoteTestCase($test_url, $dry_url)</strong>);
    $test->run(new HtmlReporter());
?>
]]></php>
                <code>RemoteTestCase</code> prend la localisation relle du lanceur de test, tout simplement un page web au format XML. Il prend aussi l'URL d'un rapporteur initi pour effectuer une excution sche. Cette technique est employe pour que les progrs soient correctement rapports vers le haut. <code>RemoteTestCase</code> peut tre ajout  une suite de test comme n'importe quel autre groupe de tests.
            </p>
        </section>
    </content>
    <internal>
        <link>
            Afficher <a href="#html">les rsultats en HTML</a>
        </link>
        <link>
            Afficher et <a href="#autres">rapporter les rsultats</a> dans d'autres formats
        </link>
        <link>
            Utilis <a href="#cli">SimpleTest depuis la ligne de commande</a>
        </link>
        <link>
            <a href="#xml">Utiliser XML</a> pour des tests distants
        </link>
    </internal>
    <external>
        <link>
            La page du projet SimpleTest sur <a href="http://sourceforge.net/projects/simpletest/">SourceForge</a>.
        </link>
        <link>
            La page de tlchargement de SimpleTest sur <a href="http://www.lastcraft.com/simple_test.php">LastCraft</a>.
        </link>
        <link>
            L'<a href="http://simpletest.sourceforge.net/">API pour dveloppeur de SimpleTest</a> donne tous les dtails sur les classes et les assertions disponibles.
        </link>
    </external>
    <meta>
        <keywords>
            test unitaire en php,
            documentation,
            marcus baker,
            perrick penet
            test simple,
            simpletest,
            test distant,
            tests xml,
            test automatis
        </keywords>
    </meta>
</page>