readme

VC源码,开源测试工具.有助于VC++的学习与开发

Documentation TUT How-To minimum steps to make TUT work for you

What is TUT

TUT is a pure C++ unit test framework. Its name - TUT - stands for 
Template Unit Tests.

Features

TUT provides all features required for unit testing:

    * Similar tests can be grouped together into test groups. Each 
      test group has its unique name and is located in a separate 
      compilation unit. One group can contain almost unlimited number 
      of tests (actually, the limit is the compiler template 
      recursion depth).
    * User can run all the tests (regression), or just some selected 
      groups or even some tests in these groups.
    * TUT provides special template functions to check the condition 
      validity at run-time and to force test failure if required. 
      Since C++ doesn't provide a facility for obtaining stack trace 
      of the throwed exception and TUT avoids macros, those functions 
      accept string marker to allow users easely determine the source 
      of exception.
    * TUT contains callback that can be implemented by the calling code 
      to integrate with an IDE, for example. Callbacks tell listener 
      when a new test run started, when test runner switches to the 
      next tests group, when a test was completed (and what result it 
      has), and when test run was finished. The callbacks allow users 
      to produce their own visualization format for test process and results.
    * Being a template library, it doesn't need compilation; just 
      include the <tut.h> header into the test modules.

TUT tests organization

Test application

C++ produces executable code, so tests have to be compiled into a single 
binary called test application. The application can be built in automated 
mode to perform nightly tests. They also can be built manually when a 
developer hunts for bugs.

The test application contains tests, organized into test groups.

Test groups

The functionality of a tested application can be divided into a few separate 
function blocks (e.g. User Rights, Export, Processing, ...). It is natural 
to group together tests for each block. TUT invokes this test group. Each 
test group has a unique human-readable name and normally is located in a 
separate file.

Tests

Each single test usually checks only one specific element of functionality. 
For example, for a container a test could check whether size() call 
returns zero after the successful call to the clear() method.

Writing simple test

Preamble

You are going to create a new class for your application. You decided to 
write tests for the class to be sure it works while you are developing or, 
possibly, enhancing it. Let's consider your class is shared pointer: 
std::auto_ptr-alike type that shares the same object among instances.

Prior to test writing, you should decide what to test. Maximalist's 
approach requires to write so many tests that altering any single 
line of your production code will break at least one of them. 
Minimalist's approach allows one to write tests only for the most 
general or the most complex use cases. The truth lies somewhere in 
between, but only you, developer, know where. You should prepare 
common successful and unsuccessful scenarios, and the scenarios for 
testing any other functionality you believe might be broken in some way.

For our shared_ptr we obviosly should test constructors, assignment operators, referencing and passing ownership.

Skeleton

If you don't have any implemented class to test yet, it would be good to 
implement it as a set of stubs for a first time. Thus you'll get an 
interface, and be able to write your tests. Yes, that's correct: you 
should write your tests before writing code! First of all, writing tests 
often helps to understand oddities in the current interface, and fix it. 
Secondly, with the stubs all your tests will fail, so you'll be sure 
they do their job.

Creating Test Group

Since we're writing unit tests, it would be a good idea to group the 
tests for our class in one place to be able to run them separately. 
It's also natural in C++ to place all the grouped tests into one 
compilation unit (i.e. source file). So, to begin, we should create 
a new file. Let's call it test_shared_ptr.cpp. (Final variant of the 
test group can be found in examples/shared_ptr subdirectory of the 
distribution package)

// test_shared_ptr.cpp
#include <tut.h>

namespace tut
{
};
            

As you see, you need to include TUT header file (as expected) and 
use namespace tut for tests. You may also use anonymous namespace if 
your compiler allows it (you will need to instantiate methods from 
tut namespace and some compilers refuse to place such instantiations 
into the anonymous namespace).

A test group in TUT framework is described by the special template 
test_group<T>. The template parameter T is a type that will hold all 
test-specific data during the test execution. Actually, the data 
stored in T are member data of the test. Test object is inherited 
from T, so any test can refer to the data in T as its member data.

