L'argument <expectedAnswer> sera comparé au résultat de l'évaluation de l'argument <script>. S'ils correspondent, le test passe, sinon il échoue.
Les contraintes sont utilisées pour déterminer si un test doit être ignoré. Chaque contrainte est stockée comme un indice du tableau ::tcltest::testConstraints. Par exemple, la contrainte unixOnly est définie de la façon suivante:
Si un test est contraint par "unixOnly", il ne s'exécutera que si la valeur de ::tcltest::testConstraints(unixOnly) est vraie. Plusieurs contraintes sont définies dans le package tcltest. Pour ajouter des contraintes spécifiques à un fichier ou à un test, vous pouvez créer l'index correspondant du tableau ::tcltest::testsConstraints dans votre propre fichier de test.
Voici la liste des contraintes définies dans le package
tcltest :
- unix
- le test ne peut s'exécuter que sur les plateformes UNIX
- pc
- le test ne peut s'exécuter que sur les plateformes Windows
- nt
- le test ne peut s'exécuter que sur les plateformes Windows NT
- 95
- le test ne peut s'exécuter que sur les plateformes Windows 95
- 98
- le test ne peut s'exécuter que sur les plateformes Windows 98
- mac
- le test ne peut s'exécuter que sur les plateformes Mac
- unixOrPc
- le test ne peut s'exécuter que sur les plateformes UNIX ou PC
- macOrPC
- le test ne peut s'exécuter que sur les plateformes Mac ou PC
- macOrUnix
- le test ne peut s'exécuter que sur les plateformes Mac ou Unix
- tempNotPc
- le test ne peut être éxécuté sur Windows. C'est un flag pour désactiver temporairement un test.
- tempNotMac
- le test ne peut être éxécuté sur un Mac. C'est un flag pour désactiver temporairement un test.
- unixCrash
- le test se plante s'il est éxécuté sur UNIX. C'est un flag pour désactiver temporairement un test.
- pcCrash
- le test se plante s'il est éxécuté sur PC. C'est un flag pour désactiver temporairement un test.
- macCrash
- le test se plante s'il est éxécuté sur Mac. C'est un flag pour désactiver temporairement un test.
- emptyTest
- le test est vide, et donc ne vaut pas la peine d'être éxécuté, mais il reste afin d'être écrit dans le futur. Cette contrainte provoque l'omission systématique du test.
- knownBug
- le test est connu pour se planter, et le bug n'est pas encore corrigé. Cette contrainte provoque l'omission du test., sauf si l'utilisateur demande le contraire. Voir la section "Introduction" pour plus d'informations.
- nonPortable
- ce test ne peut être effectué que dans l'environnement de développement Tcl/Tk maître. Certains tests sont par nature non portables, parce qu'ils dépendent de choses telles que la longueur de mot du processeur, la configuration du système de fichiers, le gestionnaire de fenêtres, etc. Ces tests sont seulement éxécutés dans l'environnement de développement Tcl principal, où; la configuration est bien connue. Cette contrainte provoque l'omission du test, sauf si l'utilisateur demande le contraire.
- userInteraction
- ce test demande une interaction avec l'utilisateur. Cette contrainte provoque l'omission du test, sauf si l'utilisateur demande le contraire.
- interactive
- ce test ne peut être effectué qu'en mode interactif, c'est à dire si la variable globale tcl_interactive est positionnée à 1.
- nonBlockFiles
- ce test ne peut s'exécuter que si la plateforme supporte de mettre les fichiers en mode non-bloqué.
- asyncPipeClose
- ce test ne peut s'exécuter que si la plateforme supporte "async flush" et "async close" sur un pipe.
- unixExecs
- le test ne peut s'exécuter que si la machine dispose des commandes telles que 'cat', 'echo', etc.
- hasIsoLocale
- le test ne peut s'exécuter que s'il peut passer dans une locale ISO.
- root
- le test ne peut s'exécuter que si l'utilisateur Unix est root
- notRoot
- le test ne peut s'exécuter que si l'utilisateur Unix n'est pas root
- eformat
- le test ne peut s'exécuter que si l'application a une version fonctionnelle de sprintf respectant le format "e" des nombres flottants.
- stdio
- le test ne peut s'exécuter que si l'application courante peut fonctionner au travers d'un pipe
FAIRE FONCTIONNER LES FICHIERS DE TEST
Utiliser la commande suivante pour exécuter un fichier de test qui utilise le package tcltest:
<shell> <testFile> ?<option> ?<value>?? ...
Les options de ligne de commande sont les suivantes (les variables du namespace tcltest qui correspondent à chacune des options sont indiquées entre parenthèses à la fin de la description) :
- -help
- affiche le mode d'utilisation
- -verbose <level>
-
définit le niveau de verbosité comme une sous-chaîne de "bps". Voir la section "Informations issus des tests" pour une explication de cette option. (::tcltest::verbose)
- -match <matchList>
-
effectue seulement les tests qui correspondent aux motifs de "glob" définis dans <matchList>. (::tcltest::match)
- -skip <skipList>
-
n'effectue pas les tests qui correspondent à un ou plusieurs motifs de "glob" définis dans <skipList>. (::tcltest::skip)
- -file <globPatternList>
-
source seulement les fichiers de test dont les noms répondent à l'un des motifs de <globPatternList> définis par rapport au répertoire::tcltest::testsDirectory. Cette option n'a de sens qui si vous effectuez des tests utilisant "all.tcl" en tant que <testFile> au lieu d'effectuer directement des fichiers unitaires de test. (::tcltest::matchFiles)
- -notfile <globPatternList>
-
source tous les fichiers sauf ceux dont les noms répondent à l'un des motifs de <globPatternList> définis par rapport au répertoire::tcltest::testsDirectory. Cette option n'a de sens qui si vous effectuez des tests utilisant "all.tcl" en tant que <testFile> au lieu d'effectuer directement des fichiers unitaires de test. (::tcltest::skipFiles)
- -constraints <list>
-
les tests contenant une contrainte parmi la liste <list> ne seront pas sautés. Notez que les éléments de <list> doivent correspondrent exactement aux contraintes existantes. Ceci est utile si vous voulez avoir la certitude que les tests ayant une contrainte particulière sont effectués (par exemple, si le testeur souhaite que tous les tests contenant la contrainte knownBug soient effectués). (::tcltest::testConstraints(constraintName))
- -limitconstraints <bool>
- Si l'argument de cette option est 1, les tests effectués seront ceux qui respectent les contraintes définies par l'option -constraints. La valeur par défaut de cet indicateur est 0 (false). Ceci est utile si vous voulez exécuter seulement les tests qui répondent aux contraintes listées par l'option -constraints. Un testeur peut vouloir cela par exemple pour n'effectuer que les tests contraints par unixOnly et aucun autre. (::tcltest::limitConstraints)
- -load <script>
- utilisera le script indiqué pour charger les commandes à tester (::tcltest::loadTestedCommands). La valeur par défaut est un script vide. Voir également -loadfile ci-dessous. (::tcltest::loadScript)
- -loadfile <scriptfile>
- utilisera le contenu du fichier indiqué pour charger les commandes à tester (::tcltest::loadTestedCommands).Voir également -load ci-dessus. La valeur par défaut est un script vide. (::tcltest::loadScript)
- -tmpdir <directoryName>
- mettra tous les fichiers temporaires (créés avec ::tcltest::makeFile et ::tcltest::makeDirectory) dans le répertoire indiqué. L'emplacement par défaut est ::tcltest::workingDirectory. (::tcltest::temporaryDirectory)
- -testdir <directoryName>
- cherche les tests à exécuter dans le répertoire indiqué. L'emplacement par défaut est ::tcltest::workingDirectory. (::tcltest::testsDirectory)
- -preservecore <level>
- contrôle pour les fichiers core. Cette option détermine quel niveau de contrôle sera effectué pour les fichiers "core". La valeur par défaut pour <level> est 0. Les niveaux <level> sont définis comme suit :
- 0
- Pas de contrôle - ne pas contrôler les fichiers core à la fin de chaque test, mais les contrôler à chaque fois que::tcltest::cleanupTests est appelé depuis un fichier all.tcl.
- 1
- Vérifier l'existence de fichiers core à la fin de chaque commande de test et à chaque fois que::tcltest::cleanupTests est appelé depuis un fichier all.tcl.
- 2
- Vérifier l'existence de fichiers core à la fin de chaque commande de test et à chaque fois que::tcltest::cleanupTests est appelé depuis un fichier all.tcl. Sauvegarder tout fichier core produit dans ::tcltest::temporaryDirectory. (::tcltest::preserveCore)
- -debug <debugLevel>
- afficher l'information de debug dans stdout. Ceci est utilisé pour débugger le code du système de test. Le niveau de debug par défaut est 0. Les niveaux sont définis ainsi:
- 0
- Ne pas afficher les informations de debug.
- 1
- Afficher l'information indiquant si un test est sauté parce qu'il ne répond à aucune des conditions indiquées dans -match ou ::tcltest::match (userSpecifiedNonMatch), ou parce qu'il répond à une quelconque des conditions indiquées par -skip ou ::tcltest::skip ((userSpecifiedSkip).
- 2
- Affiche le tableau des options interprété par le processeur de ligne de commande, le contenu du tableau ::env, et toutes les variables utilisateur définies dans le namespace courant, quand elles sont utilisées.
- 3
- Affiche l'information concernant ce que font les procédures individuelles de le système de test.(::tcltest::debug)
- -outfile <filename>
- envoie la sortie générée par le package tcltest vers le fichier indiqué. La valeur par défaut est stdout. Notez que la sortie de debug va systématiquement dans stdout, quelque soit la valeur de cette option. (::tcltest::outputChannel)
- -errfile <filename>
- envoie les erreurs générées par le package tcltest vers le fichier indiqué. La valeur par défaut est stderr. (::tcltest::errorChannel)
Une seconde façon d'exécuter les tests est de démarrer un shell, de charger le package tcltest, puis de sourcer un fichier de test approprié ou d'utiliser la commande test. Pour utiliser les options en mode interactif, alimenter la variable qui leur correspond dans le namespace tcltest après avoir chargé le package.
Voir la section "Contraintes de Test" pour toutes les contraintes pré-construites qui peuvent être utilisées dans le tableau ::tcltest::testConstraints. Voir la section "Les variables du namespace Tcltest" pour des informations sur les autres variables définies dans le namespace tcltest.
Une dernière façon d'exécuter les tests est d'indiquer les fichiers de test à exécuter à l'intérieur d'un fichier all.tcl (qui peut être nommé différemment). C'est l'approche utilisée par le système de test de Tcl. Ce fichier charge le package tcltest, définit l'emplacement du répertoire de test (::tcltest::testsDirectory), détermine quels fichiers de test exécuter, source chacun de ces fichiers, appelle ::tcltest::cleanupTests et finit de s'exécuter.
Un fichier all.tcl plus élaboré peut faire du pré- et du post-processing avant de sourcer chaque fichier .test, utiliser des interpréteurs différents pour chaque fichier, ou manipuler des structures de répertoires complexes. Pour un exemple de fichier all.tcl, voir la section "Exemples" de ce document.
RESULTATS DES TESTS
Après que tous les fichiers de test indiqués aient été éxécutés, le nombre de tests réussis, sautés ou échoués est envoyé dans::tcltest::outputChannel. A côté de cette information statistique, la sortie peut être pilotée pour chaque test par la variable ::tcltest::verbose.
::tcltest::verbose peut avoir pour valeur n'importe quelle sous-chaîne ou permutation de "bps". Dans la chaîne "bps", le 'b' se réfère au corps (body) du test, le 'p' se réfère aux tests réussis (passed) et le 's' signifié tests sautés (skipped). La valeur par défaut de ::tcltest::verbose est "b". Si 'b' est présent, alors le corps entier du test est imprimé pour chaque test échoué; sinon seulement le nom du test, la sortie souhaitée et la sortie obtenue sont imprimés pour chaque test échoué. Si 'p' est présent, alors une ligne est imprimée pour chaque test réussi, sinon aucune ligne n'est imprimée pour les tests réussis. Si 's' est présent, alors une ligne (contenant les contraintes qui ont fait que le test a été sauté) est imprimée pour chaque test sauté, sinon aucune ligne n'est imprimée dans ce cas.
Vous pouvez positionner ::tcltest::verbose, soit interactivement (une fois que le package tcltest a été chargé) ou en utilisant l'argument de ligne de commande -verbose, par exemple:
tclsh socket.test -verbose bps
CONTENUS D'UN FICHIER DE TEST
Les fichiers de test doivent commencer par charger le package tcltest:
if {[lsearch [namespace children] ::tcltest] == -1} {
package require tcltest
namespace import ::tcltest::*
}
Les fichiers de tests doivent se terminer par l'appel de la fonction de nettoyage ::tcltest::cleanupTests. La procédure ::tcltest::cleanupTests affiche des statistiques au sujet du nombre de tests réussis, sautés ou échoués, et supprime tous les fichiers créés au moyen des procédures ::tcltest::makeFile et ::tcltest::makeDirectory.
# Supprime les fichiers créés par ces tests
# Retour au répertoire de travail initial
# Supprime les tableaux globaux
::tcltest::cleanupTests
return
Les fichiers de tests doivent se finir par une extension .test. Les noms des fichiers de tests qui contiennent des tests de régression (dits de boîte transparente) doivent être nommés d'après les fichiers de code Tcl ou C qu'ils testent. Par exemple, le fichier de test du programme C "tclCmdAH.c" doit être "cmdAH.test". Les fichiers qui contiennent des tests "boîte noire" (black-box tests) devraient se conformer au motif "*_bb.test".
SELECTIONNER DES TESTS A EXECUTER DANS UN FICHIER
Normalement, quand un fichier est sourcé, tous les tests qu'il contient sont éxécutés. Individuellement, un test sera sauté si l'une des conditions suivantes est vraie:
- [1]
- le nom du test ne correspond pas (en utilisant la correspondance de type "glob") à un ou plusieurs éléments de la variable ::tcltest::match.
- [2]
- le nom du test correspond (en utilisant la correspondance de type "glob") à un ou plusieurs éléments de la variable ::tcltest::skip.
- [3]
- l'argument constraints de l'appel à ::tcltest::call, s'il existe, contient une ou plusieurs valeurs fausses.
Vous pouvez définir ::tcltest::match et/ou ::tcltest::skip, soit interactivement (après que le package tcltest a été sourcé), ou en utilisant les arguments de ligne de commande -match et -skip, par exemple :
tclsh info.test -match '*-5.* *-7.*' -skip '*-7.1*'
Soyez sûr de bien placer les quotes, de façon que votre shell ne fasse pas les substitutions de type glob sur les motifs que vous indiquez (que ce soit bien l'interpréteur tcl qui fasse ces substitutions).
Les contraintes prédéfinies (par exemple knownBug et nonPortable) peuvent être changées soit interactivement (après que le package tcltest a été sourcé), en définissant la variable ::tcltest::testConstraints(constraint), ou en utilisant l'option de ligne de commande -constraints avec le nom de la contrainte comme argument. L'exemple suivant montre comment faire fonctionner des tests contraints par les restrictsions knownBug et nonPortable:
tclsh all.tcl -constraints "knownBug nonPortable"
Voir la section "Contraintes de Test" pour plus d' information sur l'utilisation des contraintes prédéfinies et l'ajout de nouvelles contraintes.
PERSONNALISER LE SYSTEME DE TEST
Pour créer votre propre système de test, créer un fichier .tcl qui contient votre namespace. Dans ce fichier, appeller le package
tcltest (package require tcltest). Les commandes qui peuvent être redéfinies pour personnaliser le système de test sont:
- ::tcltest::PrintUsageInfoHook
- afficher de l'information complémentaire, spécifique à votre situation.
- ::tcltest::processCmdLineArgsFlagHook
- avertir le système au sujet d'options additionnelles que vous voulez qu'il comprenne.
- ::tcltest::processCmdLineArgsHook flags
- traiter les options additionnelles que vous avez communiquées au système de test au travers de ::tcltest::processCmdLineArgsFlagHook.
- ::tcltest::initConstraintsHook
- ajouter des contraintes additionnelles aux contraintes prédéfinies par tcltest.
- ::tcltest::cleanupTestsHook
- faire du nettoyage additionnel
Pour ajouter de nouvelles options à votre système de test personnalisé, redéfinissez ::tcltest::processCmdLineArgsAddFlagHook pour la liste des options additionnelles à interpréter, et ::tcltest::processCmdLineArgsHook pour les traiter effectivement . Par exemple:
proc ::tcltest::processCmdLineArgsAddFlagHook {} {
return [list -flag1 -flag2]
}
proc ::tcltest::processCmdLineArgsHook {flagArray} {
array set flag $flagArray
if {[info exists flag(-flag1)]} {
# Handle flag1
}
if {[info exists flag(-flag2)]} {
# Handle flag2
}
return
}
Vous pouvez aussi vouloir ajouter un mode d'emploi pour ces options. Ce mode d'emploi s'affichera quand l'utilisateur indiquera -help. Pour définir le mode d'emploi additionnel, définissez votre propre procédure ::tcltest::PrintUsageInfoHook. A l'intérieur de cette procédure, vous afficherez le mode d'emploi complémentaire pour chacune des options que vous avez ajoutées.
Pour ajouter de nouvelles contraintes prédéfinies au système de test, définissez votre propre version de ::tcltest::initConstraintsHook. A l'intérieur de cette procédure, vous pouvez compléter le tableau ::tcltest::testConstraints. Par exemple:
proc ::tcltest::initConstraintsHook {} {
set ::tcltest::testConstraints(win95Or98) \
[expr {$::tcltest::testConstraints(95) || \
$::tcltest::testConstraints(98)}]
}
Enfin, si vous voulez ajouter du code de nettoyage complémentaire, vous pouvez définir votre propre ::tcltest::cleanupTestsHook. Par exemple:
proc ::tcltest::cleanupTestsHook {} {
# Add your cleanup code here
}
EXEMPLES
[1] Un fichier de test simple (foo.test)
if {[lsearch [namespace children] ::tcltest] == -1} {
package require tcltest
namespace import ::tcltest::*
}
test foo-1.1 {enregistrer 1 dans la variable foo} {} {
set foo 1
} {1}
::tcltest::cleanupTests
return
[2] Un fichier all.tcl simple
if {[lsearch [namespace children] ::tcltest] == -1} {
package require tcltest
namespace import ::tcltest::*
}
set ::tcltest::testSingleFile false
set ::tcltest::testsDirectory [file dir [info script]]
foreach file [::tcltest::getMatchingTestFiles] {
if {[catch {source $file} msg]} {
puts stdout $msg
}
}
::tclttest::cleanupTests 1
return
[3] Exécuter un test simple
tclsh foo.test
[4] Exécuter des tests multiples
tclsh all.tcl -file 'foo*.test' -notfile 'foo2.test'