home
 
news
Free Software
 
mimetic
cutee
eeprog
recover
lcd
Commercial Software
 
obsolete
About me
 
resume
contact
 

 

  Intro   Download   Features   Usage and examples   Macro list   Misc. info   Command line options
Intro

cutee is the acronym of C++ Unit Testing Easy Environment and it's (guess what?) a tool to handle unit testing.

Unit testing is not very fun and I think that current unit testing tools are more difficult than what they are supposed to be. I mean that I don't want to write a 20-lines C++ file and modify a few more files just to run a single line of test-function. What I wanted was a simple, very simple way to create tests that would compile and run with a single command. Nothing more, nothing less.

I first tried CxxTest and it is good and easy but it generates a single big file with all the required code to run all tests and this didn't scale well. The main runtests.cc file run bigger and bigger and compiling time quickly went up. Also I didn't want to add a Perl interpreter to the list of my projects requirements just because CxxTest need Perl to parse files.

So here you'll find my testing framework. It's easy to use, small and portable (it has been currently tested on Linux, FreeBSD and NetBSD with gcc 3.x.x and 2.9.x).

The only requirement is a C++ compiler. I'm reasonably sure you have it. :)

Download

Latest release is 0.4.2

You can download it here: cutee-0.4.2.tar.gz

Features

  • Straightforward
    With cutee all you have to do except writing the test class is adding the file name of your new test class to the Makefile. Just the file name, nothing more. Everything else is handled automagically.
  • Minimize compilations
    Using cutee every test class will produce an object file so when you modify a test file only the modified test will be recompiled not the whole test suite.
  • Automatically generates runners
    Runners (classes that run tests) will be automatically generated.
  • Automatically updates makefiles and file dependencies
    You'll not need to update your Makefiles, cutee will generate (and automatically update) a file autocutee.mk that will be included into your Makefile and that will handle all required tasks to run your tests.
  • Automatically generates main test application
    The mail test application, also, will be generated by cutee
  • Supports plain Makefiles and Autotools
    Either you are using Autotools to build your project or a simple Makefile cutee will be easily integrated into your environment.

Usage and examples

cutee tries to handle all repetitive boring tasks needed to create and run test procedures like updating Makefiles, adding tests to the list of tests to run, etc.

I'll try to explain how to use cutee with some examples.

First test

First download and unpack cutee-x.y.z.tar.gz in a temporary directory.
Now copy Makefile.template to Makefile. This should be the content of your directory.
# ls
Makefile              Makefile.template  cutee.cc  t.selftest.h
Makefile.am.template  autocutee.mk       cutee.h
	

Now run make and then ./runtest; this'll be the result:

# ./runtest
..

    ======================================
              Tests Statistics
    --------------------------------------
                Functions       Checks
      Success          2             6
       Failed          0             0
    --------------------------------------
        Total          2             6
    ======================================    
	

What you'll see is the result of cutee self test. It's not really a complete test but it's enough to see if file dependencies and compilations are handled correctly.

Second test, a new test function

Now let's try to add a test that will fail.

Open t.selftest.h and add the following block between the two existing functions:

{
        TEST_ASSERT( 1 == 0 );
}
	

Now, again, run make and ./runtest; this'll be the result:

# ./runtest
..
 [t.selftest.h:16] cutee_test_self::my_test(): 1 == 0 assertion failed
.

    ======================================
              Tests Statistics
    --------------------------------------
                Functions       Checks
      Success          2             6
       Failed          1             1
    --------------------------------------
        Total          3             7
    ======================================
	

Third test, a new test class

Here we'll add a new test class to our test list.

Create t.third.h (note that filename is not meaningful, you could use any name you want) and insert the following code:

#define _T_THIRD_H__
#include "cutee.h"

struct TEST_CLASS( third_test_class )
{
        void TEST_FUNCTION( third_test_first_func )
        {
                TEST_ASSERT( 1 );
                TEST_ASSERT( 0 );
        }
};

#endif
	

Open the file called Makefile and add t.third.h to the test_files variable:

test_files=t.selftest.h t.third.h

all: autocutee.mk runtest

cutee: cutee.cc cutee.h
        $(CXX) $(CXXFLAGS) -o cutee cutee.cc

autocutee.mk: cutee Makefile $(test_files)
        ./cutee -p -o autocutee.mk $(test_files)
        make runtest

include autocutee.mk
	

Don't worry about other lines, you'll never need to modify them.

Again, run make and ./runtest:

# ./runtest
.
 [t.third.h:10] third_test_class::third_test_first_func(): 0 assertion failed
..
 [t.selftest.h:16] cutee_test_self::my_test(): 1 == 0 assertion failed
