web-dev-qa-db-fra.com

Javadoc dans les classes de test Junit?

Est-ce une bonne pratique de mettre des commentaires Javadoc dans des classes et des méthodes de test junit? Ou est-ce que l’idée qu’ils devraient être si faciles à lire et à comprendre qu’il est inutile de fournir un récit de l’intention du test?

junitjavadoc
31
HDave

Personnellement, j'utilise les commentaires javadoc avec parcimonie, car je constate qu'ils augmentent l'encombrement à l'écran. Si je peux nommer une classe, une fonction ou une variable de manière plus auto-descriptive, je préférerais un commentaire. Un excellent livre à lire sur ce sujet est Clean Code de Robert C. Martin (a.k.a Oncle Bob).

Ma préférence personnelle est de rendre la classe et les méthodes auto-descriptives, c.-à-d.

class ANewEventManager {
   @Test
   public void shouldAllowClassesToSubscribeToEvents() {
        /* Test logic here */
   }
}

L'un des avantages de cette approche est qu'il est facile de voir dans la sortie Junit ce qui échoue avant de parcourir le code.

21
Martin

J'utilise beaucoup Javadoc dans mes tests… .. Mais cela ne devient vraiment utile que lorsque vous ajoutez votre propre tag à votre javadoc.

L'objectif principal ici est de rendre le test compréhensible pour les autres développeurs contribuant à votre projet}. Et pour cela, nous n'avons même pas besoin de générer le javadoc réel.

/**
 * Create a valid account.
 * @result Account will be persisted without any errors,
 *         and Account.getId() will no longer be <code>null</code>
 */
@Test
public void createValidAccount() {
    accountService.create(account);
    assertNotNull(account.getId());
}

Ensuite, nous devrons informer notre plugin Javadoc dans maven que nous avons ajouté une nouvelle balise.

<build>
    <plugins>
        <plugin>
            <groupId>org.Apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.8</version>
            <configuration>
                <tags>
                    <tag>
                        <name>result</name>
                        <placement>a</placement>
                        <head>Test assertion :</head>
                    </tag>
                </tags>
            </configuration>             
        </plugin>    
    </plugins>        
</build>

Et maintenant, il ne reste plus qu’à appeler notre plug-in Maven.

javadoc:test-javadoc (or javadoc:test-aggregate for multi-module projects)

Ceci est un exemple assez simple, mais lors de tests plus complexes, il est impossible de décrire les tests en utilisant simplement un nom de méthode auto-descriptif.

36
Foumpie

J'aime aussi les commentaires sous UT, cela aide à comprendre le cas d'utilisation en quelques secondes.

J'ai créé une petite bibliothèque pour inclure des descriptions dans la pile de traces de tout type de rapport. Quiconque vérifie les rapports peut facilement se retrouver dans le problème.

Le nom de la bibliothèque est Frutilla, n'hésitez pas à l'utiliser https://github.com/ignaciotcrespo/frutilla

0
Ignacio Tomas Crespo