BUnit.h

Ir a la documentación de este archivo.

// BUnit.h (C) 2008  adolfo@di-mare.com

/*
   THIS IS FREE SOFWTWARE.
   - Use at your own risk; acknowledge authorship, please.
   - You can never blame the author for your use of this software.
   - Released to the world under LGPLv3:
     http://www.gnu.org/licenses/lgpl-3.0.html
   ESTE PROGRAMA ES LIBRE.
   - Uselo baja su propia responsabilidad; reconozca la autoría, por favor.
   - Usted nunca podrá culpar al autor por su propio uso de este software.
   - Entregado al mundo bajo LGPLv3:
     http://www.gnu.org/licenses/lgpl-3.0.html
*/
/*
    Version 0: No TestSuite<>
    Version 1: English Doxygen
    Version 2: English+Spanish Doxygen
*/

#ifdef English_dox
/** \file  BUnit.h
    \brief [B]asic module for [unit] program testing.

    \author Adolfo Di Mare <adolfo@di-mare.com>
    \date   2008
*/
#endif
#ifdef Spanish_dox
/** \file  BUnit.h
    \brief Módulo [B]ásico para prueba [unit]aria de programas.

    \author Adolfo Di Mare <adolfo@di-mare.com>
    \date   2008
*/
#endif

#ifdef English_dox
    /// Doxygen English documentation.
    #define English_dox   "Doxygen English documentation"
   /// \def English_dox  ///< Marks English documentation blocks.
   /// \def BUnit_h      ///< Avoids multiple inclusion.
#endif
#ifdef Spanish_dox
    /// Documentación en español.
    #define Spanish_dox "Documentación en español"
   /// \def Spanish_dox  ///< Macro usado para que Doxygen genere documentación
   /// \def BUnit_h      ///< Evita la inclusión múltiple.
#endif

#ifndef BUnit_h
#define BUnit_h      // avoid multiple inclusion

#include <list>      // std::list
#include <string>    // class std::string
#include <sstream>   // class basic_ostringstream<T,Ch>
#include <cstdio>    // memcpy()+strlen()
#include <typeinfo>  // class std::type_info ==> char* typeid().name();
#include <algorithm> // find()

namespace std {} // using namespace std;

/// Escuela de Ciencias de la Computación e Informática.
/// \see http:www.ecci.ucr.ac.cr
namespace ECCI { }

// Private class to hold test cases that didn´t succeed.
class TestCaseFailure {
private:
    const char * m_fname;  // file where the failure ocurred
    int          m_lineno; // line for the failure
    const char * m_label;  // descriptive message for the failure
    bool m_destroy_label;  // true when "m_label" requires destruction
private:
    TestCaseFailure() : // almost never used
        m_fname(""), m_lineno(0), m_label(""), m_destroy_label(false)
    { } // always sets "m_destroy_label" to "false"
    TestCaseFailure(const char * fname, int line, const char * label, bool destroy )
        : m_fname(fname), m_lineno(line), m_label(label), m_destroy_label(destroy)
    { }
public:
    ~TestCaseFailure() { if (m_destroy_label) { delete [] m_label; } }
    TestCaseFailure( const TestCaseFailure& o ) {
        m_fname = o.m_fname; m_lineno = o.m_lineno; m_label = o.m_label;
        m_destroy_label = o.m_destroy_label;
        // avoid double destruction of "m_label"
        const_cast<TestCaseFailure*>(&o)->m_destroy_label = false;
    //  const_cast<bool>(o.m_destroy_label) = false; // won't compile
    }
    void operator = ( TestCaseFailure& o ) {
        m_fname = o.m_fname; m_lineno = o.m_lineno; m_label = o.m_label;
        m_destroy_label = o.m_destroy_label;
        o.m_destroy_label = false; // evita doble destrucción de "m_label"
    }
    template <class TestCase> friend void do_toXML(
        const TestCase * tc , std::basic_ostringstream<char> & ost );
    template <class TestCase> friend void do_toString(
        const TestCase * tc , std::basic_ostringstream<char> & ost );
    #ifdef English_dox
         /// Test case.
    #endif
    #ifdef Spanish_dox
         /// Caso de prueba.
    #endif
    friend class TestCase;
}; // TestCaseFailure