.

    ======================================
              Tests Statistics
    --------------------------------------
                Functions       Checks
      Success          2             7
       Failed          2             2
    --------------------------------------
        Total          4             9
    ======================================
	

Quick reference

  • To add a new test class create a new header file, include "cutee.h" and use the macro TEST_CLASS to define the new class:

    #define _T_DUMMY_H_
    #include "cutee.h"
    
    struct TEST_CLASS( class_name )
    {
    };
    
    #endif
    	

    Note that "_T_DUMMY_H_" must be different for every file (that's C++, you should know it) so be careful while coping from an existing test file if you want everything to work properly.

  • Use the TEST_FUNCTION macro to add a new test function to a test class:

    {
            // test code here
    }
    	
  • Modify the test_files variable into Makefile adding the name of the file of every new test file:

    test_files=new_test_file_name
    	

Macro list

These are all defined macros:
TEST_CLASS( class_name ) Used to define a new test class
TEST_FUNCTION( function_name ) Used to define a new test function
 
Simple macros:
 
TEST_ASSERT( expr ) Fails if !expr
TEST_ASSERT_EQUALS( a, b ) Fails if a and b are not equals
TEST_ASSERT_DIFFERS( a, b ) Fails if a and b are not different
 
_P macros (print the tested value(s) on failure):
 
TEST_ASSERT_P( expr ) Fails if !expr. Print expr on failure.
TEST_ASSERT_EQUALS_P( a, b ) Fails if a and b are not equals. Print a and b on failure.
TEST_ASSERT_DIFFERS_P( a, b ) Fails if a and b are not different. Print a and b on failure.
 
_M macros (print a message on failure):
 
TEST_ASSERT_M( expr, msg ) Fails if !expr. Print msg on failure.
TEST_ASSERT_EQUALS_M( a, b, msg ) Fails if a and b are not equals. Print msg on failure.
TEST_ASSERT_DIFFERS_M( a, b, msg ) Fails if a and b are not different. Print msg on failure.
 
_PM macros (print a message and the tested value(s) on failure):
 
TEST_ASSERT_PM( expr, msg ) Fails if !expr. Print expr and msg on failure.
TEST_ASSERT_EQUALS_PM( a, b, msg ) Fails if a and b are not equals. Print a, b and msg on failure.
TEST_ASSERT_DIFFERS_PM( a, b, msg ) Fails if a and b are not different. Print a, b and msg on failure.

Misc. info

  • To use cutee with autotools you have to modify your Makefile.am to include the following lines:

    test_files= # your test files here
    
    noinst_PROGRAMS=cutee
    
    cutee_SOURCES=cutee.cc cutee.h
    
    autocutee.mk: cutee Makefile.am $(test_files)
            $(CUTEE) -k -o autocutee.mk $(test_files)
    
    include autocutee.mk
    	

    Note that cutee is called with the "-k" parameter instead of the "-p" we've seen before.

  • If you don't want to inline test code into header files you can split a test class in a .h file and .cc (or .cap, .cxx, etc.) just like every C++ class.
    For example:

    test1.h
    #define _T_SPLIT_H_
    #include "cutee.h"
    
    struct TEST_CLASS( split_test )
    {
            void TEST_FUNCTION( one );
            void TEST_FUNCTION( two );
    private:
            int i;
    };
    
    #endif
    	

    test1.cc
    
    void split_test::one()
    {
            TEST_ASSERT_EQUALS_M(++i, 1, "i: " << i);
            TEST_ASSERT_EQUALS_M(++i, 1, "i: " << i);
    }
    
    void split_test::two()
    {
            TEST_ASSERT(i > 0);
    }
    	

    You must also include the class body filename (t.split.cc) in the test_files line of the Makefile:

    Makefile
    test_files=t.split.h t.split.cc
    
    all: autocutee.mk runtest
    
    cutee: cutee.cc cutee.h
            $(CXX) $(CXXFLAGS) -o cutee cutee.cc
    
    autocutee.mk: cutee Makefile $(test_files)
            ./cutee -p -o autocutee.mk $(test_files)
            make runtest
    
    include autocutee.mk
    	

Command line options

# cutee
(108) cutee, C++ Unit Testing Easy Environment, Ver. 0.3.9
Copyright (c) 2003 by Stefano Barbato - All rights reserved.
cutee [options]... testfile(s)
 -m, --main             generates runtest source code
 -o, --output=filename  specify the output filename
 -p, --makefile         generates autocutee.mk to include in your Makefile
 -k, --automakefile     generates autocutee.mk to include in your Makefile.am
	
 
Google
Web codesink.org

Sponsored links:


All contents Copyright (c) 2003-2013 by Stefano Barbato. All Rights Reserved. Site made with vim. Syntax highlighter source-highlight