On a vu dans une leçon sur les bases de Java que ce langage est utilisé pour d’énormes projets logiciels et que le code peut être divisé en plusieurs types d’unités autonomes du plus grand (les logiciels et les frameworks) aux unités intermédiaires (les modules et les packages) et finalement aux unités atomiques (les classes).

Parce que tous nos programmes jusqu’à présent tenaient dans une seule classe, le compilateur Java nous permettait d’omettre une déclaration de classe et de simplement écrire des déclarations pour nos méthodes et nos variables globales.¹ De plus, on n’avait pas à se préoccuper des mots-clés qui sont utilisés pour gérer la visibilité des éléments de notre classe (public, private) ni de comment les méthodes sont appelées (static ou non). On ne travaillera pas avec ces concepts dans ce cours (ils sont couverts dans le cours de 12e année), mais on doit quand même ajouter une chose à notre code pour le tester avec JUnit : une déclaration de classe.

La déclaration de classe donne un nom à notre code et permet au code dans la classe test d’y référer pour utiliser nos méthodes.

Ainsi, si on a un fichier Calculator.java avec le contenu suivant :

int add(int a, int b) {
    return a + b;
}

void main() {
    System.out.println(add(1, 2));
}

et on veut tester la méthode add, on doit ajouter une déclaration de classe autour de notre code pour le tester avec JUnit :

class Calculator {
    int add(int a, int b) {
        return a + b;
    }

    void main() {
        System.out.println(add(1, 2));
    }
}

1. Utiliser l’outil “Mettre le document en forme” dans VS Code pour rétablir une bonne indentation après avoir ajouté la déclaration de classe (n’oubliez pas son accolade fermante à la fin du code).
2. Le nom de la classe doit être le même que le nom du fichier et on devrait respecter les conventions Java pour les noms de classe/fichier : commencer par une majuscule et utiliser la casse chameau pour les noms composés.

   Pour renommer le fichier, au besoin, utiliser l’outil “Renommer le fichier” dans VS Code parce qu’il renommera automatiquement le nom de la classe et toutes les références à cette classe à travers le projet.

Maintenant, le code dans la classe de test pourra créer un objet de type Calculator pour tester la méthode add(), comme on ajoute des objets de type Scanner pour utiliser ses méthodes next*().

On va utiliser pour la première fois l’option “Source Actions” dans VS Code pour créer des tests unitaires. Cette section vous montre comment le faire étape par étape.

ÉTAPE 1 : Créez votre fichier dans un projet Java et écrire au moins une de ses méthodes. Pour cet exemple, on peut utiliser le fichier Calculator.java avec le contenu suivant :

class Calculator {
    int add(int a, int b) {
        return a + b;
    }

    void main() {
        System.out.println(add(1, 2));
    }
}

ÉTAPE 2

Ouvrir le fichier dans VS Code et attendre une minute afin de laisser les outils Java s’activer.

ÉTAPE 3

Faites un clic droit n’importe où dans le fichier et choisissez “Source Action…”. Vous devriez voir une option pour Generate Tests. Cliquez dessus.

|

ÉTAPE 4

Si c’est la première fois qu’on fait ces étapes dans un projet, VS Code vous donnera une erreur et un bouton Enable tests. Cliquez dessus et choisir le framework JUnit. VS Code installera automatiquement les dépendances nécessaires pour JUnit dans votre projet, dans le sous-dossier lib.

| |

Note : vous aurez à faire cette étape une seule fois par projet, mais vous aurez à la refaire si vous créez un nouveau projet.

ÉTAPE 5

Tapez Enter pour acceptez le nom proposé pour la classe de test, généralement [nom de ma classe]Test. Dans notre exemple, ce serait CalculatorTest.

ÉTAPE 6

Sélectionnez la méthode que vous voulez tester. Dans notre exemple, on veut tester add. Cliquez sur Enter pour accepter. La classe sera créée avec la signature de la méthode de test pour add. Cochez seulement la plus récente méthode, celle qui n’a pas encore de test unitaire.

|

Notez qu’on ne doit pas tester main parce qu’il contient la logique globale du programme. main n’est pas une “unité” mais plutôt “l’intégration” ultime de toutes les unités de notre programme. Ça ne fait pas de sens de préparer des tests unitaires pour cette méthode.

ÉTAPE 7

Écrivez les tests unitaires pour les méthodes choisies. C’est à cet étape qu’on doit considérer les cas de test et les implémenter.

