Codice di esempio di test unità automatico

Question

Il mio team è responsabile dello sviluppo di un'API per un sistema di grandi dimensioni che anche noi scriviamo. Dobbiamo fornire un codice di esempio in modo che altri sviluppatori che utilizzano la nostra API possano imparare ad usarlo. Abbiamo documentato il codice utilizzando i commenti del documento xml. ad es.

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

Usiamo quindi Sandcastle e costruiamo i file di aiuto di cui abbiamo bisogno (chm e un sito Web online).

È abbastanza imbarazzante quando il codice di esempio non funziona, e questo di solito perché alcune funzionalità sono cambiate o un semplice errore.

Qualcuno ha mai fatto qualcosa del genere, ma ha anche configurato unit test per l'esecuzione sul codice di esempio in modo che siano noti per funzionare durante la compilazione?

Answer 1

Sì, sandcastle supporta questo ed è bello mantenere la correttezza degli esempi. Puoi indicare una regione di codice come questa:

   /// <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

È quindi possibile utilizzare un codice di test in TestGizmo.cs come esempio racchiudendolo in una regione:

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

Avvertenza: se si sposta o rinomina il file di prova, si otterrà un errore al riguardo solo quando si tenta di rigenerare la documentazione con sandcastle.

Answer 2

Suggerirei di usare un bit speciale di markup nel tuo XML che dice "Prendi l'esempio di codice da questo posto". Farebbe riferimento a un normale file C # che può essere eseguito con unit test. Per fare un esempio, potresti avere:

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

I test unitari vengono eseguiti normalmente, quindi inserisci un passaggio di creazione tra " create XML " e "eseguire Sandcastle" sostituirai ogni token di file " " con i contenuti appropriati. Potrebbero esserci anche dei ganci che potresti mettere in Sandcastle per farlo al momento della generazione di documenti - non so abbastanza su Sandcastle da sapere con certezza.

Ovviamente è brutto inventare il proprio markup, ma dovrebbe funzionare.

Naturalmente, questo presuppone che gli esempi di codice siano facilmente testabili in unità - alcuni potrebbero non esserlo (se hanno a che fare con risorse ecc.). Almeno sapresti che si compila comunque :)

Answer 3

Soluzione semplice: Crea una piccola applicazione in cui includi tutte le intestazioni di codice di esempio e quindi chiama i rispettivi punti di ingresso

#include "samples/sampleA.h"

void main()
{
  SomeFunction();
}

quindi dopo aver eseguito una build esegui queste piccole app devi assicurarti che funzionino bene. Ma puoi verificare che il codice funzioni correttamente senza che qualcuno abbia un pigiama party con il server NightlyBuild?

Soluzione migliore: registra l'output e chiedi a qualcuno di guardarlo al mattino.

Soluzione ancora migliore: registra l'output e grep o qualcosa del genere in modo che nessuno debba guardarlo a meno che non sia rotto.

Migliore soluzione: trova un framework di test adatto, si spera qualcosa con tutte le campane e fischietti che puoi ottenere in modo che possa inviare email alle persone se è rotto o qualcosa del genere. Nel nostro caso evitiamo le campane e i fischi, invece abbiamo collegato una Sirena della polizia USB che si spegne quando qualcosa si rompe È abbastanza eccitante!

Answer 4

Non l'ho fatto da solo, ma l'ho visto menzionato nei libri di Pragmatic Programmers. Se non sbaglio il libro "Pragmatic Unit Testing in C # con Nunit" afferma che lo hanno fatto per il libro. È possibile che abbiano citato in uno dei loro podcast.

Hanno detto che avevano un server di build continuo impostato per i loro libri. Se non sbaglio hanno usato il lattice o qualche altro markup basato sul testo per scrivere i loro libri e avevano costruito passaggi per la formattazione del markup e la costruzione e il codice di unit test nel libro.