Les tests JUnit doivent-ils être javadocalisés?

Question

J'ai plusieurs scénarios de test JUnit qui ne sont actuellement pas documentés avec des commentaires Javadoc.

Le reste de mon code est documenté, mais je me demande même si cela en vaut la peine de documenter ces tests.

Answer 1

Si le but du test est évident, je ne me soucie pas de le documenter.

Si cela n’est pas évident car il s’agit d’une situation obscure - ou si je veux faire référence à un bogue spécifique, par exemple -, dans ce cas, je vais ajouter de la documentation. Cependant, je ne documente pas les exceptions, etc., mais un bref résumé de la méthode. Cela arrive relativement rarement. Je suis plus susceptible d'ajouter de la documentation pour les méthodes d'assistance utilisées dans plusieurs tests.

Answer 2

Je ne trouve aucune utilité à javadocaliser les cas de test. Je viens de rendre le nom de la méthode assez descriptif pour connaître le but du test.

En Ruby, je sais qu'il existe des outils pour créer un document à partir du nom des tests, mais je n'en ai pas vu un en Java.

Answer 3

Que ce soit en javadoc ou non, je pense que les tests unitaires doivent absolument être documentés. Dans les cas où aucune spécification formelle n'existe, les tests unitaires sont ce qui se rapproche le plus de la définition du comportement attendu du code. En documentant les cas de test, vous expliquez très clairement au lecteur ce que le test teste et pourquoi il le teste.

Answer 4

Lorsqu’on considère les tests comme une documentation, il n’a pas beaucoup de sens de "documenter la documentation". Le nom de chaque test doit déjà décrire lui-même le but de ces tests et le comportement spécifié par ce test.

Utilisez des noms descriptifs longs pour les tests et conservez le code de test aussi lisible que possible.

Par exemple, consultez les scénarios de test dans ce projet . Certains d'entre eux font-ils quelque chose qui n'est pas flagrant en regardant le nom des tests et le code du test?

Ce n'est que dans de rares cas, lorsque le code de test est obscur, que des commentaires sont nécessaires aux tests. Par exemple, si vous testez du code multi-thread et que le code de test fait des choses étranges afin de vous assurer que le code de test s'exécute dans le bon ordre. Mais même dans ces cas, un commentaire est une excuse de ne pas écrire de code de test plus pur.

Answer 5

Je ne vois pas pourquoi vous devriez traiter les cas de test différemment de votre code de production en ce qui concerne les commentaires.

Answer 6

Je pense qu'il est utile de javadoc les conditions dans lesquelles les tests se passent.

Answer 7

Est-ce une hérésie de suggérer que les commentaires de code sont un anti-modèle? Je suis d'accord avec les réponses ci-dessus, idéalement, votre code serait suffisamment descriptif pour pouvoir être utilisé sans commentaires. Cela est particulièrement vrai si vous vous trouvez dans un environnement (d'entreprise) où les utilisateurs ont tendance à mettre à jour le code sans mettre à jour les commentaires, de sorte que les commentaires deviennent trompeurs.

Answer 8

enfer oui. même si c'est juste ...

créer un ordre, modifier un ordre, enregistrer, charger & amp; vérifiez-le.

si c'est un test très simple, alors peut-être pas.

Je trouve que lorsque le code change, il arrive parfois que la raison du test ne soit plus évidente.

Answer 9

Peut-être pourriez-vous demander à une personne qui ne connaît pas tout à fait votre code de vous donner quelques informations rapides pour savoir si vos tests sont faciles à comprendre tels quels.

Dans l'entreprise pour laquelle je travaille, nous essayons de donner à nos tests des noms descriptifs et une complexité de la documentation, mais il est souvent difficile d'obtenir ce "droit". avec le premier brouillon car les éléments évidents pour le développeur ne le sont pas toujours pour les autres.

Les tests sont traités comme du code et sont soumis dans le cadre d’un processus d’évaluation par des pairs afin que notre (petite) équipe puisse déterminer si un test est facile à comprendre ou non.

Si un test est un peu déroutant, nous pouvons mettre à jour le nom ou la documentation en conséquence et nous obtenons un meilleur indicateur de ce qui fonctionne et de ce qui ne fonctionne pas.