CUT is designed to aid the C(-like) programmer in implementing unit or programmer tests, primarily to facilitate test-driven (and related) development practices.
cutgen looks through the set of source files file1..filen, seeking idiomatic function definitions to discover unit test functions, bring-up functions, set-up functions, and their associated take-down functions. With this information, cutgen builds a test runner, which when compiled will invoke the unit tests specified in the input files.
The -o/--output option, if specified, causes the test runner to be written to named file. Without this option, cutgen defaults to writing the test runner to stdout.
The --license, -h/--help, and --version options results in the display of the relavent information; no further action is taken, regardless of the presence of other options.
NOTE: compiling the generated test runner requires GNU getopt for command-line processing. If you're using Windows, you'll probably want to look into the XGetOpt package. As I haven't used Windows on any computer since 1995, I cannot tell you how well this package works. However, as I'm not doing anything abnormal with it, the probability of success is high.
Once the test runner has been compiled, it may be invoked without any parameters. This will result in the unit tests being executed, typically in the order they were found by cutgen. If all unit tests executed correctly, then no output is generated.
To see a log of the assertions executed, pass the --verbose flag. The long flag is required; no short flag equivalent exists.
You'll notice each assertion has a unique integer associated with it. Sometimes, stopping the unit test execution at a specific assertion has proven useful. Use the --break-at long option to indicate which assertion to "break" at. Use --verbose to find the number of the assertion you'd like to stop at.
Previous versions of CUT utilized a system of printing a dot for each assertion it executed. This significantly complexified CUT's output of diagnostics, while concurrently rendering integration into IDEs and similar tools effectively impossible. Starting with version 2.7, CUT no longer renders any output at all, unless a diagnostic message demands it.
Diagnostic messages follow a prescribed format:
The filename and line number indicates the source file, and the line within said file, containing the assertion.
The assertion number assigns a unique integer identifier to each assertion encountered by the test runner. This value may be used to set a breakpoint.
The assertion expression represents the assertion's boolean expression. This field exists as a convenience for the programmer, preventing the programmer from having to edit the unit test source to find out what went wrong in about 50% of the cases.
The kind of diagnostic follows; it will be one of three possibilities: log (for --verbose output), break for a breakpoint hit, or error for a unit test failure. Strictly speaking, this field exists for the benefit of some versions of make, which colorize their outputs depending on the presence of certain keywords, error usually resulting in a distinctively highlighted line. This helps to track bugs down when pouring through voluminous amounts of recursive make output.
Each assertion bundles with it a programmer-defined message which is output as the final field. Considering the wealth of information present in other fields, however, good practice frowns on using this facility unless positively necessary.
CUT was primarily written by myself and by Billy Tanksley, starting life as distinct, and even competing, CUT 1.0 and test-assert packages, respectively. When it was finally decided to combine both packages into a single tool, CUT 2.0 was released, and found to be vastly more useful than either of us ever expected.
In 2004, Sergei Gnezdov wrote a tutorial based on CUT 2.3, which is still applicable to the CUT 2.4 version. You will need Adobe Acrobat reader to read the file, as it was written in LaTeX. The tutorial and its source files are also included in the source distribution. Sergei also contributed CUT to the BSD ports collection!
Only source distributions of CUT may be downloaded here.
The Mercurial repository exists at the URL below.
Contributors to the code are encouraged to update corresponding web pages as well, to ensure the online documentation matches the latest CUT developments.
Once acquired, simply execute the following (you'll need GNU Make version 3.80 or later for the non-recursive make system to work):
Make sure to update your path settings as appropriate.
If you, like me, use GoboLinux, you can execute the following: