Código de ejemplo de prueba de unidades automáticamente

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. por ej.

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

A continuación, utilizamos Sandcastle y compilamos los archivos de ayuda que necesitamos (chm y un sitio web en línea).

Es bastante embarazoso cuando el código de ejemplo no funciona, y esto es generalmente debido a que algunas funciones han cambiado o un simple error.

¿Alguien ha hecho alguna vez algo así, 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

Sí, sandcastle admite esto y es genial para mantener la corrección de los ejemplos. Se puede apuntar a una región de código como este:

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

continuación, puede utilizar un código de prueba en TestGizmo.cs como ejemplo encerrándolo en una región:

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

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

Answer 2

solución simple: hacer una pequeña aplicación en la que se incluyen todos los encabezados de código de muestra y luego llaman a sus respectivos puntos de entrada

#include "samples/sampleA.h" 

void main() 
{ 
    SomeFunction(); 
} 

continuación, después de realizar una acumulación ejecutar estas pequeñas aplicaciones que necesita para Asegúrate de que funcionaron 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 aún Solución: Registra 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, con suerte algo con todas las características que puede obtener para que pueda enviar correos electrónicos a las personas si está roto o algo así. En nuestro caso evitamos las campanas y silbatos, en su lugar, conectamos una USB Police Siren que se apaga cuando algo se rompe ¡Es bastante emocionante!

Answer 3

No he hecho esto por mi cuenta 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, utilizaron látex 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 4

Sugeriría utilizar un fragmento de marcado especial en su XML que diga: "Tome 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() 

pruebas unitarias funcionan con normalidad, y luego insertar un paso de generación entre "crear XML" y "ejecutar castillo de arena" que le sustituya cada una "ficha de archivo" con el contenido apropiado. 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 su 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 :)