Les sections suivantes donnent des gabarits de tests unitaires que vous pouvez utiliser pour écrire vos tests.

ÉTAPE 8

Exécutez les tests unitaires en cliquant sur le bouton Run Test à côté de la méthode de test ou en cliquant sur le bouton Run All Tests en haut de la classe de test.

Notez que s’il y a une seule classe dans votre projet qui contient des erreurs de syntaxe, vous recevrez un message d’erreur avant le lancement des tests parce que les outils Java compilent tout votre projet. Si l’erreur n’est pas dans la classe à tester ni dans la classe avec les tests, vous pouvez simplement cliquer sur le bouton Continue pour ignorer ces erreurs et lancer les tests.

ÉTAPE 9

Analysez les résultats des tests dans la fenêtre de sortie de JUnit. Si les tests sont tous réussis, rien ne s’affichera et vous devrez vous rendre à l’onglet “Test Results” pour voir la sortie. Si un test échoue, vous verrez un message d’erreur dans la fenêtre de sortie.

Notez que la sortie texte dans la partie gauche ne dit pas grand-chose d’utile. C’est plutôt la partie droite qui donne l’état de chacun des tests. Le crochet vert est pour un test réussi, le point rouge est pour un test échoué. Vous pouvez cliquer sur le résultat de chaque test pour plus de détails ou pour les lancer de nouveau.

ÉTAPE 10 : Corrigez les erreurs dans votre code et réexécutez les tests jusqu’à ce qu’ils passent tous. Les erreurs peuvent se trouver dans le test unitaire ou dans la méthode que vous testez… mais pas ailleurs! C’est l’avantage de faire des tests unitaires pour chaque méthode qu’on finit d’écrire.

ÉTAPE 11 : Répétez les étapes 3 à 10 pour chaque nouvelle méthode que vous écrivez dans la classe principale du projet.

Considérant notre méthode add dans la classe Calculator :

class Calculator {
    // ... reste du code de la classe

    int add(int a, int b) {
        return a + b;
    }
}

La classe de test produit par les outils de JUnit dans VS Code serait le suivant, avec quelques lignes additionnelles :

import static org.junit.Assert.*; // ajoutez cette ligne pour les méthodes de comparaison

import org.junit.Test;

public class CalculatorTest {

    Calculator calc = new Calculator(); // ajoutez cette ligne pour faire référence à votre code

    @Test
    public void testAdd() {

    }
}

On peut écrire le test unitaire testAdd dans la classe CalculatorTestcomme suit à l’intérieur de la classe de test :

    @Test
    public void testAdd() {
        /*
         * Cas de tests pour int add(int, int)
         *
         * Descr.   Entrées  Sortie attendue
         * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         * base     1, 2    3
         */

        assertEquals(3, calc.add(1,2));
    }

Deux points qui peuvent faire planter ce code :

• La méthode assertEquals() ne sera pas reconnue si vous n’avez pas ajouté l’imporation static d’Assert au début du fichier de test. Voir le gabarit pour la classe de test ci-dessus.
• La méthode add() ne sera pas reconnue si vous n’avez pas créé une variable calc de type Calculator dans la classe de test. Voir le gabarit pour la classe de test ci-dessus.

Notez que assertEquals est une méthode de JUnit qui compare le premier argument avec le deuxième argument et lève une exception si les deux arguments ne sont pas égaux. C’est la méthode la plus courante pour tester des valeurs de retour.

Il y a plusieurs autres détails à noter dans ce code :

1. L’annotation @Test et la signature de la méthode ont peut-être été créées automatiquement si vous avez suivi les étapes ci-dessus. L’annotation @Test devient un point de lancement du code de test pour JUnit.
2. On écrit les cas de test dans un commentaire de bloc au début de la méthode de test. Dans l’exemple, on a simplement inclut un cas de test, mais vous devrez considérer l’ensemble des cas à tester dans la méthode.
3. On utilise la méthode assertEquals pour implémenter le cas de test, soit comparer le résultat attendu avec la valeur de retour de la méthode testée. Il devrait y avoir un appel à assertEquals pour chaque cas de test.

L’exemple de base fonctionne pour tous les types sauf les valeurs à virgule flottante (comme les double).

Avec les double, dû à la conversion inexacte entre le binaire (dans la machine) et le décimal (dans la représentation du nombre), il y a toujours - ou presque - des erreurs d’arrondissement. Ainsi on ne peut jamais évaluer l’égalité entre deux double directement comme on le fait avec les autres types de données.