// Abstract base class for every test case ==>
// - It's always mandatory to reimplement \c TestCase::run().
class TestCase {
protected:
    int          m_pass;    // number successful tests
    int          m_failure; // number of non successful tests [broken assert_XXX()]
    const char * m_name;    // name for the test case
    bool         m_test_suite_destroy; // true means destroy from dynamic memory
    std::list<TestCaseFailure> m_failureList; // container for al non successful tests
public:
    TestCase(const char * name=0);
    virtual ~TestCase() { }
    virtual bool run() = 0; // must implement in derived class
    void runBare();
    bool Run()     { return run(); } // same as run()
    bool runTest() { return run(); }
    virtual void setUp();
    virtual void tearDown();
    int  countTestCases() const { return 1; } // more than 1 for TestSuite<>
    // errorCount() == 0 ==> "error" means "wrong exception"
    int  runCount() const { return successCount()+failureCount()+errorCount(); }
    virtual int failureCount() const { return m_failure; }
    int  errorCount() const { return 0; }
    virtual int successCount() const { return m_pass; }
    // true when all runs have been a success
    bool wasSuccessful() const { return successCount() == runCount(); }
    virtual void reset(); // resets al counter back to 0
public:
    std::string getName() const;
    void setName( const char * name=0 );
    virtual const std::string toString() const;
    virtual const std::string summary() const;
    virtual const std::string toXML() const;
    const std::string report() const { return summary() + '\n' + toString(); }
    const std::string failureString() const { return toString(); }
    template <class T> static std::string toString( const T & val );
protected:
    void recordSuccess() { ++m_pass; } // record another successful test
    void recordFailure( // (char*) version
        const char* label, const char* fname, int lineno,
        bool must_copy=false );
    void recordFailure( // std::string version
        const std::string& label, const char* fname, int lineno );
    void testThis( // (char*) version ==> don't destroy label
        bool cond, const char*        label, const char* fname, long lineno,
        bool must_copy=false );
    void testThis( // string<> version ==> create copy of "label" in dynamic memory
        bool cond, const std::string& label, const char* fname, long lineno );
    template <class TestCase> friend
    void do_toXML( const TestCase * tc , std::basic_ostringstream<char> & ost );
    template <class TestCase> friend
    void do_toString( const TestCase * tc , std::basic_ostringstream<char> & ost );
    template <class TestCase> friend class TestSuite; ///< Colección de pruebas.
    int  nPass()  const { return m_pass; }    // Deprecated: it's here for
    int  nError() const { return m_failure; } // compatibility with Allison's work
private:
    virtual bool iAmTestSuite() const { return false; } // I am NOT a TestSuite<>
    TestCase(const TestCase&);            // trick to prevent copy on init
    TestCase& operator=(const TestCase&); // trick to prevent copying
    #ifdef English_dox
         /// Test case class for \c BUnit.h
    #endif
    #ifdef Spanish_dox
          /// Clase de prueba para \c BUnit.h
    #endif
    friend class test_BUnit;
}; // TestCase

#ifdef Spanish_dox
/// Sinónimo de \c TestCase.
#endif
#ifdef English_dox
/// Synonym for \c TestCase.
#endif
typedef TestCase TestCase_is_base_for_TestSuite;

// Test collection.
template <class TestCase>
class TestSuite : public TestCase_is_base_for_TestSuite {
public:
    typedef std::list<TestCase_is_base_for_TestSuite*> container_type;
    typedef container_type::iterator iterator;
    typedef const container_type::iterator cons_iterator;
    typedef const container_type const_container_type;
private:
    container_type m_allTest; // holds [pointers to] failed tests
public:
    TestSuite(const char * name=0): TestCase(name), m_allTest() { }
    virtual ~TestSuite();
    bool addTest(TestCase& T);
    bool addTest(TestCase* T);
    void addSuite( TestSuite& SSS );
    bool run(); // implemented: TestSuite<> is not an abstract class
    void runBare();
    int  countTestCases() const { return int(m_allTest.size()); }
    int  failureCount() const;
    int  successCount() const;
    void reset();
    const_container_type& allTests() const { return m_allTest; }
    const std::string toString() const;
    const std::string summary() const;
    const std::string toXML() const;
private:
    bool iAmTestSuite() const { return true; }
    TestSuite(const TestSuite& DONTcopy);
    TestSuite& operator=(const TestSuite& DONTcopy); // forbid copying
}; // TestSuite

/************************\
**************************
**                      **
**       BUnit.h        **
**                      **
**************************
\************************/

#ifdef English_dox
    /// Doxygen English documentation.
    #define English_dox   "Doxygen English documentation"
   /// \def English_dox  ///< Marks English documentation blocks.
#endif
#ifdef Spanish_dox
    /// Documentación en español.
    #define Spanish_dox "Documentación en español"
   /// \def Spanish_dox  ///< Macro usado para que Doxygen genere documentación
#endif

