readme

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

    }
};
        

So far this test does nothing, but it's enough to illustrate the concept.

All tests in the group belong to the type test_group<T>::object. This 
class is directly inherited from our test data structure. In our case, it is

class object : public shared_ptr_data { ... }
        
This allows to access members of the data structure directly, since at 
the same time they are members of the object type. We also typedef the 
type with testobject for brevity.

We mark our test with number 1. Previously, test group had a dummy test 
with the same number, but now, since we've defined our own version, it 
replaces the dummy test as more specialized one. It's how C++ template 
ordering works.

The test we've written always succeeds. Successful test returns with no 
exceptions. Unsuccessful one either throws an exception, or fails at 
fail() or ensure() methods (which anyway just throw the exception when failed).

First real test

Well, now we know enough to write the first real working test. This test 
will create shared_ptr instances and check their state. We will define a 
small structure (keepee) to use it as shared_ptr stored object type.

#include <tut.h>
#include <shared_ptr.h>

namespace tut
{
    struct shared_ptr_data
    {
        struct keepee{ int data; };
    };

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

    /**
     * Checks default constructor.
     */
    template<>
    template<>
    void testobject::test<1>()
    {
        shared_ptr<keepee> def;
        ensure("null",def.get() == 0);
    }
};
        

That's all! The first line creates shared_ptr. If constructor throws 
an exception, test will fail (exceptions, including '...', are catched 
by the TUT framework). If the first line succeeds, we must check 
whether the kept object is null one. To do this, we use test object 
member function ensure(), which throws std::logic_error with a given 
message if its second argument is not true. Finally, if destructor of 
shared_ptr fails with exception, TUT also will report this test as failed.

It's equally easy to write a test for the scenario where we expect to get 
an exception: let's consider our class should throw an exception if it 
has no stored object, and the operator -> is called.

/**
 * Checks operator -> throws instead of returning null.
 */
template<>
template<>
void testobject::test<2>()
{
    try
    {
        shared_ptr<keepee> sp;
        sp->data = 0;
        fail("exception expected");
    }
    catch( const std::runtime_error& ex )
    {
        // ok
    }
}
        

Here we expect the std::runtime_error. If operator doesn't throw it, 
we'll force the test to fail using another member function: fail(). It 
just throws std::logic_error with a given message. If operator throws 
anything else, our test will fail too, since we intercept only 
std::runtime_error, and any other exception means the test has failed.

NB: our second test has number 2 in its name; it can, actually, be any 
in range 1..Max; the only requirement is not to write tests with the 
same numbers. If you did, compiler will force you to fix them anyway.

And finally, one more test to demonstrate how to use the 
ensure_equals template member function:

/**
 * Checks keepee counting.
 */
template<>
template<>
void testobject::test<3>()
{
    shared_ptr<keepee> sp1(new keepee());
    shared_ptr<keepee> sp2(sp1);
    ensure_equals("second copy at sp1",sp1.count(),2);
    ensure_equals("second copy at sp2",sp2.count(),2);
}
        

The test checks if the shared_ptr correctly counts references during 
copy construction. What's interesting here is the template member 
ensure_equals. It has an additional functionality comparing with similar 
call ensure("second_copy",sp1.count()==2); it uses operator == to check 
the equality of the two passed parameters and, what's more important, it 
uses std::stream to format the passed parameters into a human-readable 
message (smth like: "second copy: expected 2, got 1"). It means that 
ensure_equals cannot be used with the types that don't have operator <<; 
but for those having the operator it provides much more informational message.

In contrast to JUnit assertEquals, where the expected value goes before 
the actual one, ensure_equals() accepts the expected after the actual 
value. I believe it's more natural to read ensure_equals("msg", count, 5) 
as "ensure that count equals to 5" rather than JUnit's 
"assert that 5 is the value of the count".

Running tests

Tests are already written, but an attempt to run them will be unsuccessful. 
We need a few other bits to complete the test application.

First of all, we need a main() method, simply because it must be in all 
applications. Secondly, we need a test runner singleton. Remember I said 
each test group should register itself in singleton? So, we need that 
singleton. And, finally, we need a kind of a callback handler to visualize 
our test results.

The design of TUT doesn't strictly set a way the tests are visualized; 
instead, it provides an opportunity to get the test results by means of 
callbacks. Moreover it allows user to output the results in any format he 
prefers. Of course, there is a "reference implementation" in the 
example/subdirectory of the project.

Test runner singleton is defined in tut.h, so all we need to activate it 
is to declare an object of the type tut::test_runner_singleton in the main 
module with a special name tut::runner.

Now, with the test_runner we can run tests. Singleton has method get() 
returning a reference to an instance of the test_runner class, which in 
turn has methods run_tests() to run all tests in all groups, 
run_tests(const std::string& groupname) to run all tests in a given group 
and run_test(const std::string& grp,int n) to run one test in the specified group.

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

namespace tut
{
    test_runner_singleton runner;
}

int main()
{
    // run all tests in all groups
    runner.get().run_tests();

    // run all tests in group "shared_ptr"
    runner.get().run_tests("shared_ptr");

    // run test number 5 in group "shared_ptr"
    runner.get().run_test("shared_ptr",5);

    return 0;
}
  
It's up to user to handle command-line arguments or GUI messages and map those 
arguments/messages to actual calls to test runner. Again, as you see, TUT 
doesn't restrict user here.

But, the last question is still unanswered: how do we get our test results? 
The answer lies inside tut::callback interface. User shall create its subclass, 
and write up to three simple methods. He also can omit any method since they 
have default no-op implementation. Each corresponding method is called in the 
following cases:

    * a new test run started;
    * test finished;
    * test run finished.

Here is a minimal implementation:

class visualizator : public tut::callback
{
public:
  void run_started(){ }

  void test_completed(const tut::test_result& tr)
  {
      // ... show test result here ...
  }

  void run_completed(){ }
};        

The most important is the test_completed() method; its parameter has type 
test_result, and contains everything about the finished test, from its group 
name and number to the exception message, if any. Member result is an enum 
that contains status of the test: ok, fail or ex. Take a look at the 
examples/basic/main.cpp for more complete visualizator.

Visualizator should be passed to the test_runner before run. Knowing that, 
we are ready to write the final version of our main module:

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

namespace tut
{
  test_runner_singleton runner;
}

class callback : public tut::callback
{
public:
  void run_started(){ std::cout << "\nbegin"; }

  void test_completed(const tut::test_result& tr)
  {
    std::cout << tr.test_pos << "=" << tr.result << std::flush;
  }

  void run_completed(){ std::cout << "\nend"; }
};

int main()
{
  callback clbk;
  runner.get().set_callback(&clbk);

  // run all tests in all groups
  runner.get().run_tests();
  return 0;
}
        
That's it. You are now ready to link and run our test application. Do it as often as possible; 
once a day is a definite must. I hope, TUT will help you to make your application more 
robust and relieve your testing pain. Feel free to send your questions, suggestions and 
critical opinions to me; I'll do my best to address them asap.