TestBuilder

Une aide aux développeurs de plugin pour écrire plus vite leurs tests, et les encourager à en écrire plus souvent !

Un plugin pour aider les développeurs de plugin à écrire plus vite leurs tests. Et les encourager à en écrire plus souvent !

Avertissement

Ce plugin est un outil de développement. Il a tout son intérêt installé sur votre machine de développement, mais il est très vivement déconseillé de l’installer sur un serveur en ligne car il manipule les scripts PHP dans l’arborescence de votre site et permet de lancer l’exécution de code PHP arbitraire.

Installation

Le plugin s’installe classiquement. Il ne crée pas de table dans votre base de données.

Vous devez également installer les tests/ à la racine de SPIP. Si vous comptez ajouter des tests de fonctions de SPIP, vous devez installer le répertoire par SVN pour pouvoir ensuite publier vos ajouts :

cd mon_spip/
svn co svn://zone.spip.org/spip-zone/_core_/tests

Si vos tests concernent uniquement des plugins, vous pouvez utiliser l’archive https://files.spip.net/contribs/tests_spip.zip qui contient la dernière version des tests mise à jour toutes les heures. Il vous suffira de déposer le répertoire tests/ à la racine de votre site.

Un menu TestBuilder apparaît dans votre menu « configuration » (ou « administration ») en spip 2.0.x/2.1.x, « Maintenance » en spip 3.0.x et depuis spip 3.1.x dans le menu « Développement ». Il vous permet d’accéder à l’interface du plugin qui vous permet de naviguer dans les répertoires de votre site pour sélectionner le script PHP pour lequel vous souhaitez faire des tests.

Naviguez jusqu’au répertoire contenant le script pour lequel vous voulez écrire des tests :

Puis cliquez sur le nom du script

Liste des fonctions et des tests

TestBuilder vous présente alors la liste des fonctions argumentées de votre script, et la présence éventuelle d’un test existant. Les tests sont repérés par l’homonymie avec le nom de la fonction, et recherchés dans le répertoire tests/ à la racine de votre site, ou dans les plugins de SPIP.

Sinon vous pouvez créer un nouveau test pour votre fonction.

Lorsqu’un test existe il vous est possible de le modifier [1]

Ajouter des jeux d’essai à votre test

Lorsque vous demandez à créer un test pour une fonction, TestBuilder vous présente un formulaire de saisie des essais. Il comporte une vue du code de la fonction à tester, ce qui vous permet de l’avoir sous les yeux, et notamment les commentaires qui la précèdent ou qu’elle contient.

Dans notre exemple, nous allons construire un test pour la fonction tb_export qui fait juste un appel à la fonction var_export avec le second argument à true.

Le formulaire vous propose un champ de saisie par argument de la fonction ainsi que pour le résultat attendu de la fonction. Vous devez saisir dans ces champs une expression PHP valide (une chaine doit par exemple être entre guillemets).

Le bouton ’Tester’ vous permet de vérifier la pertinence de votre essai ou son bon fonctionnement : il vous présente le résultat de l’appel de la fonction avec les arguments que vous avez saisis [2].

Si vous n’avez pas indiqué de résultat attendu, celui-ci est pré-rempli lors de ce test à blanc. Sinon, il est comparé et le message vous indique un succès si ce que vous avez indiqué correspond effectivement au retour de la fonction.

Ici on vérifie que notre fonction exporte la chaine ’toto’ en expression PHP valide.

Si votre fonction possède plusieurs arguments, dont certains facultatifs, vous pouvez laisser les champs correspondant vides, ils seront ignorés lors de la construction de l’appel de la fonction.

Lorsque votre essai vous semble bon, vous pouvez l’ajouter au test avec le bouton « Ajouter ». TestBuilder va alors créer le fichier de test si nécessaire, et y écrire l’essai que vous venez d’indiquer.

Vous pouvez ajouter votre essai directement, sans spécifier de résultat et sans passer par le bouton « Tester ». Le résultat attendu sera alors retrouvé automatiquement par TestBuilder en exécutant la fonction avec les arguments que vous lui avez fourni. Pour cela, TestBuilder rejoue tout le jeu d’essai dans l’ordre, dans un contexte vierge, afin de trouver le résultat correct qui peut être influencé par les essais précédents.