#ifdef English_dox
/** \mainpage

\section sec-01 [B]asic module for [unit] program testing.

Header file \c BUnit.h supports writing modules for unit program testing.
The model used for this implementation is similar to that described in
the article "The Simplest Automated Unit Test Framework That Could
Possibly Work "by Chuck Allison, which you can get here:
- http://www.stickyminds.com/getfile.asp?ot=XML&id=3129&fn=XDD3129filelistfilename1.pdf
- http://www.google.com/search?num=100&as_q=Simplest+Unit+Test+Allison
- http://search.yahoo.com/search?n=100&p=Simplest+Unit+Test+Allison

- To simplify to a minimum the task of writing test cases, the full
  implementation of \c BUnit is contained within the single header
  file \c BUnit.h, so testing requieres only this directive:
  - <strong>\#include "BUnit.h"</strong>
- This framework is similar to JUnit, because it is presumed that
  in the future students will use Java as their primary language
  to develop programs (as C++ is used only for deep training in
  programming techniques).
  \see http://search.yahoo.com/search?n=100&p=JUnit+Java
- As C++ does not have a mechanism similar to Java's "reflection",
  for each failed test the exact test condition is recorded
  using an invocation to macro \c BUnit_TEST() that also records
  the filename \c __FILE__ and the line \c __LINE__ for that test.
  \see http://search.yahoo.com/search?n=100&p=reflection+Java
- In JUnit class \c TestCase is a subclass of \c Assert; in BUnit no
  \c Assert class exist but to maintain compatibility with JUnit similar
  functionality is provided with macros whose names begin with "assert".
  \see http://search.yahoo.com/search?n=100&p=JUnit+Java+Assert+method
- To simplify this framework no difference is made between a test that
  is not successfull and one that didn´t succeed because the correct
  exception was not raised. This is a contrast with JUnit where an
  "error" is a test case that raised the wrong exception. This
  explains why \c TestCase::errorCount() always returns zero \c 0.
    \code
    // Failure vs Error in JUnit
    public void test_Fail () {
        try {
            new ArrayList(10).get( 11 );
            fail("Error if IndexOutOfBoundsException is not thrown" ); // error
        }
        catch (IndexOutOfBoundsException success) { } // Ok
    }
    public void test_Failure() {
        assertTrue( 1 == 2 ); // failure
    }
    \endcode
- In \c BUnit.h no difference is made between "failures" and "errors".
  - En \c JUnit an "error" means that the wrong exception was raised.
  - En \c JUnit a "failure" means that an assertion was false.
  - \see http://osdir.com/ml/java.junit.user/2002-06/msg00114.html
  - \see http://search.yahoo.com/search?n=100&p=junit+difference+failure+error
- In JUnit, what's the difference between a failure and an error?
  - Assertions are used to check for the possibility of failures,
    therefore failures are anticipated with invokations similar to \c assertTrue().
  - Errors are unanticipated problems resulting in uncaught exceptions
    being propagated from a JUnit test method.
  - \see http://www.cs.waikato.ac.nz/~bernhard/314/junit3.8.1/doc/faq/faq.htm#tests_9
  - \see http://www.cs.wm.edu/~noonan/junit/doc/faq/faq.htm#tests_9

\dontinclude test_BUnit.cpp
\skipline    test::Allison()
\until       }}
\see         test_BUnit::test_Allison()
*/
#endif
#ifdef Spanish_dox
/** \mainpage

\section sec-01 Módulo [B]ásico para prueba [unit]aria de programas.

El archivo de encabezado \c BUnit.h apoya la escritura de módulos de prueba de
unitaria programas. El modelo que se usa para esta implementación es
similar al expuesto en este artículo "The Simplest Automated Unit
Test Framework That Could Possibly Work" de Chuck Allison, que se
puede obtener aquí:
- http://www.stickyminds.com/getfile.asp?ot=XML&id=3129&fn=XDD3129filelistfilename1.pdf
- http://www.google.com/search?num=100&as_q=Simplest+Unit+Test+Allison
- http://search.yahoo.com/search?n=100&p=Simplest+Unit+Test+Allison

- Para simplificar al mínimo la tarea de programar los casos de prueba,
  la implementación completa de \c BUnit está contenida en el archivo
  de encabezado \c BUnit.h, por lo que para hacer pruebas basta poner
  esta directiva:
  - <strong>\#include "BUnit.h"</strong>
- Este marco de pruebas es similar a JUnit, pues se presume que en
  el futuro los estudiantes usarán Java como su lenguaje principal
  para desarrollo de programas (pues usan C++ sólo para adiestrarse
  profundamente en técnicas de programación).
  \see http://search.yahoo.com/search?n=100&p=JUnit+Java
- Como el lenguaje C++ no tiene un mecanismo similar al de "reflexión"
  de Java, en cada prueba fallida se registra la condición de prueba
  exacta, obtenida a través de una invocación de la macro \c BUnit_TEST()
  que registra el nombre del archivo \c __FILE__ y el renglón \c __LINE__
  de la prueba.
  \see http://search.yahoo.com/search?n=100&p=reflection+Java
- En JUnit la clase \c TestCase es una subclase de \c Assert; en BUnit no
  existe la clase \c Assert pero para mantener compatibilidad con JUnit
  sí se provée funcionalidad similar usando macros cuyos nombres comienzan
  con "assert".
  \see http://search.yahoo.com/search?n=100&p=JUnit+Java+Assert+method
- Para simplificar este marco de pruebas no se usa la clase \c TestResult
  que sirve para acumular resultados de las pruebas. En su lugar, se puede
  obtener una hilera enorme \c std::string que contiene el registro de
  todas las pruebas que no tuvieron éxito invocando el método
  \c TestCase::toString() o \c TestCase::toXML().
- Para simplificar esta plataforma de pruebas no se hace diferencia entre
  un caso de prueba de prueba no existoso y uno que no tiene éxito porque no
  se ha levantado la excepción adecuada. Esto contrasta con JUnit, que
  llama "error" a un caso de prueba que ha levantado la excepción equivocada.
  Por eso \c TestCase::errorCount() siempre retorna cero \c 0.
    \code
    // Falla vs Error en JUnit
    public void test_Error() {
        try {
            new ArrayList(10).get( 11 );
            fail("Error si no tira IndexOutOfBoundsException" ); // error
        }
        catch (IndexOutOfBoundsException success) { } // Ok
    }
    public void test_Failure() {
        assertTrue( 1 == 2 ); // falla
    }
    \endcode
- En \c BUnit.h no se hace diferencia entre "fallas" y "errores".
  - En \c JUnit un "error" se produce cuando no se levanta la excepción adecuada.
  - En \c JUnit una "falla" se produce cuando una aserción resulta falsa.
  - \see http://osdir.com/ml/java.junit.user/2002-06/msg00114.html
  - \see http://www.cs.waikato.ac.nz/~bernhard/314/junit3.8.1/doc/faq/faq.htm#tests_9
  - \see http://search.yahoo.com/search?n=100&p=junit+difference+failure+error
- In JUnit, ¿cuál es la diferencia entre fallas y errores?
  - Las aseveraciones son usadas para verificar si existen fallas, y por eso las
    fallas son previstas con invocaciones similares a \c assertTrue().
  - Los errores son problemas no previstos que resultan de excepciones no captadas
    por los método de prueba JUnit.
  - \see http://www.cs.waikato.ac.nz/~bernhard/314/junit3.8.1/doc/faq/faq.htm#tests_9
  - \see http://www.cs.wm.edu/~noonan/junit/doc/faq/faq.htm#tests_9

\dontinclude test_BUnit.cpp
\skipline    test::Allison()
\until       }}
\see         test_BUnit::test_Allison()
*/
#endif

