Cutter: C Unit Testing Tool (v. 0.55)

What is Cutter?
Cutter accepts a simple set of test parameters and generates a complete C program that runs those tests and reports the results. Cutter also provide services that make running the tests more efficient.
What do the input and output for Cutter look like?

A simple Cutter file specifying two tests for one function looks like this:

; sample Cutter file

.start

.code

#include "project-specific-header.h"

.function int convert_to_units( char* str );

.test

.expect ERR

.params NULL

.test

.expect 720000

.params "10in"

.stop

It generates this C code:

* Unit-test harness

* Generated by Cutter, the C Unit Test Framework, v. 0.50

* on Tue Dec 06 21:59:41 2005

* DO NOT MODIFY. To change this file, edit simpleSample.cut

* and rerun Cutter.

* Cutter is available at no cost from http://cutter.pz.org

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

static int total_tests = 2;

static int testNumber;

static int failedTests;

#include "project-specific-header.h"

extern int convert_to_units( char* str );

int main( int argc, char *argv[] )

{

printf( " test %04u: %s: ", ++testNumber,
"int convert_to_units( char* str ): " );

if (( convert_to_units ( NULL )) == ERR )

printf( "passed\n" );

else

{

printf( "FAILED\n" );

failedTests++;

}

printf( " test %04u: %s: ", ++testNumber,
"int convert_to_units( char* str ): " );

if (( convert_to_units ( "10in" )) == 720000 )

printf( "passed\n" );

else

{

printf( "FAILED\n" );

failedTests++;

}

return( failedTests );

}

So, what is the benefit?

With Cutter, it’s easy to quickly generate unit tests for functions: simply specify the expected return value and the input parameters to the function, and Cutter generates all the test code (in C) and reports the results of the tests.
What is the syntax for the Cutter files?

Cutter is driven by commands. Each command starts with a period. Commands must be the first item in a line of text.

Cutter scripts begin with the .start command (everything before that is ignored).

Thereafter, the .global command identifies code for global items, such as #included files, function declarations, and globals data items that are needed to execute the test functions. (See previous example). Everything that follows the.code command up to the next Cutter command is copied as is into the output file, so make sure it’s all valid C code.

Then come the tests. You start by specifying the function to test, then the tests to run on it. To specify the function, use a .function record. This record contains a complete function signature, including return type and types for passed parameters. For example:

char *functionName( int j, void* pv )

.function records are followed by one or more tests. Each test consists of at least three records. The .test record, which simply indicates the start of a new test, the .expect record which gives the expected return value. This value can be stated as an exact value or a relational one. For example >= 0 is a valid .expect record.

Finally, there comes the .params record. Whatever is specified in the .params record is passed as parameters to the tested function when it’s called.

Because you are likely to test functions at times by passing them invalid parameters, you need to be able to silence stderr and stdout, so that you don’t get a screenful of error messages. Cutter automatically redirects stdout and stderr, so their output is not visible. If you want to see their output, you can tell Cutter to redirect them to disk. To do this, use the .rederr command (redirect stderr) followed by the name of the file. If the filename contains space, put in double quotation marks. To redirect stdout, use the .redout command in similar fashion.

The following example is a test for function cutter_main. Prior to running the test, stderr is redirected to a file called stderr on disk. The first test passes parameters of 1 and NULL to the function and expects a return of EXIT_FAILURE. If this result is returned, the test completes successfully:

.function int cutter_main( int argc, const char *argv[] )

.rederr “stderr on disk”

.test

.expect EXIT_FAILURE

.params 1, NULL

Cutter scripts end with the .stop command. Anything after this command is ignored.

What about comments?

Comments in Cutter begin with a semicolon (;), which must be the first character on the line. Comments are line-oriented, so every line in a comment must begin with a semicolon.

Where can I get more information on running Cutter?

Download the documentation at http://cutter.pz.org/cutter-0.55-manual.pdf
How do I run Cutter?

cutter infile [-o outfile] -v
where infile is the set of tests (generally a file with the .cut extension) and an optional output file. If outfile is not specified, output is to stdout. The –v switch turns on the verbal option, which provides additional data regarding the compilation to the screen.
How do I install Cutter?

Uncompress the download and copy the executable to the directory of your choice and run it there. Cutter makes no changes to registries or system settings of any kind. To uninstall Cutter, simply delete the executable. It’s really that simple.
How do I uninstall Cutter?

Simply delete the Cutter executable. That’s all.
So, what’s next for Cutter?

Cutter is actively under development. We will expand the syntax as user needs dictate. A graphical front end that captures the output from the tests and presents in a xUnit like GUI is under active consideration, as is the ability to export error reports to bug-tracking systems such as BugZilla and Atlassian JIRA.
How is Cutter licensed?

Cutter is free and open-source. It uses the Apache License 2.0, which is one of the most permissive licenses available. Enjoy the tool and, please, give us feedback on how we can improve the product.
How do I get a hold of Cutter or the developers behind Cutter?

The latest versions of Cutter are available at http://cutter.pz.org. Team members can be contacted at cutter [ at ] pz [dot] org.