Le fichier de test est rangé dans un répertoire tests/ du plugin contenant le script PHP sur lequel vous travaillez, ou dans le répertoire tests/ à la racine de SPIP si il s’agit d’un script de SPIP.

Un lien vers le script de test vous permet de l’exécuter pour vérifier son fonctionnement.

Tests combinatoires automatiques

Écrire les essais à l’unité est utile pour traiter les cas particuliers intéressants connus. Mais il peut être aussi utile d’écrire des tests sytématiques en fonction du type des arguments.
Pour cela vous pouvez indiquer pour chaque champ un pseudo-type correspondant à un jeu d’essai (string, date, array, int ... les pseudo-types disponibles sont rappelés en colonne latérale), et utiliser le bouton « Jeu de tests combinatoires ».

TestBuilder génère alors une série d’essais constitués de toutes les combinaisons possibles à partir d’une liste de valeurs intéressantes pour chaque pseudo-type.

Vous pouvez ainsi générer très vite une grande série de tests systématiques qui vous permettront de détecter des cas non prévus ou erronés, et de valider la robustesse de la fonction.

Lorsque TestBuilder génère ces tests, il élimine les tests en double qui sont caractérisés par des arguments et un résultat identiques.

Vous pouvez étendre ou personnaliser la liste des pseudo-types et des essais de base pour chacun d’entre-eux en surchargeant le fichier inc/tb_essais_type.php. Cela vous permet de gérer tous les cas particuliers. Si vos pseudo-types et/ou vos essais sont génériques, pensez à les reverser dans le plugin pour en faire profiter toute la communauté !

Modification d’un jeu d’essai

Chaque jeu d’essai existant est listé sous le formulaire de saisie. Vous pouvez supprimer un jeu d’essai qui ne vous convient pas avec le bouton « X », ou le modifier avec le bouton idoine.

L’essai en cours de modification est exposé dans la liste, et le bouton d’enregistrement « Modifier » vous indique que vous êtes en train de modifier un essai. Celui-ci sera enregistré à la même place dans la série d’essais.

Jouer les tests

Les tests de SPIP sont joués en visitant simplement le répertoire /tests/ de votre site SPIP.

Vous pouvez alors voir que votre script de test a été pris en compte et joué avec tous les autres.

En exécutant régulièrement les tests, vous avez un aperçu de la conformité globale de votre code au fur et à mesure de vos développements et vous pouvez détecter immédiatement des régressions sur les fonctions dont vous avez écris les tests au fur et à mesure.

Script de test

Le script de test généré dans notre exemple figure ci-dessous.
TestBuilder génère les scripts sur la base de templates/function.php présent dans le plugin, que vous pouvez surcharger pour vos besoins.

Il repose sur une fonction nommée essais_nomdelafonctionatester qui doit renvoyer le jeu d’essais à tester.

<?php
/**
 * Test unitaire de la fonction tb_export
 * du fichier ../plugins/testbuilder/inc/tb_lib.php
 *
 * genere automatiquement par TestBuilder
 * le 2010-02-27 13:55
 */

	$test = 'tb_export';
	$remonte = "../";
	while (!is_dir($remonte."ecrire"))
		$remonte = "../$remonte";
	require $remonte.'tests/test.inc';
	find_in_path("../plugins/testbuilder/inc/tb_lib.php",'',true);

	//
	// hop ! on y va
	//
	$err = tester_fun('tb_export', essais_tb_export());
	
	// si le tableau $err est pas vide ca va pas
	if ($err) {
		die ('<dl>' . join('', $err) . '</dl>');
	}

	echo "OK";
	

	function essais_tb_export(){
		$essais = array (
  0 => 
  array (
    0 => '\'\'',
    1 => '',
  ),
  1 => 
  array (
    0 => '\'0\'',
    1 => '0',
  ),
  2 => 
  array (
    0 => '\'Un texte avec des <a href="http://spip.net">liens</a> [Article 1->art1] [spip->http://www.spip.net] http://www.spip.net\'',
    1 => 'Un texte avec des <a href="http://spip.net">liens</a> [Article 1->art1] [spip->http://www.spip.net] http://www.spip.net',
  ),
  3 => 
  array (
    0 => '\'Un texte avec des entit&eacute;s &amp;&lt;&gt;&quot;\'',
    1 => 'Un texte avec des entit&eacute;s &amp;&lt;&gt;&quot;',
  ),
  4 => 
  array (
    0 => '\'Un texte sans entites &<>"\\\'\'',
    1 => 'Un texte sans entites &<>"\'',
  ),
  5 => 
  array (
    0 => '\'{{{Des raccourcis}}} {italique} {{gras}} <code>du code</code>\'',
    1 => '{{{Des raccourcis}}} {italique} {{gras}} <code>du code</code>',
  ),
  6 => 
  array (
    0 => '\'Un modele <modeleinexistant|lien=[->http://www.spip.net]>\'',
    1 => 'Un modele <modeleinexistant|lien=[->http://www.spip.net]>',
  ),
);
		return $essais;
	}