#ifdef Spanish_dox
    // using namespace std;
    /// Definido por la biblioteca C++ estándar.
    namespace std {} // It's here for Doxygen to document it
#endif
#ifdef English_dox
    // using namespace std;
    /// Defined by the C++ estándar library.
    namespace std {} // Está acá para que Doxygen lo documente
#endif

/// Escuela de Ciencias de la Computación e Informática.
/// \see http:www.ecci.ucr.ac.cr
namespace ECCI { }

/************************\
**************************
**                      **
**   TestCaseFailure    **
**                      **
**************************
\************************/

#ifdef English_dox
/** \class TestCaseFailure
    \brief Private class to hold test cases that didn´t succeed.
*/
/** \var   const char * TestCaseFailure::m_fname;
    \brief Name of the file where the failure was produced.
*/
/** \var   int TestCaseFailure::m_lineno;
    \brief Line number in the file where the failure was produced.
*/
/** \var   const char * TestCaseFailure::m_label;
    \brief Descriptive message for the failure.
*/
/** \var   bool TestCaseFailure::m_destroy_label;
    \brief Holds \c "true" if the destructor should return the dynamic memory for \c m_label.
*/
/** \fn    TestCaseFailure::TestCaseFailure();
    \brief Default constructor.
*/
/** \fn    TestCaseFailure::TestCaseFailure(const char * fname, int line, const char * label, bool destroy );
    \brief Private constructor that can set \c m_label to \c true.
*/
#endif
#ifdef Spanish_dox
/** \class TestCaseFailure
    \brief Clase privada que contiene los datos de cada prueba no exitosa.
*/
/** \var   const char * TestCaseFailure::m_fname;
    \brief Nombre del archivo en donde se produjo el error.
*/
/** \var   int TestCaseFailure::m_lineno;
    \brief Número de línea del archivo en donde se produjo el error.
*/
/** \var   const char * TestCaseFailure::m_label;
    \brief Mensaje descriptivo del error.
*/
/** \var   bool TestCaseFailure::m_destroy_label;
    \brief Contiene \c "true" si el destructor debe retornar la memoria dinámica de \c m_label.
*/
/** \fn    TestCaseFailure::TestCaseFailure();
    \brief Constructor por defecto.
*/
/** \fn    TestCaseFailure::TestCaseFailure(const char * fname, int line, const char * label, bool destroy );
    \brief Constructor Privado que puede inicializar \c m_label en \c true.
*/
#endif

#ifdef English_dox
/** \fn    TestCaseFailure::~TestCaseFailure();
    \brief Destructor.
*/
/** \fn    TestCaseFailure::TestCaseFailure( const TestCaseFailure& o );
    \brief Copy constructor.
*/
/** \fn    void TestCaseFailure::operator = ( TestCaseFailure& o );
    \brief Copy operator used to insert into contanier.
*/
#endif