L’algorithme à utiliser se résume à :

• valeur 1 = valeur 2 ± une marge d'erreur acceptable ou
• valeur absolue de (valeur 1 - valeur 2) <= une marge d'erreur acceptable (la valeur absolue ignore le signe du résultat)

Par exemple, pour des notes de cours à une décimale près on pourrait note1 = note2 ± 0.1 ou note1 = note2 ± 0.05, selon votre préférence.

Pour les double, JUnit fournit une méthode assertEquals qui prend un troisième argument, la marge d’erreur acceptable. Par exemple, pour une méthode average qui retourne la moyenne de deux nombres à une décimale près, on pourrait écrire le test unitaire comme suit :

    @Test
    public void testAverage() {
        /*
         * Cas de tests pour double average(double, double) :
         *
         * Descr.   Entrées     Sortie attendue
         * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         * base     80.0, 90.0  85.0
         */

        assertEquals(85.0, calc.average(80.0, 90.0), 0.1);
    }

Notez que nous fournissons la valeur attendue et la valeur de retour de la méthode testée comme avec l’exemple. Cependant, on ajoute aussi un troisième argument, la marge d’erreur acceptable. Dans cet exemple, on accepte une différence de 0.1 entre la valeur attendue et la valeur de retour.

Le choix de la marge acceptable dépend de la précision requise par votre programme. Comme règle de base, on devrait choisir une marge d’erreur qui est plus petite que la précision finale que nous voulons parce que les erreurs d’arrondissment s’accumulent à chaque opération.

Donc la marge de 0.1 si on veut des résultats à une place décimale est trop généreuse et on perd beaucoup de précision. Règle de base : utiliser une marge d’erreur au moins 3 chiffres de plus que la précision finale désirée. P. ex., si on veut une précision finale de 0.1 on devrait choisir une marge d’erreur d’au maximum 0.0001. le test ci-dessus serait modifié à :

assertEquals(85.0, calc.average(80.0, 90.0), 0.0001);

Si on a la méthode getNameUsingGlobalScanner dans la classe Calculator :

import java.util.Scanner;

class Calculator {

    /** Scanner global pour toutes les méthodes de la classe */
    Scanner console = new Scanner(System.in);

    // ... reste du code de la classe

    String getNameUsingGlobalScanner() {
        System.out.print("Entrez votre prénom > ");
        String name = console.next(); // utilise le Scanner global
        console.nextLine(); // jeter tout après le premier mot
        return name;
    }
}

On peut écrire le test unitaire testGetNameUsingGlobalScanner dans la classe CalculatorTest comme suit :

    @Test
    public void testGetNameUsingGlobalScanner() {
        /*
         * Cas de test pour String getName() qui utilise un
         * Scanner déclaré globalement
         * 
         * Descr.           Entrée          Sortie attendue
         * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         * normal           "david"         "david"
         * un caractère     "A"             "A"
         * plusieurs mots   "David Crowley" "David"
         */

        /* PRÉPARATION */

        // garder une référence au Scanner original de calc
        Scanner original = calc.console;

        // définir les cas de test
        String testInput = "david\n" +
                "A\n" +
                "David Crowley\n"; // les \n sont les `Entrée` de l'utilisateur

        // créer une source d'entrées qui contient nos cas de tests
        InputStream testStream = new ByteArrayInputStream(testInput.getBytes());

        // passer la nouvelle source d'entrées au Scanner de calc
        calc.console = new Scanner(testStream); 

        /* TESTS */
        
        assertEquals("david", calc.getNameUsingGlobalScanner());
        assertEquals("A", calc.getNameUsingGlobalScanner());
        assertEquals("David", calc.getNameUsingGlobalScanner());

        /* NETTOYAGE */

        // rediriger le Scanner global de calc à lire sa source originale
        calc.console = original;
    }

Note : avec l’ajout des InputStream et du Scanner, on doit ajouter import java.io.*; et import java.util.*; au début du fichier de test, p. ex. :

import static org.junit.Assert.*;

import java.io.*;   // ici
import java.util.*; // et ici

import org.junit.Test;

public class CalculatorTest {
    // ... reste du code de la classe

}

Si on oublie, parfois les outils d’autocomplétion dans VS Code peuvent ajouter ces déclarations automatiquement, mais c’est quelque chose à vérifier si vous avez des messages d’erreurs sur ces variables.

