TUT: C++ Unit Test Framework

Documentation

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

- TUT Design
  what's hidden under the hood of tut.h, and why things are such as they are

- TUT Usage Example
  it's better to see once...

- TUT As Is
  complete source of TUT

Distribution

- The TUT License
  almost no restrictions to use

- TUT Downloads
  latest version of TUT as well as other related stuff

Support

- TUT Frequently Asked Questions
  often asked questions and answers for them

- Links
  related projects and concepts

- TUT Author
  who is the author

TUT Frequently Asked Questions

What is TUT?

TUT is a small and portable unit test framework for C++. It's so small that it fits into one header file. It's so portable that it could be used on almost any C++ platform, including Windows, MacOS and unices.

How it's different from C++Unit (boost::test, ...)?

C++Unit, boost::test and other frameworks perform similar tasks.

But there are some issues with most of them:

- they require to build them as a library
- tests depend on preprocessor macros
- they often overloaded with features

TUT, in contrast, is located in a single header file (20K). All you should do is to include it into the test module. No linking at all.

TUT uses C++ template engine to dispatch calls to test methods. Therefore you shouldn't even register methods as tests: template will do it for you automatically. As a result, the test code will be more readable.

And finally, TUT is a minimal software. It only does what it's designed for. It doesn't attempt to integrate with MSDN or to control production processes. It just runs tests.

What compilers are supported?

Most modern compilers are supported. Some outdated compilers are unable to handle templates in TUT, though

Supported:

- GNU GCC 2.95
- GNU GCC 3.x (both under unix and MinGW)
- Borland 5.6 (Borland C++ Builder 6)
- Intel C++ Compiler 6.x
- Intel C++ Compiler 8.1
- Sun Studio 9: C++ 5.6 Compiler
- Microsoft VC7 (Microsoft VS.NET 2003 and later)
- Sun WorkShop 6 update 2 C++ 5.3 (probably, previous versions as well)

Unsupported:

- Borland 5.5.x (Borland C++ Builder 5)
- Microsoft VC6 (including SP5)
- Microsoft VC7 (Microsoft VS.NET 2002)
- C for AIX Compiler, Version 6
- KAI C++ Compiler
- Portland Group Compiler, Version 5.2-4

If you use TUT with any other compiler or environment please let me know.

Some broken compiler/linker/platform combinations require to make methods ensure(), ensure_equals and fail() to be inline, and not in anonymous namespace. Try to change tut.h accordingly if you see "duplicate symbol ensure" or "ensure is not found" during linking stage.

I've taken a look at the selftest code and it looks awful

Self tests are very special beasties, and actually you've seen two(!) TUT frameworks running one under control of another. The case is quite extreme. Regular TUT tests are very simple to read; you'd better look at the online example.

Why don't you provide methods to catch user-code exceptions?

First of all, the user-code exceptions are intercepted inside the test runner, and afterwards user receives them along with the test_result status. For std exceptions, a textual message is included into results. For the others there will be a message that an unknown exception was generated.

I've used ensure_equals() method and compiler refused to build my code complaining that there is ambiguous overload for operator <<.

One or both types you've provided to ensure_equals() have no operator << at all. Since the diagnostic message is built using std::stringstream, compiler needs the operator to format your objects. Either add the operator or use ensure() method (which doesn't tell you the exact values the objects had, just the fact they were not equal).

What about segmentation faults in code being tested? What about deadlocks?

C++ Standard doesn't specify what happens if the code references wrong address. Thus, segmentation fault processing is system and compiler dependent, and shall be handled differently in each system/compiler pair.

If you want TUT to react correctly to tests failures caused by segfaults, you must somehow convert hardware faults into C++ exceptions.

For Win32 TUT uses SEH. You need to specify -DTUT_USE_SEH at build time.

For unixes there is no standard way to convert SIGSEGV into an exception. Consult your platform/compiler documentation for possible ways to do that.

You may also use restartable wrapper defined in optional header tut_restartable.h. It runs the tests the same way as regular runner does, but also logs the progress. If a test crashes the test application, and then test application runs again, the wrapper will load last log record, and continue test execution from position after the crashed test.

Of course, this requires helper script that runs test application until all tests will be runned. The script might be is as simple as

    while true
    do
      ./restartable && exit 0
    done

Directory examples/restartable contains simple restartable test application.

This approach can be extended to support deadlocks in code. The script must be modified to automatically kill test application after specified period of time.