#ifdef Spanish_dox
/** \fn    TestCaseFailure::~TestCaseFailure()
    \brief Destructor.
*/
/** \fn    TestCaseFailure::TestCaseFailure( const TestCaseFailure& o );
    \brief Constructor de copia.
*/
/** \fn    void TestCaseFailure::operator = ( TestCaseFailure& o )
    \brief Copiador usado al insertar en el contenedor.
*/
#endif

/************************\
**************************
**                      **
**      TestCase        **
**                      **
**************************
\************************/

#ifdef English_dox
/** \class TestCase
    \brief Every test case is an instance derived from this abstract class.
     - It's always mandatory to reimplement \c TestCase::run().
*/
/** \fn    int TestCase::m_pass;
    \brief Number of successful tests.
*/
/** \fn    int TestCase::m_failure;
    \brief Number of test that produced failed.
*/
/** \fn    const char * TestCase::m_name;
    \brief Test case name.
*/
/** \fn    bool TestCase::m_test_suite_destroy;
    \brief Holds \c "true" if the test case is stored in dynamic memory.
*/
/** \fn    std::list<TestCaseFailure> TestCase::m_failureList;
    \brief Container where test cases that produced failures are stored.
*/
#endif

#ifdef Spanish_dox
/** \class TestCase
    \brief Cada caso de prueba es una instancia derivada de esta clase abstracta.
     - Siempre es obligatorio reimplementar \c TestCase::run().
*/
/** \fn    int TestCase::m_pass;
    \brief Cantidad de pruebas exitosas.
*/
/** \fn    int TestCase::m_failure;
    \brief Cantidad de pruebas que han fallado.
*/
/** \fn    const char * TestCase::m_name;
    \brief Nombre del caso de prueba.
*/
/** \fn    bool TestCase::m_test_suite_destroy;
    \brief Contiene \c "true" si la prueba está almacenada en memoria dinámica.
*/
/** \fn    std::list<TestCaseFailure> TestCase::m_failureList;
    \brief Contenedor para almacenar las pruebas que han producido fallas.
*/
#endif