Une autre façon d’utiliser un Scanner dans un programme est de le déclarer localement, par exemple avec la méthode getName dans la classe Calculator :

import java.util.Scanner;

class Calculator {
    String getName(Scanner in) {
        System.out.print("Entrez votre prénom > ");
        String name = in.next(); // fait référence au Scanner passé en paramètre
        in.nextLine(); // jeter tout après le premier mot
        return name;
    }

    void main() {
        Scanner console = new Scanner(System.in); // déclarer un Scanner local
        //... autre code
        String name = getName(console); // passer le Scanner local comme argument
        //... autre code
    }
}

Le test unitaire testGetName dans CalculatorTest serait alors :

    @Test
    public void testGetName() {
        /*
         * Cas de test pour String getName(Scanner)
         * 
         * Descr.           Entrée          Sortie attendue
         * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         * normal           "david"         "david"
         * un caractère     "A"             "A"
         * plusieurs mots   "David Crowley" "David"
         */

        /* PRÉPARATION */

        // définir les cas de test
        String testInput = "david\n" +
                "A\n" +
                "David Crowley\n"; // les \n sont les `Entrée` de l'utilisateur

        // créer un Scanner qui lit nos entrées de test au lieu de l'entrée standard
        InputStream testStream = new ByteArrayInputStream(testInput.getBytes());
        Scanner testScanner = new Scanner(testStream);

        /* TESTS */

        assertEquals("david", calc.getName(testScanner));
        assertEquals("A", calc.getName(testScanner));
        assertEquals("David", calc.getName(testScanner));

        /* NETTOYAGE */

        // Le nouveau Scanner est détruit automatiquement à la fin de cette méthode
    }

Note : avec l’ajout des InputStream et du Scanner, on doit ajouter import java.io.*; et import java.util.*; au début du fichier de test, p. ex. :

import static org.junit.Assert.*;

import java.io.*;   // ici
import java.util.*; // et ici

import org.junit.Test;

public class CalculatorTest {
    // ... reste du code de la classe

}

Si on oublie, parfois les outils d’autocomplétion dans VS Code peuvent ajouter ces déclarations automatiquement, mais c’est quelque chose à vérifier si vous avez des messages d’erreurs sur ces variables.

Considérant la méthode sayName dans la classe Calculator :

    void sayName(String name) {
        System.out.println("Bonjour " + name);
    }

On peut écrire le test unitaire testSayName dans la classe CalculatorTest comme suit :

    @Test
    public void testSayName() {
        /*
         * Cas de test pour void sayName(String)
         * 
         * Descr.           Entrée          Sortie attendue
         * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         * normal           "David"         "Bonjour David"
         * un caractère     "A"             "Bonjour A"
         * plusieurs mots   "David Crowley" "Bonjour David Crowley"
         * 
         */

        /* PRÉPARATION */

        // garder une référence à la sortie standard originale
        PrintStream original = System.out;

        // rediriger la sortie standard vers un flux de sortie temporaire
        OutputStream outContent = new ByteArrayOutputStream();
        System.setOut(new PrintStream(outContent));
    
        /* TESTS */

        calc.sayName("David");
        calc.sayName("A");
        calc.sayName("David Crowley");

        String expectedOutput = "Bonjour David\nBonjour A\nBonjour David Crowley\n";

        assertEquals(expectedOutput, outContent.toString().replace("\r\n", "\n")); // le replace() est nécessaire sur Windows (encodage de fin de ligne différent)

        /* NETTOYAGE */

        // rétablir la sortie standard originale
        System.setOut(original);
    }

Note : on applique la méthode de traitement de texte .replace("\r\n", "\n") sur la sortie pour s’assurer que les différents types de retour de ligne ne causent pas un échec de la comparaison. Windows utilise \r\n pour le retour de ligne, alors que Linux, MacOS et nos propres instructions Java utilisent seulement \n.

Note : avec l’ajout du PrintStream et des OutputStream, on doit ajouter import java.io.*; au début du fichier de test, p. ex. :

import static org.junit.Assert.*;

import java.io.*;   // ici

import org.junit.Test;

public class CalculatorTest {
    // ... reste du code de la classe

}

Si on oublie, parfois les outils d’autocomplétion dans VS Code peuvent ajouter ces déclarations automatiquement, mais c’est quelque chose à vérifier si vous avez des messages d’erreurs sur ces variables.