GPL + CeCILL Header change
[scilab.git] / scilab / modules / development_tools / help / fr_FR / test_run.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA
5  * Copyright (C) 2009-2011 - DIGITEO - Michael Baudin
6  * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier: added 32/64bits separation
7  *
8  * Copyright (C) 2012 - 2016 - Scilab Enterprises
9  *
10  * This file is hereby licensed under the terms of the GNU GPL v2.0,
11  * pursuant to article 5.3.4 of the CeCILL v.2.1.
12  * This file was originally licensed under the terms of the CeCILL v2.1,
13  * and continues to be available under such terms.
14  * For more information, see the COPYING file which you should have received
15  * along with this program.
16  * === LICENSE_END ===
17  *
18  -->
19 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="test_run" xml:lang="fr">
20     <refnamediv>
21         <refname>test_run</refname>
22         <refpurpose>
23             Lance les tests unitaires et de non régression présents dans un module ou dans un répertoire. La passe de test vérifie d'abord que le test s'exécute sans erreur, puis que la sortie console (fichier <literal>dia</literal>) est conforme à un fichier de référence préalablement généré (fichier <literal>dia.ref</literal>).
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntaxe</title>
28         <synopsis>
29             status = test_run()
30             status = test_run(module)
31             status = test_run(module, test_name)
32             status = test_run(module, test_name, options, exportToFile)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>module</term>
40                 <listitem>
41                     <para>
42                         Un tableau de chaînes de caractères ou <literal>[]</literal>. Nom des modules ou répertoires à tester, tous les modules internes de scilab si <literal>[]</literal>
43                     </para>
44                     <itemizedlist>
45                         <listitem>
46                             <para>
47                                 le nom d'un module interne de Scilab ("core", "time", ...) ou d'un sous-module ("optimization|neldermead").
48                             </para>
49                         </listitem>
50                         <listitem>
51                             <para>
52                                 le nom d'un module ATOMS ("module_lycee", "nisp", ...). Pour être pris en compte le module doit être chargé à l'appel de test_run().
53                             </para>
54                         </listitem>
55                         <listitem>
56                             <para>
57                                 le chemin absolu vers le répertoire d'un module.
58                             </para>
59                         </listitem>
60                     </itemizedlist>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>test_name</term>
65                 <listitem>
66                     <para>
67                         Un tableau de chaînes de caractères ou <literal>[]</literal>. Le nom des tests à exécuter lors de cette passe de tests, tous les tests si <literal>[]</literal>
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>options</term>
73                 <listitem>
74                     <para>
75                         Un tableau de chaînes de caractères ou <literal>[]</literal>. Les options à utiliser pour la passe de test, les options par défaut si <literal>[]</literal>
76                     </para>
77                     <variablelist>
78                         <varlistentry>
79                             <term>"no_check_ref"</term>
80                             <listitem>
81                                 <para>n'effectue pas la comparaison entre les fichiers .dia et .dia.ref</para>
82                             </listitem>
83                         </varlistentry>
84                         <varlistentry>
85                             <term>"no_check_error_output"</term>
86                             <listitem>
87                                 <para>ignore les messages affichés en sortie d'erreur standard. Cette option peut être utilisé pour certains messages présents en sortie d'erreur dans la localisation par exemple.</para>
88                             </listitem>
89                         </varlistentry>
90                         <varlistentry>
91                             <term>"create_ref"</term>
92                             <listitem>
93                                 <para>génère un fichier .dia.ref (ignore la comparaison avec tout précédent fichier .dia.ref)</para>
94                             </listitem>
95                         </varlistentry>
96                         <varlistentry>
97                             <term>"show_error"</term>
98                             <listitem>
99                                 <para>affiche les 10 dernières lignes d'exécution du script si un test échoue.</para>
100                             </listitem>
101                         </varlistentry>
102                         <varlistentry>
103                             <term>"show_diff"</term>
104                             <listitem>
105                                 <para>
106                                     si une différence avec le fichier .dia.ref est trouvée, affiche la différence avec une commande <literal>diff -u</literal>
107                                 </para>
108                             </listitem>
109                         </varlistentry>
110                         <varlistentry>
111                             <term>"list"</term>
112                             <listitem>
113                                 <para>liste les tests disponibles (aucun test n'est exécuté)</para>
114                             </listitem>
115                         </varlistentry>
116                         <varlistentry>
117                             <term>"help"</term>
118                             <listitem>
119                                 <para>affiche des exemples d'utilisation de cette commande</para>
120                             </listitem>
121                         </varlistentry>
122                         <varlistentry>
123                             <term>"mode_nw"</term>
124                             <listitem>
125                                 <para>ajoute l'option "-nw" au lancement de chaque test</para>
126                             </listitem>
127                         </varlistentry>
128                         <varlistentry>
129                             <term>"mode_nwni"</term>
130                             <listitem>
131                                 <para>ajoute l'option "-nwni" au lancement de chaque test</para>
132                             </listitem>
133                         </varlistentry>
134                         <varlistentry>
135                             <term>"mode_nwni_profiling"</term>
136                             <listitem>
137                                 <para>ajoute les options "-nwni -profiling" pour permettre le profiling (seulement disponible sous linux)</para>
138                             </listitem>
139                         </varlistentry>
140                         <varlistentry>
141                             <term>"nonreg_tests"</term>
142                             <listitem>
143                                 <para>lance uniquement les tests de non régression</para>
144                             </listitem>
145                         </varlistentry>
146                         <varlistentry>
147                             <term>"unit_tests"</term>
148                             <listitem>
149                                 <para>lance uniquement les tests unitaires</para>
150                             </listitem>
151                         </varlistentry>
152                         <varlistentry>
153                             <term>"skip_tests"</term>
154                             <listitem>
155                                 <para>
156                                     ignore les tests spécifiés dans <term>test_name</term>
157                                 </para>
158                             </listitem>
159                         </varlistentry>
160                         <varlistentry>
161                             <term>"enable_lt"</term>
162                             <listitem>
163                                 <para>active les tests taggés à long temps d'exécution</para>
164                             </listitem>
165                         </varlistentry>
166                         <varlistentry>
167                             <term>"short_summary"</term>
168                             <listitem>
169                                 <para>n'affiche pas les statistiques complètes d'exécutions (seuls le nombre de tests exécutés, réussis, échoués et ignorés sont affichés sur une seule ligne de résumé)</para>
170                             </listitem>
171                         </varlistentry>
172                     </variablelist>
173                 </listitem>
174             </varlistentry>
175             <varlistentry>
176                 <term>exportToFile</term>
177                 <listitem>
178                     <para>
179                         une chaîne de caractères. Chemin d'accès à un fichier d'export.
180                     </para>
181                     <para>
182                         Exporte le resultat de la passe de test dans le fichier XML <varname>exportToFile</varname>. Ce fichier suit le format XUnit.
183                         L'utilisation de cet argument d'entrée active automatiquement les options <literal>"show_diff"</literal> et <literal>"show_error"</literal>.
184                     </para>
185                     <para>
186                         Si le fichier spécifié par <varname>exportToFile</varname> existe préalablement, les résultats de tests sont ajoutés en fin de fichier.
187                     </para>
188                 </listitem>
189             </varlistentry>
190             <varlistentry>
191                 <term>status</term>
192                 <listitem>
193                     <para>
194                         Une valeur booléenne.
195                         Renvoie %t dans le cas où aucune erreur n'est détectée pour cette passe.
196                         Renvoie %f sinon.
197                     </para>
198                 </listitem>
199             </varlistentry>
200         </variablelist>
201     </refsection>
202     <refsection>
203         <title>Description</title>
204         <para>
205             Cherche les fichiers .tst dans les répertoires unit_tests et nonreg_tests, les exécute et affiche un résumé des succès et échecs pour la passe de test.
206             Les ficheirs .tst se trouvent dans les répertoire SCI+"/modules/*/tests/unit_tests" et SCI+"/modules/*/tests/nonreg_tests".
207         </para>
208         <para>
209             Tout d'abord, <literal>test_run</literal> vérifie que le test ne produit aucune erreur.
210             Si le test produit une erreur, le test est considéré en échec.
211         </para>
212         <para>
213             Ensuite, <literal>test_run</literal> s'assure que les commandes et l'affichage de leurs résultats dans la console sont conformes à un fichier de référence préalablement constitué. Chaque exécution d'un test donne lieu à un fichier <literal>.dia</literal> qui est comparé à une fichier <literal>.dia.ref</literal>.
214             Le fichier <literal>.dia.ref</literal> doit se trouver dans le même répertoire que le fichier <literal>.tst</literal> correspondant.
215             Si les deux fichiers sont différents le test est considéré en échec.
216         </para>
217         <para>
218             Des tags spécifiques insérés dans les fichiers .tst peuvent modifier la gestion des fichiers .tst. Ces tags se trouvent dans des commentaires Scilab présents dans le fichier de test.
219         </para>
220         <para>liste des tags disponbiles : </para>
221         <itemizedlist>
222             <listitem>
223                 <para>
224                     &lt;-- INTERACTIVE TEST --&gt;
225                     Le test est taggé Interactif. Les tests interactifs sont ignorés.
226                 </para>
227             </listitem>
228             <listitem>
229                 <para>
230                     &lt;-- LONG TIME EXECUTION --&gt;
231                     Le test est taggé comme étant long à exécuter. Ces test sont ignorés sauf si l'option <literal>"enable-lt"</literal> est spécifiée.
232                 </para>
233             </listitem>
234             <listitem>
235                 <para>
236                     &lt;-- NOT FIXED --&gt;
237                     Le test est taggé comme non corrigé. Les tests non corrigés sont ignorés.
238                 </para>
239             </listitem>
240             <listitem>
241                 <para>
242                     &lt;-- TEST WITH GRAPHIC --&gt;
243                     Ce test est taggé comme nécessitant les fonctionnalités graphiques de Scilab. Ils sont automatiquement exécutés avec l'option de lancement "-nw" (mode par défaut).
244                 </para>
245             </listitem>
246             <listitem>
247                 <para>
248                     &lt;-- NO TRY CATCH --&gt;
249                 </para>
250             </listitem>
251             <listitem>
252                 <para>
253                     &lt;-- NO CHECK ERROR OUTPUT --&gt;
254                     La sortie d'erreur standard de scilab n'est pas vérifiée.
255                 </para>
256             </listitem>
257             <listitem>
258                 <para>
259                     &lt;-- NO CHECK REF --&gt;
260                     Les fichiers <literal>.dia</literal> et <literal>.dia.ref</literal> ne sont pas vérifiés.
261                 </para>
262             </listitem>
263             <listitem>
264                 <para>
265                     &lt;-- ENGLISH IMPOSED --&gt;
266                     Le test est lancé avec l'option <literal>-l en_US</literal>
267                 </para>
268             </listitem>
269             <listitem>
270                 <para>
271                     &lt;-- FRENCH IMPOSED --&gt;
272                     Le test est lancé avec l'option <literal>-l fr_FR</literal>
273                 </para>
274             </listitem>
275             <listitem>
276                 <para>
277                     &lt;-- CLI SHELL MODE --&gt;
278                     (anciennement &lt;-- JVM NOT MANDATORY --&gt; maintenant obsolète)
279                     Le test est exécuté avec l'option de lancement <literal>-nwni</literal>.
280                 </para>
281             </listitem>
282             <listitem>
283                 <para>
284                     &lt;-- WINDOWS ONLY --&gt;
285                     Ignore le test sur tout autre système d'exploitation que Windows.
286                 </para>
287             </listitem>
288             <listitem>
289                 <para>
290                     &lt;-- UNIX ONLY --&gt;
291                     Ignore le test sur tout autre système d'exploitation que Unix.
292                 </para>
293             </listitem>
294             <listitem>
295                 <para>
296                     &lt;-- LINUX ONLY --&gt;
297                     Ignore le test sur tout autre système d'exploitation que GNU/Linux.
298                 </para>
299             </listitem>
300             <listitem>
301                 <para>
302                     &lt;-- MACOSX ONLY --&gt;
303                     Ignore le test sur tout autre système d'exploitations que Mac OS X.
304                 </para>
305             </listitem>
306             <listitem>
307                 <para>
308                     &lt;-- XCOS TEST --&gt;
309                     Charge préalablement les librairies d'Xcos pour exécuter le test.
310                 </para>
311             </listitem>
312         </itemizedlist>
313         <para>
314             Chaque test est éxécuté dans un processus séparé, créé avec la commande <link linkend="host">host</link>.
315             Ceci permet de continuer à lancer les tests même si l'environnement exécutant le test est devenu instable suite aux commandes passées.
316             Cela permet aussi de rendre les tests indépendants les uns des autres.
317         </para>
318     </refsection>
319     <refsection>
320         <title>Tests spécifiques à une platforme</title>
321         <para>
322             Il est possible que le résultat d'un test dépende de l'OS sur lequel il est exécuté.
323             Si tel est le cas, le fichier <literal>.ref</literal> peut dépendre d'une plateforme et le test peut échouer sur les autres plateformes.
324             Des fichiers <literal>.ref</literal> additionnels peuvent être créés avec des extensions spéciques à la plateforme :
325         </para>
326         <itemizedlist>
327             <listitem>
328                 <para>
329                     <literal>.unix.dia.ref</literal> pour la plateforme Unix,
330                 </para>
331             </listitem>
332             <listitem>
333                 <para>
334                     <literal>.linux.dia.ref</literal> pour la plateforme GNU/Linux,
335                 </para>
336             </listitem>
337             <listitem>
338                 <para>
339                     <literal>.linux32.dia.ref</literal> pour la plateforme GNU/Linux 32bits,
340                 </para>
341             </listitem>
342             <listitem>
343                 <para>
344                     <literal>.win.dia.ref</literal> pour la platforme Windows,
345                 </para>
346             </listitem>
347             <listitem>
348                 <para>
349                     <literal>.win32.dia.ref</literal> pour la plateforme Windows 32bits,
350                 </para>
351             </listitem>
352             <listitem>
353                 <para>
354                     <literal>.macosx.dia.ref</literal> pour la plateforme Max OS X.
355                 </para>
356             </listitem>
357         </itemizedlist>
358         <para>
359             L'algorithme est le suivant :
360             D'abord les fichiers <literal>.ref</literal> sont sélectionnés pour le test. Si ces fichiers n'existent pas le fichier <literal>platform.ref</literal> est examiné pour la platforme sur lequel le test est lancé.
361         </para>
362         <itemizedlist>
363             <listitem>
364                 <para>
365                     Sur les plateformes Windows : <literal>.win.dia.ref</literal>, <literal>.win32.dia.ref</literal>
366                 </para>
367             </listitem>
368             <listitem>
369                 <para>
370                     sur les plateformes Mac OS : <literal>.unix.dia.ref</literal>, <literal>.macosx.dia.ref</literal>,
371                 </para>
372             </listitem>
373             <listitem>
374                 <para>
375                     sur les plateformes GNU/Linux : <literal>.unix.dia.ref</literal>, <literal>.linux.dia.ref</literal>, <literal>.linux32.dia.ref</literal>.
376                 </para>
377             </listitem>
378         </itemizedlist>
379     </refsection>
380     <refsection>
381         <title>Examples</title>
382         <programlisting role="example"><![CDATA[
383 // Lance tous les tests
384 // =============================================
385
386 test_run();
387 test_run([]);
388 test_run([],[]);
389
390 // Teste un ou plusieurs modules
391 // =============================================
392
393 // Teste un seul module
394 test_run('time');
395
396 // Teste plusieurs modules
397 test_run(['time','string']);
398
399 // Teste un sous-module
400 test_run('optimization|neldermead');
401
402 // Teste définit par le chemin d'accès
403 test_run(SCI+'/modules/core');
404
405 // Lance un test spécifique
406 // =============================================
407
408 // Un seul test
409 test_run('time','datenum');
410
411 // Plusieurs tests
412 test_run('time',['datenum';'calendar']);
413
414 // Ignorer plusieurs tests
415 // =============================================
416
417 test_run('time',['datenum';'calendar'],'skip_tests');
418
419 // Options
420 // =============================================
421
422 // sans comparaison entre .dia et .dia.ref
423 test_run('time','datenum','no_check_ref');
424
425 // création d'un fichier .dia.ref
426 test_run([],[],'create_ref');
427
428 // liste des tests disponibles
429 test_run([],[],'list');
430
431 // affichage des exemples d'utilisation de la commande
432 test_run([],[],'help');
433
434 // Exécution de tous les tests de non régression
435 test_run([],[],'nonreg_test');
436
437 // Exécution de tous les tests unitaires
438 test_run([],[],'unit_test');
439
440 // non vérification de la sortie d'erreur standard (std err)
441 test_run('boolean','bug_2799','no_check_error_output');
442
443 // Combinaisons d'options
444 test_run([],[],['no_check_ref','mode_nw']);
445  ]]></programlisting>
446         
447         <programlisting role="example"><![CDATA[
448 // lance les tests d'un module externe
449 test_run('SCI/contrib/toolbox_skeleton')
450  ]]></programlisting>
451         
452         <programlisting role="example"><![CDATA[
453 // Export XML Xunit
454 test_run('boolean',[],[],TMPDIR+"/boolean_test_run.xml");
455 test_run('time','datenum',[],TMPDIR+"/time_datenum_test_run.xml");
456  ]]></programlisting>
457     </refsection>
458     <refsection>
459         <title>Design interne</title>
460         <para>
461             Les tests sont exécutés dans un répertoire temporaire, non pas dans le repertoire les contenant.
462         </para>
463         <para>
464             Les scripts de tests ne sont pas exécutés tels qu'écrit, un en-tête et un pied de page spécifiques sont rajoutés à chaque test.
465             Le but est d'instrumenter le fichier de tests afin de rediriger les sorties dans un fichier de log spécique au test.
466         </para>
467     </refsection>
468     <refsection>
469         <title>Historique</title>
470         <revhistory>
471             <revision>
472                 <revnumber>5.4.0</revnumber>
473                 <revdescription>test_run renvoie un statut:
474                     <itemizedlist><listitem>
475                             Renvoie %t si aucune erreur n'est détectée
476                         </listitem>
477                         <listitem>
478                             Renvoie %f si une erreur est détectée
479                         </listitem>
480                     </itemizedlist>
481                     <para>
482                         <literal>show_diff</literal> et <literal>show_error</literal> ajoutés comme nouvelles options
483                     </para>
484                     <para>
485                         tag <literal>CLI SHELL MODE</literal> ajouté. Remplace <literal>JVM NOT MANDATORY</literal> (toujours supporté)
486                     </para>
487                     <para>
488                         <literal>test_run</literal> peut fonctionner sur un module externe.
489                     </para>
490                     <para>
491                         Quatrième paramètre d'appel pour l'export vers un fichier XML XUnit
492                     </para>
493                 </revdescription>
494             </revision>
495             <revision>
496                 <revnumber>5.5.0</revnumber>
497                 <revdescription>séparation 32/64bits disponible</revdescription>
498             </revision>
499             <revision>
500                 <revnumber>6.0.0</revnumber>
501                 <revdescription>mode profiling ajouté pour permettre l'analyse du profil d'exécution avec valgrind (Linux uniquement)</revdescription>
502             </revision>
503         </revhistory>
504     </refsection>
505 </refentry>