#ifdef English_dox
/** \fn    virtual TestCase::~TestCase();
    \brief Destructor.
*/
/** \fn    virtual bool TestCase::run() = 0;
    \brief <strong>[virtual]</strong> ==> Executes test and returns \c "false" if not successful.
    <strong>[***]</strong> It is always mandatory to redefine method \c run().
    \see runBare().
*/
/** \fn    bool TestCase::Run();
    \brief Synonym for \c run().
*/
/** \fn    bool TestCase::runTest();
    \brief Synonym for \c run().
*/
/** \fn    int  TestCase::countTestCases() const;
    \brief 1 == Number of test cases.
    The value returned always is one \c 1 because class \c TestCase
    represents a single test case. For the container \c TestSuite<>
    the value returned can be bigger than \c 1.
    - A "test case" is a class, derived from class \c TestCase.
    - A "test run" gets counted when either a specific test succeeds or fails.
    - A "test run" gets counted when protected method TestCase::testThis() is
      executed, either directly or through any BUnit \c "assert()" macro, as
      \c assertTrue(), \c fail_Msg(), \c assertEquals_Delta(), or others like
      \c BUnit_SUCCESS() or \c BUnit_TEST().
    - A "test case" ussually has many "test runs". A collection of "test cases"
      resided within an instance derived from class \c TestSuite<>.
*/
/** \fn    int  TestCase::runCount() const;
    \brief Number of test runs.
    - Synonym for <code>successCount()+failureCount()+errorCount()</code>.
    \see reset().
*/
/** \fn    virtual int TestCase::failureCount() const;
    \brief Number of test runs that failed. \see reset().
*/
/** \fn    int  TestCase::errorCount() const;
    \brief Always returns \c 0 (cero): "Number of errors".
    - BUnit does not maintain separate counts for "errors" and "failures".
    \see http://osdir.com/ml/java.junit.user/2002-06/msg00114.html
*/
/** \fn    virtual int TestCase::successCount() const;
    \brief Number of successful test runs. \see reset().
*/
/** \fn    bool TestCase::wasSuccessful() const;
    \brief Returns \c "true" when all test runs where successful.
    - Synonym for <code>(successCount() == runCount())</code>
*/
/** \fn    std::string TestCase::getName() const;
    \brief Gets the test case name. \see setName().
*/
/** \fn    const std::string TestCase::report() const;
    \brief Returns string \c summary() followed by \c toString().
*/
/** \fn    const std::string TestCase::failureString() const;
    \brief Synonym for \c toString().
*/
/** \fn    void TestCase::recordSuccess();
    \brief Records the test run as a success.
*/
/** \fn    int  TestCase::nPass()  const;
    \brief Synonym for \c successCount() [OBSOLETE]. \deprecated
*/
/** \fn    int  TestCase::nError() const;
    \brief Synonym for \c failureCount() [OBSOLETE]. \deprecated
*/
/** \fn    virtual bool TestCase::iAmTestSuite() const;
    \brief Returns \c false for \c TestCase.
*/
/** \fn    TestCase::TestCase(const TestCase&);
    \brief This \c "private" declaration forbids test case copying.
*/
/** \fn    TestCase& TestCase::operator=(const TestCase&);
    \brief This \c "private" declaration forbids test case copying.
*/
#endif
#ifdef Spanish_dox
/** \fn    virtual TestCase::~TestCase();
    \brief Destructor.
*/
/** \fn    virtual bool TestCase::run() = 0;
    \brief <strong>[virtual]</strong> ==> Ejecuta la prueba y retorna \c "false" si produce error.
    <strong>[***]</strong> Siempre es necesario redefinir el método \c run().
    \see runBare().
*/
/** \fn    bool TestCase::Run();
    \brief Sinónimo de \c run().
*/
/** \fn    bool TestCase::runTest();
    \brief Sinónimo de \c run().
*/
/** \fn    int  TestCase::countTestCases() const;
    \brief 1 == Cantidad de casos de prueba.
    El valor retornado siempre es uno \c 1 porque la clase \c TestCase
    representa un único caso de pruebas. Para el contenedor
    \c TestSuite<> el valor retornado puede ser mayor a \c 1.
    - Un "caso de prueba" es una clase derivada de la clase \c TestCase.
    - Una "prueba" se cuenta cuando tiene éxito o fracasa.
    - Una "prueba" se cuenta cuando el método protegido TestCase::testThis() es
      ejecutado, ya sea directamente o a través de cualquiera de los macros
      \c "assert()" de BUnit, como lo son \c assertTrue(), \c fail_Msg(),
      \c assertEquals_Delta(), u otros como \c BUnit_SUCCESS() or \c BUnit_TEST().
    - Un "caso de prueba" generalmente incluye muchas "pruebas". Una colección de
      "casos de prueba" reside en una instancia derivada de la clase \c TestSuite<>.
*/
/** \fn    int  TestCase::runCount() const;
    \brief Cantidad total de pruebas realizadas.
    - Sinónimo de <code>successCount()+failureCount()+errorCount()</code>.
    \see reset().
*/
/** \fn    virtual int TestCase::failureCount() const;
    \brief Cantidad de pruebas que fallaron. \see reset().
*/
/** \fn    int  TestCase::errorCount() const;
    \brief Siempre retorna \c 0 (cero): "Cantidad de errores".
    - BUnit no se contabilizan aparte los "errores" de las "fallas".
    \see http://osdir.com/ml/java.junit.user/2002-06/msg00114.html
*/
/** \fn    virtual int TestCase::successCount() const;
    \brief Cantidad de pruebas exitosas. \see reset().
*/
/** \fn    bool TestCase::wasSuccessful() const;
    \brief Retorna \c "true" si todas las pruebas han sido exitosas.
    - Sinónimo de <code>(successCount() == runCount())</code>
*/
/** \fn    std::string TestCase::getName() const;
    \brief Obtiene el nombre de la prueba. \see setName().
*/
/** \fn    const std::string TestCase::report() const;
    \brief Retorna la hilera encabezado \c summary() seguido \c toString().
*/
/** \fn    const std::string TestCase::failureString() const;
    \brief Sinónimo de \c toString().
*/
/** \fn    void TestCase::recordSuccess();
    \brief Registra como exitoso el resultado de una prueba.
*/
/** \fn    int  TestCase::nPass()  const;
    \brief Sinónimo de \c successCount() [OBSOLETO]. \deprecated
*/
/** \fn    int  TestCase::nError() const;
    \brief Sinónimo de \c failureCount() [OBSOLETO]. \deprecated
*/
/** \fn    virtual bool TestCase::iAmTestSuite() const;
    \brief Retorna \c false para \c TestCase.
*/
/** \fn    TestCase::TestCase(const TestCase&);
    \brief Esta declaración \c "private" prohibe la copia de casos de prueba.
*/
/** \fn    TestCase& TestCase::operator=(const TestCase&);
    \brief Esta declaración \c "private" prohibe la copia de casos de prueba.
*/
#endif

#ifdef Spanish_dox
/** Constructor.
    Si no se indica el nombre en \c "name", después el nombre se obtiene
    invocando <code>typeid(*this).name()</code>.
*/
#endif
#ifdef English_dox
/** Constructor.
    If no name is given to this constructor in \c "name", later the
    name will be obtained invoking <code>typeid(*this).name()</code>.
*/
#endif
/** \dontinclude test_BUnit.cpp
    \skipline    test::constructor()
    \until       }}
    \see         test_BUnit::test_constructor()
*/
inline TestCase::TestCase(const char * name) :
    m_pass(0), m_failure(0), m_name(name),
    m_test_suite_destroy(false), m_failureList() { }

#ifdef Spanish_dox
/** Elimina todas las pruebas realizadas.
    - Anula los contadores de pruebas porque deja la clase en el estado
      inicial que tuvo al ser construida.
    - Borra el registro de pruebas no exitosas.
    - No borra el nombre de la prueba.
*/
#endif
#ifdef English_dox
/** Discards all test runs.
    - Resets to cero al counters because the test case is left in
      the state it had when initially contructed.
    - Deletes the record for not successful tests.
    - Does not change the test case name.
*/
#endif
/** \dontinclude test_BUnit.cpp
    \skipline    test::reset()
    \until       }}
    \see         test_BUnit::test_reset()
*/
inline void TestCase::reset() {
    m_pass =  m_failure = 0;
    m_failureList.clear();
}

inline std::string TestCase::getName() const {
    return ( m_name != 0 ? m_name : typeid(*this).name() );
}

#ifdef Spanish_dox
/** Le cambia el nombre a la prueba por \c "name".
    - Si \c "name" es una hilera o puntero nulo, después
      usa <code>typeid(*this).name()</code> para obtener
      el nombre de la prueba.
*/
#endif
#ifdef English_dox
/** Sets the test case name to \c "name".
    - When \c "name" is a null string or pointer, later
      <code>typeid(*this).name()</code> will be invoked
      to get the test´s name.
*/
#endif
/** \dontinclude test_BUnit.cpp
    \skipline    test::setName()
    \until       }}
    \see         test_BUnit::test_setName()
*/
inline void TestCase::setName( const char * name ) {
    m_name = name;
}

#ifdef Spanish_dox
/** Ejecuta la prueba <code>setUp(); run(); tearDown();</code>.
    - A diferencia de \c run(), este método sí establece el ambiente
      de prueba invocando \c setUp() y \c tearDown() antes y después
      de hacer la prueba.
*/
#endif
#ifdef English_dox
/** Excecutes the test run <code>setUp(); run(); tearDown();</code>.
    - In contrast to \c run(), this method will setup the environment
      for the test run invoking \c setUp() and \c tearDown() before and
      after the test.
*/
#endif
/** \dontinclude test_BUnit.cpp
    \skipline    test::run()
    \until       }}
    \see         test_BUnit::test_run()
*/
inline void TestCase::runBare( ) { setUp(); run(); tearDown(); }

#ifdef Spanish_dox
/** Establece el ambiente para la ejecución de la prueba.
    Esta clase existe para mejorar la compatibilidad con JUnit.
    \see TestCase::setUp()
*/
#endif
#ifdef English_dox
/** Sets the environment for the test run.
    This clase exists to improve compatibility with JUnit.
    \see TestCase::setUp()
*/
#endif
typedef TestCase TestFixture;

#ifdef Spanish_dox
/** Establece el ambiente en que se realizará la prueba.
    - Como \c TestCase::run() es un método abstracto, para facilitar la
      programación lo usual es que el programador no incluya invocaciones
      a \c TestCase::setUp() y \c TestCase::tearDown() pues es más fácil
      dejar que lo haga \c TestSuite<TestCase>::runBare().
    - A diferencia de \c TestCase::runBare(), el método \c TestCase::run()
      no establece el ambiente de prueba porque no invoca ni a
      \c TestCase::setUp() antes de la prueba ni a \c TestCase::tearDown()
      después de la prueba.
    - \c TestSuite<TestCase>::runBare() invoca los métodos
      \c TestCase::setUp() y \c TestCase::tearDown() cuando ejecuta cada
      prueba.
    - Si el programador cliente quiere que cada prueba se ejecute luego de
      establecer el ambiente de la prueba, lo más práctico es que agregue
      sus pruebas a una colección de pruebas \c TestSuite para ejecutarlas
      con \c TestSuite<TestCase>::runBare().
*/
#endif
#ifdef English_dox
/** Sets the environment for the test run.
    - As \c TestCase::run() is an abstract method, to facilitate
      programming it is usual for the programmer not to invoke
      \c TestCase::setUp() and \c TestCase::tearDown() because it is
      easier to have \c TestSuite<TestCase>::runBare() do it.
    - In contrast with \c TestCase::runBare(), method  \c TestCase::run()
      will not establish the test environment because it does not
      invoke neither \c TestCase::setUp() before the test run nor
      \c TestCase::tearDown() after the test run.
    - \c TestSuite<TestCase>::runBare() invokes methods
      \c TestCase::setUp() and \c TestCase::tearDown() when the test run
      is executed.
    - If the client programmer wants each test run  to stablish it test
      environment, it is easier to put all test cases into a test collection
      \c TestSuite and execute all of them invoking
      \c TestSuite<TestCase>::runBare().
*/
#endif
inline void TestCase::setUp() { }

#ifdef Spanish_dox
/// Destruye el ambiente de prueba.
#endif
#ifdef English_dox
/// Destroys the test environment.
#endif
inline void TestCase::tearDown() {}