?>

Notes

[1Attention, cette fonctionnalité n’est opérationnelle que pour les tests qui ont été créés par TestBuilder. Si votre script a été créé manuellement antérieurement, TestBuilder ne retrouvera pas les jeux d’essai qu’il contient. Par ailleurs, il y ajoutera les jeux d’essais que vous définissez via l’interface sans casser le reste de votre fichier, mais il vous appartiendra d’ajouter à votre script les quelques lignes nécessaires au test de ces jeux d’essai.

[2Attention, avec le bouton « tester », la fonction est exécutée dans le contexte de ecrire/ alors que dans toutes les autres situations, la fonction sera testée dans le contexte public de SPIP

Discussion

3 discussions

  • 1

    Pour les plugins, cela créé dans /tests de la racine de spip, et pas dans le dossier du plugins.

    Répondre à ce message

  • 4

    oki, j’ai compris. Ce qui compte comme résultat, c’est le résultat du premier test ... peut-être à rajouter dans l’article ?

    • Oui en fait le résultat attendu est calculé automatiquement en exécutant la fonction avec les arguments proposés.
      Mais parfois (voire au début lorsqu’on écrit le test avant la fonction), on voudrait indiquer le résultat à la main. Je vais ajouter cette fonctionnalité, car c’est très simple à implémenter.

      Cela permettra d’avoir les 2 possibilités : écrire un test a posteriori sur une fonction qui marche, ecrire un test a priori sur une fonction qui ne marche pas encore en spécifiant le résultat attendu.

    • Voila, la version 0.3 permet de spécifier le résultat attendu si besoin, et c’est intégré dans la doc.

    • super, c’’est nickel.

      Une remarque supplémentaire : en allant dans /tests on n’a pas l’ensemble des globales de SPIP et des fichiers de type options/fonctions.

      résultat, j’ai dû les inclure à la main dans les jeu de test (regarde mes commits sur spip- bible pour plus de détails)

      serait-il pertinent de les inclures par défaut ?

    • hum,
      un petit pb de saisi :
      -  je dois retourner un résultat avec des retours à la ligne
      -  donc j’ai besoin d’un texarea
      -  je fais un test sans rien préciser commme résultat attendu. Le résultat calculé est mis dans un input
      -  je clique sur textarea -> mais j’ai perdu mes retours à la ligne car la value d’un input ne peut être avoir de retour

      pour le moment la seule solution que j’ai vue est de mettre mettre directement un textarea plutôt qu’un input

    Répondre à ce message

  • merci pour ce super module, qui effectivement me sera sans doute utile...

    mais il y a une chose que je ne pige pas bien !

    si j’ai bien suivis ce qui est dit là http://www.spip-blog.net/Extr3mz-pr0gr4mm1n.html, le principe des test est : tu a des arguments en entrée de fonctions, tu fais passer par la fonction, et tu vérifie que tu obtiens bien ce que tu veux en sorti. M’abuse ou non ?

    Or là tu mentionne comment définir les valeurs d’entré, mais j’ai beau relire l’article, je ne vois pas comment définir les valeurs de sortis.

    Ps : par ailleur, peut-être préciser en entete d’article la compatibilité seulement avec 2.1

    a+

    Répondre à ce message

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom