Exemple de code de test unitaire automatiquement

Question

Mon équipe est responsable du développement d'une API pour un grand système que nous écrivons également. Nous devons fournir un exemple de code afin que les autres développeurs utilisant notre API puissent apprendre à l'utiliser. Nous avons documenté le code en utilisant les commentaires du document XML. par exemple.

/// <summary>Summary here</summary>
/// <example>Here is an example  <code>example code here</code> </example>
public void SomeFunction() 

Nous utilisons ensuite Sandcastle et construisons les fichiers d’aide nécessaires (chm et un site Web en ligne).

Il est assez embarrassant de voir que l'exemple de code ne fonctionne pas. Cela est généralement dû au fait que certaines fonctionnalités ont été modifiées ou à une simple erreur.

Quelqu'un a-t-il déjà fait quelque chose comme cela, mais a-t-il également configuré des tests unitaires pour qu'ils s'exécutent sur le code exemple afin qu'ils soient connus pour fonctionner pendant la construction?

Answer 1

Oui, sandcastle le soutient et il est bon de conserver l'exactitude des exemples. Vous pouvez pointer sur une région de code comme celle-ci:

   /// <summary>
   /// Gizmo which can act as client or server.
   /// </summary>
   /// <example>
   /// The following example shows how to use the gizmo as a client:
   /// <code lang="cs"
   ///    source="..\gizmo.unittests\TestGizmo.cs"
   ///    region="GizmoClientSample"/>
   /// </example>
   public class Gizmo

Vous pouvez ensuite utiliser un code de test dans TestGizmo.cs à titre d'exemple en le plaçant dans une région:

[Test]
public GizmoCanActAsClient()
{
   #region GizmoClientSample
   Gizmo gizmo = new Gizmo();
   gizmo.ActAsClient();
   #endregion
}

Avertissement: si vous déplacez ou renommez le fichier de test, vous obtiendrez une erreur à ce sujet lorsque vous tenterez de régénérer la documentation avec sandcastle.

Answer 2

Je suggérerais d'utiliser un bit de balisage spécial dans votre code XML, qui indique: "Prenez l'exemple de code à partir de cet endroit". Cela ferait référence à un fichier C # normal pouvant être exécuté avec des tests unitaires. Pour prendre votre exemple, vous pourriez avoir:

/// <summary>Summary here</summary>
/// <example>Here is an example
/// <code>!!sourcefile:SomeClassTest.cs#SomeFunction!!</code></example>
public void SomeFunction()

Vos tests unitaires s'exécutent normalement, puis insérez une étape de création entre & create; XML " et " exécuter Sandcastle " vous remplaceriez chaque jeton de fichier " avec le contenu approprié. Il se peut même que Sandcastle installe des hameçons lors de la génération de doc. Je ne connais pas suffisamment Sandcastle pour en être sûr.

C’est moche d’inventer votre propre balisage, mais ça devrait marcher.

Bien entendu, cela suppose que les exemples de code sont facilement testables par unité - certains ne le sont peut-être pas (s'ils traitent de ressources, etc.). Au moins, vous savez qu'il compile bien:)

Answer 3

Solution simple: Créez une petite application dans laquelle vous incluez tous les exemples d’en-têtes de code, puis appelez leurs points d’entrée respectifs

#include "samples/sampleA.h"

void main()
{
  SomeFunction();
}

ensuite, après avoir créé une version exécutant ces petites applications, vous devez être sûr qu'elles ont fonctionné correctement. Mais pouvez-vous vérifier que le code fonctionne correctement sans que quelqu'un ait une soirée pyjama avec le serveur NightlyBuild?

Meilleure solution: enregistrez le résultat et demandez à quelqu'un de le consulter le matin.

Une solution encore meilleure: enregistrez le résultat et collez-le au grep ou quelque chose de sorte que personne ne soit obligé de l'examiner à moins qu'il ne soit cassé.

Meilleure solution: Trouvez un cadre de test approprié. Si tout va bien, vous pouvez obtenir quelque chose avec tout ce que vous pouvez obtenir pour pouvoir envoyer un courrier électronique aux personnes si son problème est cassé ou quelque chose comme ça. Dans notre cas, nous évitons les cloches et les sifflets, mais nous avons connecté une sirène de police USB qui se déclenche lorsque quelque chose se brise. C’est assez excitant!

Answer 4

Je ne l’ai pas fait moi-même, mais j’ai vu cela mentionné dans les livres de Pragmatic Programmers. Si je ne me trompe pas, le livre "Tests unitaires pragmatiques en C # avec Nunit" mentionne qu'ils l'ont fait pour le livre. Il se peut qu’ils aient toutefois mentionné dans l’un de leurs podcasts.

Ils ont mentionné qu’ils disposaient d’un serveur de construction continu pour leurs livres. Si je ne me trompe pas, ils ont utilisé du latex ou un autre balisage textuel pour écrire leurs livres et ils avaient défini des étapes pour formater le balisage et le code de construction et de tests unitaires du livre.