#ifdef Spanish_dox
/** Efectúa la prueba y registra su resultado.
    - Si la prueba fue exitosa sólo incrementa la cantidad de éxitos
      \c successCount().
    - Si la prueba no tuvo éxito reporta en \c toString() ese hecho.
    - El resultado de la prueba es \c "cond".
    - Los valores \c "fname" y \c "lineno" indican el archivo y el renglón
      en donde se ejecuta la prueba.
    - Usualmente los valores de \c "fname" y \c "lineno" se obtienen con
      las macros globales \c "__FILE__" y \c "__LINE__".
    - El valor \c "must_copy" indica que es necesario hacer una copia de la
      hilera \c "label", copia que será destruida cuando el registro de
      pruebas no exitosas sea borrado.
    - En la mayor parte de los casos, la hilera \c "label" es una constante
      generada por el preprocesador al usar la macro \c \#cond y por eso su
      memoria no debe ser retornada.
    Este método es invocado usando la macro \c BUnit_TEST().
*/
#endif
#ifdef English_dox
/** Executes the test and records its result.
    - If the test is successful only increases the numbero of success
      \c successCount().
    - If the test is not successful reports in \c toString() this fact.
    - The result of the test is \c "cond".
    - Values \c "fname" and \c "lineno" show the file and line of the
      executed test.
    - Usuallyy \c "fname" and \c "lineno" are values obtained with global
      macros \c "__FILE__" and \c "__LINE__".
    - The value for \c "must_copy" indicates whether it is necessary to
      make a copy of string \c "label"; this copy will be destroyed when
      the record of not successful test is deleted.
    - Most of the time string \c "label" is a constant genertated by the
      preprocessor when using macro \c \#cond its memory must not be
      returned.
    This method is invoked using macro \c BUnit_TEST().
*/
#endif
/** \dontinclude test_BUnit.cpp
    \skipline    test::testThis()
    \until       }}
    \see         test_BUnit::test_testThis()
*/
inline void TestCase::testThis(
    bool cond, const char * label, const char* fname, long lineno, bool must_copy )
{
    if (cond) {
        recordSuccess();
    }
    else {
        recordFailure( label, fname, lineno, must_copy );
    }
}

#ifdef Spanish_dox
/// Sinónimo de \c testThis().
#endif
#ifdef English_dox
/// Synonym for \c testThis().
#endif
inline void TestCase::testThis(
    bool cond, const std::string& label, const char* fname, long lineno )
{
    testThis( cond, label.c_str(), fname, lineno, true /* must_copy == true */ );
/*  NOTE: In the class instance the name for the test case is stored as
    a (char*). If a std::string is used for "label", it must be converted to
    a (char*) that will have to be destroyed when the test instance gets
    destroyed. This is why parameter "must_copy" must be set to "true".
*/
}

#ifdef Spanish_dox
/** Registra que la prueba no tuvo éxito.
    - Los valores \c "fname" y \c "lineno" indican el archivo y el renglón
      en donde se ejecuta la prueba.
    - Usualmente los valores de \c "fname" y \c "lineno" se obtienen invocando
      las macros globales \c "__FILE__" y \c "__LINE__".
    - El valor \c "must_copy" indica que es necesario hacer una copia de la
      hilera \c "label" en memoria dinámica. Este memoria dinámica será destruida
      cuando el caso de prueba sea destruido o cuando el método \c TestCase::reset()
      sea invocado.
    - En la mayor parte de los casos, la hilera \c "label" es una constante
      generada por el preprocesador al usar la macro \c \#cond; como esta hilera
      constante no está almacenada en la memoria dinámica no debe ser destruida.

    Este método es invocado usando la macro \c BUnit_FAILURE().
*/
#endif
#ifdef English_dox
/**  Records that the test run did not succeed.
    - Values \c "fname" and \c "lineno" indicate the file and line where
      the test run is executed.
    - The values form \c "fname" and \c "lineno" are usuallly obtained
      invoking global macros \c "__FILE__" and \c "__LINE__".
    - \c "must_copy" forces a copy of string label to be created in dynamic
      memory. This dynamic memory will be destroyed when the test case gets
      destroyed or when method \c TestCase::reset() gets invoked.
    - Oftentimes string \c "label" is a constant string generated by the
      preprocessor macro using \c \#cond; this string constant is not stored
      in dynamic memory and it must not be destroyed.

    This method is invoked using macro \c BUnit_FAILURE().
*/
#endif
inline void TestCase::recordFailure(
    const char* label, const char* fname, int lineno, bool must_copy )
{
    if ( must_copy ) {
        size_t len = strlen(label)+1;
        char* str = new char[ len ]; // copies the failure message
        memcpy( str, label, len );
        label = str;
    }
    m_failureList.push_back( TestCaseFailure ( fname, lineno, label, must_copy ) );
    m_failure++;
/*  NOTE: When this method is invoked directly it is because "label" is a
    constant (char*) string, produced by one of the BUnit_TEST() macro using
    operator "#" (as in #cond). As thi