GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
EXERCISIX(3) FreeBSD Library Functions Manual (prm) EXERCISIX(3)

exercisix
lighweight unit-test framework for C++

Exercisix is a unit-test framework for C++, designed for test-aided development. It's main features are:

  • test discovery
  • textual description as primary test identifier
  • terse test tools syntax
  • informative error messages
  • emacs-friendly error message format
  • easy build: framework is source-based, no linking is required

Each test suite resides in its own translation unit, which is compiled into a separate executable file. Framework provides its own main() function. A test suite file must include header <exercisix.hh> and may have one or more test cases.

A test case is defined as a word TEST, followed by parenthesis, containing a text string literal within them. Then goes code block in curly braces, which contains test case body. A test case body is a sequence of statements, similar to function body. A test case body should contain an expectation statement, which uses one of EXPECT_* test tools, described below.

A minial test suite is specified like this:

#include
 <exercisix.hh>

TEST( "one should be equal to one" )
{
  EXPECT( 1, ==, 1 );
}

Each test case is a function with unique name testN(), where N is a number of the line the macro TEST were called. See section 'COMMAND-LINE OPTIONS' below for details of how to match test case with the name of it's function.

Test cases are executed in sequence, in the same order as they are defined in the source file. If during execution of a test case a test tool reports a failure, then test suite execution stops after the test case finishes and error message is printed. If no failures were reported, then the name of the source file containing test suite definition is printed, followed by the word “SUCCESS”.

Four test tools are provided: EXPECT(), EXPECT_NO_EXCEPTIONS(), EXPECT_EXCEPTION(), and EXERCISIX_FAIL.

The first, EXPECT() have the following form:

EXPECT( expr1, op, expr2 );

Where expr1 and expr2 are any valid C++ expressions. The op is any C++ operator, defined for types which expressions expr1 and expr2 evaluate to. The tool evaluates the expression

(expr1) op (expr2)

, casts it to bool, then registers failure if result value is false and does nothing if result value is true.

The second test tool, EXPECT_NO_EXCEPTIONS has the following form:

EXPECT_NO_EXCEPTIONS( expr );

The expr is any valid C++ expression. The tool evaluates the expression expr, then does nothing if expression evaluates without throwing an exception and registres failure if an exception was thrown during evaluation of the expression expr.

The third test tool, EXPECT_EXCEPTION has the following form:

EXPECT_EXCEPTION( expr, type );

Where expr is any valid C++ expression and type is any valid C++ type. The tool evalues the expression expr, then does nothing if an exception of type type was thrown during evaluation of expression expr, registers a failure if thrown expression was of a different type or no exceptions were thrown at all.

The last EXERCISIX_FAIL test tool is provided for creating custom complex assertions. It is used as a complete statement:

EXERCISIX_FAIL;

If the line on which this tool is placed is reached, framework registers generic failure.

If during execution of a test case a failure is reported, the framework prints source file name, line number (where a test tool that reported a failure was used), and failed test description. After that comes test-tool specific information as described below:

The EXPECT() test tool prints operator, texts of both expressions and their values. If expression value is not printable, framework prints expression text only and explicitly states that value can not be printed. The framework can print any value that may be used in operator<< for std::ostream.

The EXPECT_NO_EXCEPTIONS() test tool prints actual type of exception that was thrown. If type of exception can not be determined, the framework explicitly states that exception of unknown type was thrown.

The EXPECT_EXCEPTION() test tool prints actual type of exception that was thrown. If type of exception can not be determined, the framework explicitly states that exception of unknown type was thrown. The expected type of exception is also printed.

If during execution of a test method an exception is thrown from outside one of EXPECT_* test tools, process is stopped and error message “unexpected exception” containing the type of exception (if it can be determined) is printed. The source file name and a line, which contains TEST macro for the test method are also printed.

The framework will detect the type of any exception which is derived from std::exception.

#include
 <exercisix.hh>
#include
 <vector>
#include
 <stdexcept>

using std::vector;

TEST( "one equals to one" )
{
  EXPECT( 1, ==, 1 );
}

TEST( "two is less than three" )
{
  EXPECT( 2, <, 3 );
}

TEST( "at() completes successfully if index is within bounds" )
{
  int source[] = { 1, 2, 3 };
  vector <int> v(source, source + 3);

  EXPECT_NO_EXCEPTIONS( v.at(1) );
}

TEST( "at() throws exception of type 'std::out_of_range "
      "if index is out of bounds" )
{
  int source[] = { 1, 2, 3 };
  vector <int> v(source, source + 3);

  EXPECT_EXCEPTION( v.at(7), std::out_of_range);
}

void throw_int()
{
  throw 11;
}

TEST( "if function throws integer, it must be greater than 7" )
{
  try {
    throw_int();
  }
  catch(int e)
  {
    if (e < 7)
      EXERCISIX_FAIL;
  }
}

The framework does not provide specifically any tools for performing SETUP or TEARDOWN operations before and after execution of a test method. Usual C++ constructs for declaring local variables inside test method body may be used instead. Local variables will be initialized as control reaches their definition and destroyed at the end of the block, thus eliminating the need for specific SETUP or TEARDOWN tools.

The executables produced using the framework accept command-line options. The syntax of the command-line is as follows:

test-suite-executable [-l | --list] [-v | --verbose] [--version]

The available options are:

--list
Do not execute test cases, just list their descritpions instead. This produces a list of all test cases in a suite, useful for documentation. For each test case it's ordinal number, test function name and test description are printed. This option can also be used to match test cases with names of functions that represent these test cases. It's helpful for debugging, since framework obscures the actual structure of test code. This lets you set a breakpoint on the test case.
--verbose
Print each test case description before actually executing it. If test case reports no failures, the word “SUCCESS” is printed at the same line after test case is finished.
Print version of the framework. No test cases are executed.

The framework is believed to be compliant with ISO/IEC 14882:2003 .

The “exercisix” framework is distributed under the terms of BSD license.

Copyright (c) 2009, 2011 Alexander Churanov. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the
distribution.

THIS SOFTWARE IS PROVIDED BY ALEXANDER CHURANOV ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ALEXANDER CHURANOV BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

c++(1)

Alexander Churanov ⟨exercisix@alexanderchuranov.com⟩

http://alexanderchuranov.com/software/exercisix/
February 16, 2011

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.