source: trunk/server/www/vendors/simpletest/docs/fr/reporter_documentation.html @ 6

Last change on this file since 6 was 6, checked in by sander, 12 years ago

Added SimpleTest? test framework

File size: 24.2 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
4<title>Documentation SimpleTest : le rapporteur de test</title>
5<link rel="stylesheet" type="text/css" href="docs.css" title="Styles">
6</head>
7<body>
8<div class="menu_back"><div class="menu">
9<a href="index.html">SimpleTest</a>
10                |
11                <a href="overview.html">Overview</a>
12                |
13                <a href="unit_test_documentation.html">Unit tester</a>
14                |
15                <a href="group_test_documentation.html">Group tests</a>
16                |
17                <a href="mock_objects_documentation.html">Mock objects</a>
18                |
19                <a href="partial_mocks_documentation.html">Partial mocks</a>
20                |
21                <a href="reporter_documentation.html">Reporting</a>
22                |
23                <a href="expectation_documentation.html">Expectations</a>
24                |
25                <a href="web_tester_documentation.html">Web tester</a>
26                |
27                <a href="form_testing_documentation.html">Testing forms</a>
28                |
29                <a href="authentication_documentation.html">Authentication</a>
30                |
31                <a href="browser_documentation.html">Scriptable browser</a>
32</div></div>
33<h1>Documentation sur le rapporteur de test</h1>
34        This page...
35        <ul>
36<li>
37            Afficher <a href="#html">les résultats en HTML</a>
38        </li>
39<li>
40            Afficher et <a href="#autres">rapporter les résultats</a>
41            dans d'autres formats
42        </li>
43<li>
44            Utilisé <a href="#cli">SimpleTest depuis la ligne de commande</a>
45        </li>
46<li>
47            <a href="#xml">Utiliser XML</a> pour des tests distants
48        </li>
49</ul>
50<div class="content">
51       
52            <p>
53                SimpleTest suit plutÃŽt plus que moins le modÚle MVC (ModÚle-Vue-ContrÃŽleur).
54                Les classes "reporter" sont les vues et les modÚles
55                sont vos scénarios de test et leur hiérarchie.
56                Le contrÃŽleur est le plus souvent masqué à l'utilisateur
57                de SimpleTest à moins de vouloir changer la façon
58                dont les tests sont effectivement exécutés,
59                auquel cas il est possible de surcharger les objets
60                "runner" (ceux de l'exécuteur) depuis l'intérieur
61                d'un scénario de test. Comme d'habitude avec MVC,
62                le contrÃŽleur est plutÃŽt indéfini et il existe d'autres endroits
63                pour contrÃŽler l'exécution des tests.
64            </p>
65       
66        <p><a class="target" name="html"><h2>Les résultats rapportés au format HTML</h2></a></p>
67            <p>
68                L'affichage par défaut est minimal à l'extrême.
69                Il renvoie le succÚs ou l'échec avec les barres conventionnelles
70                - rouge et verte - et affichent une trace d'arborescence
71                des groupes de test pour chaque assertion erronée. Voici un tel échec...
72                <div class="demo">
73                    <h1>File test</h1>
74                    <span class="fail">Fail</span>: createnewfile-&gt;True assertion failed.<br>
75                    <div style="padding: 8px; margin-top: 1em; background-color: red; color: white;">1/1 test cases complete.
76                    <strong>0</strong> passes, <strong>1</strong> fails and <strong>0</strong> exceptions.</div>
77                </div>
78                Alors qu'ici tous les tests passent...
79                <div class="demo">
80                    <h1>File test</h1>
81                    <div style="padding: 8px; margin-top: 1em; background-color: green; color: white;">1/1 test cases complete.
82                    <strong>1</strong> passes, <strong>0</strong> fails and <strong>0</strong> exceptions.</div>
83                </div>
84                La bonne nouvelle, c'est qu'il existe pas mal de points
85                dans la hiérarchie de l'affichage pour créer des sous-classes.
86            </p>
87            <p>
88                Pour l'affichage basé sur des pages web,
89                il y a la classe <span class="new_code">HtmlReporter</span> avec la signature suivante...
90<pre>
91class HtmlReporter extends SimpleReporter {
92    public HtmlReporter($encoding) { ... }
93    public makeDry(boolean $is_dry) { ... }
94    public void paintHeader(string $test_name) { ... }
95    public void sendNoCacheHeaders() { ... }
96    public void paintFooter(string $test_name) { ... }
97    public void paintGroupStart(string $test_name, integer $size) { ... }
98    public void paintGroupEnd(string $test_name) { ... }
99    public void paintCaseStart(string $test_name) { ... }
100    public void paintCaseEnd(string $test_name) { ... }
101    public void paintMethodStart(string $test_name) { ... }
102    public void paintMethodEnd(string $test_name) { ... }
103    public void paintFail(string $message) { ... }
104    public void paintPass(string $message) { ... }
105    public void paintError(string $message) { ... }
106    public void paintException(string $message) { ... }
107    public void paintMessage(string $message) { ... }
108    public void paintFormattedMessage(string $message) { ... }
109    protected string _getCss() { ... }
110    public array getTestList() { ... }
111    public integer getPassCount() { ... }
112    public integer getFailCount() { ... }
113    public integer getExceptionCount() { ... }
114    public integer getTestCaseCount() { ... }
115    public integer getTestCaseProgress() { ... }
116}
117</pre>
118                Voici ce que certaines de ces méthodes veulent dire.
119                PremiÚrement les méthodes d'affichage que vous voudrez probablement surcharger...
120                <ul class="api">
121                    <li>
122                        <span class="new_code">HtmlReporter(string $encoding)</span><br>
123                        est le constructeur. Notez que le test unitaire initie
124                        le lien à l'affichage plutÃŽt que l'opposé.
125                        L'affichage est principalement un receveur passif
126                        des évÚnements de tests. Cela permet d'adapter
127                        facilement l'affichage pour d'autres systÚmes
128                        en dehors des tests unitaires, tel le suivi
129                        de la charge de serveurs.
130                        L'"encoding" est le type d'encodage
131                        que vous souhaitez utiliser pour l'affichage du test.
132                        Pour pouvoir effectuer un rendu correct de la sortie
133                        de débogage quand on utilise le testeur web,
134                        il doit correspondre à l'encodage du site testé.
135                        Les chaînes de caractÚres disponibles
136                        sont indiquées dans la fonction PHP
137                        <a href="http://www.php.net/manual/fr/function.htmlentities.php">html_entities()</a>.
138                    </li>
139                    <li>
140                        <span class="new_code">void paintHeader(string $test_name)</span><br>
141                        est appelé une fois, au début du test quand l'évÚnement
142                        de démarrage survient. Le premier évÚnement de démarrage
143                        est souvent délivré par le groupe de tests du niveau
144                        le plus haut et donc c'est de là que le
145                        <span class="new_code">$test_name</span> arrive.
146                        Il peint les titres de la page, CSS, la balise "body", etc.
147                        Il ne renvoie rien du tout (<span class="new_code">void</span>).
148                    </li>
149                    <li>
150                        <span class="new_code">void paintFooter(string $test_name)</span><br>
151                        est appelé à la toute fin du test pour fermer
152                        les balises ouvertes par l'entête de la page.
153                        Par défaut il affiche aussi la barre rouge ou verte
154                        et le décompte final des résultats.
155                        En fait la fin des tests arrive quand l'évÚnement
156                        de fin de test arrive avec le même nom
157                        que celui qui l'a initié au même niveau.
158                        Le nid des tests en quelque sorte.
159                        Fermer le dernier test finit l'affichage.
160                    </li>
161                    <li>
162                        <span class="new_code">void paintMethodStart(string $test_name)</span><br>
163                        est appelé au début de chaque méthode de test.
164                        Normalement le nom vient de celui de la méthode.
165                        Les autres évÚnements de départ de test
166                        se comportent de la même maniÚre sauf que
167                        celui du groupe de tests indique au rapporteur
168                        le nombre de scénarios de test qu'il contient.
169                        De la sorte le rapporteur peut afficher une barre
170                        de progrÚs au fur et à mesure que l'exécuteur
171                        passe en revue les scénarios de test.
172                    </li>
173                    <li>
174                        <span class="new_code">void paintMethodEnd(string $test_name)</span><br>
175                        clÃŽt le test lancé avec le même nom.
176                    </li>
177                    <li>
178                        <span class="new_code">void paintFail(string $message)</span><br>
179                        peint un échec. Par défaut il ne fait qu'afficher
180                        le mot "fail", une trace d'arborescence
181                        affichant la position du test en cours
182                        et le message transmis par l'assertion.
183                    </li>
184                    <li>
185                        <span class="new_code">void paintPass(string $message)</span><br>
186                        ne fait rien, par défaut.
187                    </li>
188                    <li>
189                        <span class="new_code">string _getCss()</span><br>
190                        renvoie les styles CSS sous la forme d'une chaîne
191                        à l'attention de la méthode d'entêtes d'une page.
192                        Des styles additionnels peuvent être ajoutés ici
193                        si vous ne surchargez pas les entêtes de la page.
194                        Vous ne voudrez pas utiliser cette méthode dans
195                        des entêtes d'une page surchargée si vous souhaitez
196                        inclure le feuille de style CSS d'origine.
197                    </li>
198                </ul>
199                Il y a aussi des accesseurs pour aller chercher l'information
200                sur l'état courant de la suite de test. Vous les utiliserez
201                pour enrichir l'affichage...
202                <ul class="api">
203                    <li>
204                        <span class="new_code">array getTestList()</span><br>
205                        est la premiÚre méthode trÚs commode pour les sous-classes.
206                        Elle liste l'arborescence courante des tests
207                        sous la forme d'une liste de noms de tests.
208                        Le premier test -- celui le plus proche du coeur --
209                        sera le premier dans la liste et la méthode de test
210                        en cours sera la derniÚre.
211                    </li>
212                    <li>
213                        <span class="new_code">integer getPassCount()</span><br>
214                        renvoie le nombre de succÚs atteint. Il est nécessaire
215                        pour l'affichage à la fin.
216                    </li>
217                    <li>
218                        <span class="new_code">integer getFailCount()</span><br>
219                        renvoie de la même maniÚre le nombre d'échecs.
220                    </li>
221                    <li>
222                        <span class="new_code">integer getExceptionCount()</span><br>
223                        renvoie quant à lui le nombre d'erreurs.
224                    </li>
225                    <li>
226                        <span class="new_code">integer getTestCaseCount()</span><br>
227                        est le nombre total de scénarios lors de l'exécution des tests.
228                        Il comprend aussi les tests groupés.
229                    </li>
230                    <li>
231                        <span class="new_code">integer getTestCaseProgress()</span><br>
232                        est le nombre de scénarios réalisés jusqu'à présent.
233                    </li>
234                </ul>
235                Une modification simple : demander à l'HtmlReporter d'afficher
236                aussi bien les succÚs que les échecs et les erreurs...
237<pre><strong>
238class ShowPasses extends HtmlReporter {
239   
240    function paintPass($message) {
241        parent::paintPass($message);
242        print "&amp;&lt;span class=\"pass\"&gt;Pass&lt;/span&gt;: ";
243        $breadcrumb = $this-&gt;getTestList();
244        array_shift($breadcrumb);
245        print implode("-&amp;gt;", $breadcrumb);
246        print "-&amp;gt;$message&lt;br /&gt;\n";
247    }
248   
249    function _getCss() {
250        return parent::_getCss() . ' .pass { color: green; }';
251    }
252}</strong>
253</pre>
254            </p>
255            <p>
256                Une méthode qui a beaucoup fait jaser reste la méthode <span class="new_code">makeDry()</span>.
257                Si vous lancez cette méthode, sans paramÚtre,
258                sur le rapporteur avant que la suite de test
259                ne soit exécutée alors aucune méthode de test
260                ne sera appelée. Vous continuerez à avoir
261                les évÚnements entrants et sortants des méthodes
262                et scénarios de test, mais aucun succÚs ni échec ou erreur,
263                parce que le code de test ne sera pas exécuté.
264            </p>
265            <p>
266                La raison ? Pour permettre un affichage complexe
267                d'une IHM (ou GUI) qui permettrait la sélection
268                de scénarios de test individuels.
269                Afin de construire une liste de tests possibles,
270                ils ont besoin d'un rapport sur la structure du test
271                pour l'affichage, par exemple, d'une vue en arbre
272                de la suite de test. Avec un rapporteur lancé
273                sur une exécution sÚche qui ne renverrait
274                que les évÚnements d'affichage, cela devient
275                facilement réalisable.
276            </p>
277       
278        <p><a class="target" name="autre"><h2>Etendre le rapporteur</h2></a></p>
279            <p>
280                PlutÃŽt que de modifier l'affichage existant,
281                vous voudrez peut-être produire une présentation HTML
282                complÚtement différente, ou même générer une version texte ou XML.
283                PlutÃŽt que de surcharger chaque méthode dans
284                <span class="new_code">HtmlReporter</span> nous pouvons nous rendre
285                une étape plus haut dans la hiérarchie de classe vers
286                <span class="new_code">SimpleReporter</span> dans le fichier source <em>simple_test.php</em>.
287            </p>
288            <p>
289                Un affichage sans rien, un canevas vierge
290                pour votre propre création, serait...
291<pre><strong>
292require_once('simpletest/simple_test.php');</strong>
293
294class MyDisplay extends SimpleReporter {<strong>
295    </strong>
296    function paintHeader($test_name) {
297    }
298   
299    function paintFooter($test_name) {
300    }
301   
302    function paintStart($test_name, $size) {<strong>
303        parent::paintStart($test_name, $size);</strong>
304    }
305   
306    function paintEnd($test_name, $size) {<strong>
307        parent::paintEnd($test_name, $size);</strong>
308    }
309   
310    function paintPass($message) {<strong>
311        parent::paintPass($message);</strong>
312    }
313   
314    function paintFail($message) {<strong>
315        parent::paintFail($message);</strong>
316    }
317}
318</pre>
319                Aucune sortie ne viendrait de cette classe jusqu'à un ajout de votre part.
320            </p>
321       
322        <p><a class="target" name="cli"><h2>Le rapporteur en ligne de commande</h2></a></p>
323            <p>
324                SimpleTest est aussi livré avec un rapporteur
325                en ligne de commande, minime lui aussi.
326                L'interface imite celle de JUnit,
327                sauf qu'elle envoie les messages d'erreur au fur
328                et à mesure de leur arrivée.
329                Pour utiliser le rapporteur en ligne de commande,
330                il suffit de l'intervertir avec celui de la version HTML...
331<pre>
332&lt;?php
333require_once('simpletest/unit_tester.php');
334require_once('simpletest/reporter.php');
335
336$test = &amp;new GroupTest('File test');
337$test-&gt;addTestFile('tests/file_test.php');
338$test-&gt;run(<strong>new TextReporter()</strong>);
339?&gt;
340</pre>
341                Et ensuite d'invoquer la suite de test à partir d'une ligne de commande...
342<pre class="shell">
343php file_test.php
344</pre>
345                Bien sûr vous aurez besoin d'installer PHP
346                en ligne de commande. Une suite de test qui
347                passerait toutes ses assertions ressemble à...
348<pre class="shell">
349File test
350OK
351Test cases run: 1/1, Failures: 0, Exceptions: 0
352</pre>
353                Un échec déclenche un affichage comme...
354<pre class="shell">
355File test
3561) True assertion failed.
357    in createnewfile
358FAILURES!!!
359Test cases run: 1/1, Failures: 1, Exceptions: 0
360</pre>
361            </p>
362            <p>
363                Une des principales raisons pour utiliser
364                une suite de test en ligne de commande tient
365                dans l'utilisation possible du testeur avec
366                un processus automatisé. Pour fonctionner comme
367                il faut dans des scripts shell le script de test
368                devrait renvoyer un code de sortie non-nul suite à un échec.
369                Si une suite de test échoue la valeur <span class="new_code">false</span>
370                est renvoyée par la méthode <span class="new_code">SimpleTest::run()</span>.
371                Nous pouvons utiliser ce résultat pour terminer le script
372                avec la bonne valeur renvoyée...
373<pre>
374&lt;?php
375require_once('simpletest/unit_tester.php');
376require_once('simpletest/reporter.php');
377
378$test = &amp;new GroupTest('File test');
379$test-&gt;addTestFile('tests/file_test.php');<strong>
380exit ($test-&gt;run(new TextReporter()) ? 0 : 1);</strong>
381?&gt;
382</pre>
383                Bien sûr l'objectif n'est pas de créer deux scripts de test,
384                l'un en ligne de commande et l'autre pour un navigateur web,
385                pour chaque suite de test.
386                Le rapporteur en ligne de commande inclut
387                une méthode pour déterminer l'environnement d'exécution...
388<pre>
389&lt;?php
390require_once('simpletest/unit_tester.php');
391require_once('simpletest/reporter.php');
392
393$test = &amp;new GroupTest('File test');
394$test-&gt;addTestFile('tests/file_test.php');<strong>
395if (TextReporter::inCli()) {</strong>
396    exit ($test-&gt;run(new TextReporter()) ? 0 : 1);<strong>
397}</strong>
398$test-&gt;run(new HtmlReporter());
399?&gt;
400</pre>
401                Il s'agit là de la forme utilisée par SimpleTest lui-même.
402            </p>
403       
404        <p><a class="target" name="xml"><h2>Test distant</h2></a></p>
405            <p>
406                SimpleTest est livré avec une classe <span class="new_code">XmlReporter</span>
407                utilisée pour de la communication interne.
408                Lors de son exécution, le résultat ressemble à...
409<pre class="shell">
410&lt;?xml version="1.0"?&gt;
411&lt;run&gt;
412  &lt;group size="4"&gt;
413    &lt;name&gt;Remote tests&lt;/name&gt;
414    &lt;group size="4"&gt;
415      &lt;name&gt;Visual test with 48 passes, 48 fails and 4 exceptions&lt;/name&gt;
416      &lt;case&gt;
417        &lt;name&gt;testofunittestcaseoutput&lt;/name&gt;
418        &lt;test&gt;
419          &lt;name&gt;testofresults&lt;/name&gt;
420          &lt;pass&gt;This assertion passed&lt;/pass&gt;
421          &lt;fail&gt;This assertion failed&lt;/fail&gt;
422        &lt;/test&gt;
423        &lt;test&gt;
424          ...
425        &lt;/test&gt;
426      &lt;/case&gt;
427    &lt;/group&gt;
428  &lt;/group&gt;
429&lt;/run&gt;
430</pre>
431                Vous pouvez utiliser ce format avec le parseur
432                fourni dans SimpleTest lui-même.
433                Il s'agit de <span class="new_code">SimpleTestXmlParser</span>
434                et se trouve <em>xml.php</em> Ã  l'intérieur du paquet SimpleTest...
435<pre>
436&lt;?php
437require_once('simpletest/xml.php');
438
439...
440$parser = &amp;new SimpleTestXmlParser(new HtmlReporter());
441$parser-&gt;parse($test_output);
442?&gt;
443</pre>
444                <span class="new_code">$test_output</span> devrait être au format XML,
445                à partir du rapporteur XML, et pourrait venir
446                d'une exécution en ligne de commande d'un scénario de test.
447                Le parseur envoie des évÚnements au rapporteur exactement
448                comme tout autre exécution de test.
449                Il y a des occasions bizarres dans lesquelles c'est en fait trÚs utile.
450            </p>
451            <p>
452                Un problÚme des trÚs grandes suites de test,
453                c'est qu'elles peuvent venir à bout de la limite de mémoire
454                par défaut d'un process PHP - 8Mb.
455                En plaçant la sortie des groupes de test dans du XML
456                et leur exécution dans des process différents,
457                le résultat peut être parsé à nouveau pour agréger
458                les résultats avec moins d'impact sur le test au premier niveau.
459            </p>
460            <p>
461                Parce que la sortie XML peut venir de n'importe où,
462                ça ouvre des possibilités d'agrégation d'exécutions de test
463                depuis des serveur distants.
464                Un scénario de test pour le réaliser existe déjà
465                à l'intérieur du framework SimpleTest, mais il est encore expérimental...
466<pre>
467&lt;?php<strong>
468require_once('../remote.php');</strong>
469require_once('../reporter.php');
470
471$test_url = ...;
472$dry_url = ...;
473
474$test = &amp;new GroupTest('Remote tests');
475$test-&gt;addTestCase(<strong>new RemoteTestCase($test_url, $dry_url)</strong>);
476$test-&gt;run(new HtmlReporter());
477?&gt;
478</pre>
479                <span class="new_code">RemoteTestCase</span> prend la localisation réelle
480                du lanceur de test, tout simplement un page web au format XML.
481                Il prend aussi l'URL d'un rapporteur initié
482                pour effectuer une exécution sÚche.
483                Cette technique est employée pour que les progrÚs
484                soient correctement rapportés vers le haut.
485                <span class="new_code">RemoteTestCase</span> peut être ajouté à
486                une suite de test comme n'importe quel autre groupe de tests.
487            </p>
488       
489    </div>
490        References and related information...
491        <ul>
492<li>
493            La page du projet SimpleTest sur
494            <a href="http://sourceforge.net/projects/simpletest/">SourceForge</a>.
495        </li>
496<li>
497            La page de téléchargement de SimpleTest sur
498            <a href="http://www.lastcraft.com/simple_test.php">LastCraft</a>.
499        </li>
500<li>
501            L'<a href="http://simpletest.org/api/">API pour développeur de SimpleTest</a>
502            donne tous les détails sur les classes et les assertions disponibles.
503        </li>
504</ul>
505<div class="menu_back"><div class="menu">
506<a href="index.html">SimpleTest</a>
507                |
508                <a href="overview.html">Overview</a>
509                |
510                <a href="unit_test_documentation.html">Unit tester</a>
511                |
512                <a href="group_test_documentation.html">Group tests</a>
513                |
514                <a href="mock_objects_documentation.html">Mock objects</a>
515                |
516                <a href="partial_mocks_documentation.html">Partial mocks</a>
517                |
518                <a href="reporter_documentation.html">Reporting</a>
519                |
520                <a href="expectation_documentation.html">Expectations</a>
521                |
522                <a href="web_tester_documentation.html">Web tester</a>
523                |
524                <a href="form_testing_documentation.html">Testing forms</a>
525                |
526                <a href="authentication_documentation.html">Authentication</a>
527                |
528                <a href="browser_documentation.html">Scriptable browser</a>
529</div></div>
530<div class="copyright">
531            Copyright<br>Marcus Baker 2006
532        </div>
533</body>
534</html>
Note: See TracBrowser for help on using the repository browser.