Automatisch Unit Test Beispiel Code

Question

Mein Team ist verantwortlich für die Entwicklung einer API für ein großes System, das wir auch schreiben. Wir müssen Beispielcode bereitstellen, damit andere Entwickler, die unsere API verwenden, lernen können, wie sie verwendet werden. Wir haben den Code mit den XML-Dokumentenkommentaren dokumentiert. z.

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

Wir verwenden dann Sandcastle und bauen die Hilfedateien, die wir brauchen (chm und eine Online-Website).

Es ist ziemlich peinlich, wenn der Beispielcode nicht funktioniert, und dies ist in der Regel, weil einige Funktionalität geändert hat oder ein einfacher Fehler.

Hat jemand schon mal so etwas gemacht, aber auch Komponententests für den Beispielcode konfiguriert, damit diese während des Builds funktionieren?

Answer 1

Ja, Sandcastle unterstützt dies und es ist großartig, die Korrektheit der Beispiele zu wahren. Sie können so zu einer Coderegion zeigen:

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

Caveat:

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

Sie dann einigen Test-Code in TestGizmo.cs als Beispiel in einer Region, die es durch Einschließen verwenden können, wenn Sie sich bewegen oder benennen Sie die Testdatei um, Sie erhalten nur einen Fehler, wenn Sie versuchen, die Dokumentation mit Sandcastle neu zu erstellen.

Answer 2

Einfache Lösung: Machen Sie eine kleine Anwendung, in der Sie alle Beispielcode-Header enthalten und rufen Sie dann den jeweiligen Einspeisepunkten

#include "samples/sampleA.h" 

void main() 
{ 
    SomeFunction(); 
} 

dann, nachdem Sie ein Build ausführen, um diese kleinen Anwendungen, die Sie brauchen, um sicher sein, dass sie in Ordnung waren. Aber können Sie überprüfen, ob der Code in Ordnung war, ohne dass jemand eine Pyjamaparty mit dem NightlyBuild-Server hat?

Bessere Lösung: Melden Sie die Ausgabe an und lassen Sie sich jemanden morgens ansehen.

Noch bessere Lösung: Protokollieren Sie die Ausgabe und grep es oder etwas so niemand muss es betrachten, es sei denn es ist kaputt.

Beste Lösung: Finden Sie eine geeignete Test-Framework, hoffentlich etwas mit all den Schnickschnack, die Sie bekommen können, so kann es Leute per E-Mail, wenn es kaputt oder so ähnlich. In unserem Fall vermeiden wir die Schnickschnack statt einer USB Police Sirene, die ausgeht, wenn etwas bricht Es ist ziemlich aufregend!

Answer 3

Ich habe das selbst nicht gemacht, aber ich habe das in den Pragmatischen Programmierbüchern erwähnt gesehen. Wenn ich mich nicht irre, erwähnt das Buch "Pragmatische Unit Testing in C# mit Nunit", dass sie das für das Buch getan haben. Es könnte sein, dass sie in einem ihrer Podcasts erwähnt haben.

Sie erwähnten, sie hätten einen Continuous Build Server für ihre Bücher eingerichtet. Wenn ich mich nicht irre, benutzten sie Latex oder ein anderes textbasiertes Markup, um ihre Bücher zu schreiben, und sie hatten Schritte zum Formatieren des Markup- und Build- und Unit-Test-Codes im Buch.

Answer 4

Ich würde vorschlagen, ein spezielles bisschen Markup in Ihrem XML zu verwenden, das sagt, "Ergreifen Sie das Codebeispiel von diesem Platz". Es würde sich auf eine normale C# -Datei beziehen, die mit Komponententests ausgeführt werden kann. Um Ihr Beispiel zu nehmen, könnten Sie haben:

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

Ihre Unit-Tests als normal laufen, und dann einen Build-Schritt einfügen zwischen „erstellen XML“ und „Run Sandcastle“ Sie würden ersetzen Sie jede „Datei-Token“ mit dem geeignete Inhalte. Möglicherweise gibt es sogar Hooks, die du zur Zeit der Doc-Generierung in Sandcastle einbauen kannst - ich weiß nicht genug über Sandcastle, um das sicher zu wissen.

Es ist hässlich, natürlich ein eigenes Markup zu erfinden, aber es sollte funktionieren.

Natürlich setzt dies voraus, dass die Codebeispiele leicht Unit-Testable sein können - einige nicht (wenn sie mit Ressourcen usw. umgehen). Zumindest würdest du es aber kompilieren :)