.net - unitarias - Código de ejemplo de prueba unitaria automáticamente

pruebas unitarias interfaz

Question

Mi equipo es responsable del desarrollo de una API para un sistema grande que también escribimos. Necesitamos proporcionar un código de ejemplo para que otros desarrolladores que usen nuestra API puedan aprender a usarlo. Hemos estado documentando el código usando los comentarios del documento xml. p.ej.

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

Luego usamos Sandcastle y creamos los archivos de ayuda que necesitamos (chm y un sitio web en línea).

Es bastante vergonzoso cuando el código de ejemplo no funciona, y esto es generalmente porque alguna funcionalidad ha cambiado o un simple error.

¿Alguna vez alguien ha hecho algo como esto, pero también ha configurado pruebas unitarias para ejecutar en el código de ejemplo para que se sepa que funcionan durante la compilación?

Answer 1

No he hecho esto por mí mismo, pero he visto esto mencionado en los libros de Pragmatic Programmers. Si no me equivoco, el libro "Pragmatic Unit Testing in C # with Nunit" menciona que hicieron esto para el libro. Sin embargo, es posible que hayan mencionado en uno de sus podcasts.

Mencionaron que tenían un servidor de compilación continuo configurado para sus libros. Si no me equivoco, usaron latex u otro texto basado en el marcado para escribir sus libros y tuvieron pasos de compilación para formatear el marcado y el código de construcción y prueba unitaria en el libro.

Answer 2

Sugeriría usar un fragmento especial de marcado en su XML que diga: "Toma la muestra del código de este lugar". Se referiría a un archivo C # normal que se puede ejecutar con pruebas unitarias. Para tomar su ejemplo, es posible que tenga:

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

Las pruebas de su unidad se ejecutan normalmente, y luego inserte un paso de compilación entre "crear XML" y "ejecutar Sandcastle". Reemplazaría cada "token de archivo" con los contenidos apropiados. Incluso puede haber ganchos que puedas poner en Sandcastle para hacer esto en el momento de la generación del doc. No sé lo suficiente sobre Sandcastle para estar seguro.

Es feo inventar tu propia marca, por supuesto, pero debería funcionar.

Por supuesto, esto supone que los ejemplos de código son fácilmente comprobables por unidad, algunos pueden no serlo (si se trata de recursos, etc.). Al menos sabría que compila sin embargo :)

Answer 3

Solución simple: cree una pequeña aplicación en la que incluya todos los encabezados de código de muestra y luego llame a sus respectivos puntos de entrada

#include "samples/sampleA.h"
void main()
{
SomeFunction();
}

luego, después de hacer una compilación, ejecuta estas pequeñas aplicaciones que necesitas para asegurarte de que funcionen bien. ¿Pero puede verificar que el código se ejecutó correctamente sin que alguien tenga una fiesta de pijamas con el servidor NightlyBuild?

Mejor solución: registre la salida y haga que alguien la mire por la mañana.

Mejor solución: Registre la salida y grep o algo para que nadie tenga que mirarla a menos que esté rota.

La mejor solución: encuentre un marco de prueba adecuado, ojalá algo con todos los recursos que pueda obtener para que pueda enviar correos electrónicos a personas si está roto o algo así. En nuestro caso evitamos las campanas y silbatos, en su lugar conectamos una Sirena de Policía USB que se activa cuando algo se rompe ¡Es bastante emocionante!

Answer 4

Sí, Sandcastle apoya esto y es genial mantener la exactitud de los ejemplos. Puede señalar una región de código como esta:

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

A continuación, puede usar un código de prueba en TestGizmo.cs como ejemplo adjuntándolo a una región:

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

Advertencia: si mueve o cambia el nombre del archivo de prueba, solo obtendrá un error cuando intente regenerar la documentación con sandcastle.