For simple test groups (where all data are stored in test local 
variables) type T is an empty struct.

#include <tut.h>

namespace tut
{
  struct shared_ptr_data
  { 
  };
}
            
But when tests have complex or repeating creation phase, you may put 
data members into the T and provide constructor (and, if required, 
destructor) for it. For each test, a new instance of T will be 
created. To prepare your test for execution TUT will use default 
constructor. Similarly, after the test has been finished, TUT 
calls the destructor to clean up T. I.e.:

#include <tut.h>

namespace tut
{
  struct complex_data
  {
    connection* con;
    complex_data(){ con = db_pool.get_connection(); }
    ~complex_data(){ db_pool.release_connection(con); }
  };

  // each test from now will have con data member initialized
  // by constructor:
  ...
  con->commit();
  ...
            

What will happen if the constructor throws an exception? TUT will treat 
it as if test itself failed with exception, so this test will 
not be executed. You'll see an exception mark near the test, and 
if the constructor throwed something printable, a certain message will appear.

Exception in destructor is threated a bit different. Reaching destruction 
phase means that the test is passed, so TUT marks test with warning 
status meaning that test itself was OK, but something bad has happend 
after the test.

Well, all we have written so far is just a type declaration. To work 
with a group we have to have an object, so we must create the test group 
object. Since we need only one test group object for each unit, we can 
(and should, actually) make this object static. To prevent name clash with 
other test group objects in the namespace tut, we should provide a 
descriptive name, or, alternatively, we may put it into the anonymous 
namespace. The former is more correct, but a descriptive name usually works 
well too, unless you're too terse in giving names to objects.

#include <tut.h>

namespace tut
{
    struct shared_ptr_data
    {

    };

    typedef test_group<shared_ptr_data> tg;
    tg shared_ptr_group("shared_ptr");
};
            
As you see, any test group accepts a single parameter - its human-readable 
name. This name is used to identify the group when a programmer wants to 
execute all tests or a single test within the group. So this name shall 
also be descriptive enough to avoid clashes. Since we're writing tests 
for a specific unit, it's enough to name it after the unit name.

Test group constructor will be called at unspecified moment at the test 
application startup. The constructor performs self-registration; it calls 
tut::runner and asks it to store the test group object name and location. 
Any other test group in the system undergoes the same processing, i.e. 
each test group object registers itself. Thus, test runner can iterate 
all test groups or execute any test group by its name.

Newly created group has no tests associated with it. To be more precise, 
it has predefined set of dummy tests. By default, there are 50 tests in a 
group, including dummy ones. To create a test group with higher volume 
(e.g. when tests are generated by a script and their number is higher) 
we must provide a higher border of test group size when it is instantiated:

#include <tut.h>

namespace tut
{
    struct huge_test_data
    {
    };

    // test group with maximum 500 tests
    typedef test_group<huge_test_data,500> testgroup;
    testgroup huge_test_testgroup("huge group");
};
            

Note also, that your compiler will possibly need a command-line switch 
or pragma to enlarge recursive instantiation depth. For g++, for 
example, you should specify at least --ftemplate-depth-501 to increase 
the depth. For more information see your compiler documentation.

Creating Tests

Now it's time to fill our test group with content.

In TUT, all tests have unique numbers inside the test group. Some 
people believe that textual names better describe failed tests in 
reports. I agree; but in reality C++ templates work good with numbers 
because they are compile-time constants and refuse to do the same 
with strings, since strings are in fact addresses of character 
buffers, i.e. run-time data.

As I mentioned above, our test group already has a few dummy tests; 
and we can replace any of them with something real just by writing 
our own version:

#include <tut.h>

namespace tut
{
    struct shared_ptr_data{};

    typedef test_group<shared_ptr_data> testgroup;
    typedef testgroup::object testobject;
    testgroup shared_ptr_testgroup("shared_ptr");

    template<>
    template<>
    void testobject::test<1>()
    {
        // do nothing test