cipra: cipra::fixture Class Reference

| cipra 1.2.1 A C++11 Unit Testing Framework based on Test::More

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Members

All Classes Namespaces Functions Variables Typedefs Pages
Classes | Public Member Functions | Protected Member Functions | List of all members
cipra::fixture Class Reference

The base class for any test fixtures. More...

`#include <tests.hpp>`

## Public Member Functions
int | run ()
| Run this test fixture and produce output from the user-defined `test()` method. More...

## Protected Member Functions
| fixture ()
| Construct a new test fixture with no plan. More...
| fixture (const fixture &)
| Construct a new test fixture from an existing one. More...
void | plan (int total)
| Sets the number of tests you plan to have run by the end of this fixture. More...
void | plan (skip_all_t, std::string reason=std::string(""))
| Tells the fixture to skip all test cases. More...
Diagnostic output
Prints some string to your test output. These methods must be used, because the normal output to the nonrmal C++ iostreams will be intercepted during the course of the unit test. The API is modelled on that of Perl's `Test::More` module. For a more extensible API, use the iostream.
void | diag (std::string message)
| Print a diagnostic message to the test output. More...
void | note (std::string message)
| Print out a non-diagnostic note to the test output. More...
template<typename T >
void | explain (T object)
| Pretty-print an object to the test output using the object's `operator<<()`. More...
Test Cases
Call these functions to perform single test cases in your unit test. Each of these functions will output to the test output whether the succeed or fail. Test cases that run code take some input that has an `operator()`. This can include function pointers, functor objects, or C++11 lambdas. This allows a form of "lazy execution", in which the test case can run code before and after running your inputted code.
template<typename funcT >
void | ok (funcT expr, std::string name=std::string(""))
| Assert that some expression returns a value that when converted to a `bool` will be `true`. More...
template<typename T , typename U >
void | is (T got, U expected, std::string name=std::string(""))
| Assert that some value is the same as another value. More...
template<typename T , typename U >
void | isnt (T got, U expected, std::string name=std::string(""))
| Assert that some value is not the same as another value. More...
template<typename funcT >
void | throws (funcT expr, std::string name=std::string(""))
| Assert that some expression throws an exception of any type. More...
template<typename exceptionT , typename funcT >
void | throws (funcT expr, std::string name=std::string(""))
| Assert that some expression throws an exception of a specified type. More...
template<typename funcT >
void | nothrows (funcT expr, std::string name=std::string(""))
| Assert that some expression does not throw an exception of any type. More...
template<typename exceptionT , typename funcT >
void | nothrows (funcT expr, std::string name=std::string(""))
| Assert that some expression does not throw an exception of a specified type. More...
template<typename T , typename... argsT>
T | new_ok (argsT &&...args)
| Assert that the constructor of an object can be constructed without throwing an exception of any type. More...
void | pass (std::string name=std::string(""))
| Say that some test has passed. More...
void | fail (std::string name=std::string(""))
| Say that some test has failed. More...

## Static Protected Attributes
Constants
A few value-less constants that can be passed to certain functions in the test fixture. These constants are only used in overload resolution. The names of these constants are taken from `Test::More`.
static const skip_all_t | skip_all
| The constant of the type to skip all test cases.
static const no_plan_t | no_plan
| The constant of the type to have no plan in the test.

## Detailed Description

The base class for any test fixtures.

To use cipra, you should derive from this class.

Version
  1.0

Author
  Patrick M. Niedzielski

Date
  2012-09-07

Since
  1.0

Note
  For compilers that support the Itanium ABI and have the associated functions in the `abi::` namespace, define the preprocessor token `CIPRA_CXA_ABI` before the `cipra.h` header is included to take advantage of these functions to provide better diagnostics of exceptions that are thrown by test expressions. A conforming compiler should provide `abi::__cxa_current_exception_type()` and `abi::__cxa_demangle` in the header file `cxxabi.h`. This flag does not affect test behavior outside of exception diagnostics.

Todo:

  Add a `subtest()` method.

  Add some equivalent of `TODO` and `SKIP` blocks.

  Add a `BAIL_OUT()` method.

## Constructor & Destructor Documentation

cipra::fixture::fixture | ( |  | ) |
| inlineprotected

Construct a new test fixture with no plan.

A plan can be specified with the plan() method.

Author
  Patrick M. Niedzielski

Date
  2012-09-02

Since
  1.0

cipra::fixture::fixture | ( | const fixture & |  | ) |
| inlineprotected

Construct a new test fixture from an existing one.

Author
  Patrick M. Niedzielski

Date
  2012-09-02

Since
  1.0

## Member Function Documentation

void cipra::fixture::diag | ( | std::string | message | ) |
| protected

Print a diagnostic message to the test output.

Author
  Patrick M. Niedzielski

Date
  2012-09-26

Since
  1.0

Parameters

  [in] | message | A string to print to the test output.

template<typename T >

void cipra::fixture::explain | ( | T | object | ) |
| protected

Pretty-print an object to the test output using the object's `operator<<()`.

Author
  Patick M. Niedzielski

Date
  2012-09-26

Since
  1.0

Parameters

  [in] | object | An object to print.

Todo:
  The `operator<<()` could have newlines in it. These should be escaped.

void cipra::fixture::fail | ( | std::string | name = `std::string("")` | ) |
| protected

Say that some test has failed.

Author
  Patrick M. Niedzielski

Date
  2012-11-15

Since
  1.0

Parameters

  [in] | name | A user-readable description of this test assertion.

Note
  This is a synonym for ok(false, name).

template<typename T , typename U >

void cipra::fixture::is | ( | T | got,
|  | U | expected,
|  | std::string | name = `std::string("")`
| ) |  |
| protected

Assert that some value is the same as another value.

Either the types `T` and `U` need to be implicitly convertible or there must be defined an `operator==(T,U)` function or method.

Author
  Patrick M. Niedzielski

Date
  2012-09-28

Since
  1.0

Parameters

  [in] | got | A value we got.
  [in] | expected | A value we are expecting.
  [in] | name | A user-readable description of this test assertion.

Note
  An `operator<<` function for stream output must be defined for both `T` and `U` to output the objects in the case of failure.

Warning
  This method does not capture any exceptions that may be thrown in determining the values of `got` and `expected`.

template<typename T , typename U >

void cipra::fixture::isnt | ( | T | got,
|  | U | expected,
|  | std::string | name = `std::string("")`
| ) |  |
| protected

Assert that some value is not the same as another value.

Either the types `T` and `U` need to be implicitly convertible or there must be defined an `operator!=(T,U)` function or method.

Author
  Patrick M. Niedzielski

Date
  2012-09-28

Since
  1.0

Parameters

  [in] | got | A value we got.
  [in] | expected | A value we are expecting not to get.
  [in] | name | A user-readable description of this test assertion.

Note
  An `operator<<` function for stream output must be defined for `T`.

Warning
  This method does not capture any exceptions that may be thrown in determining the values of `got` and `expected`.

template<typename T , typename... argsT>

T cipra::fixture::new_ok | ( | argsT &&... | args | ) |
| protected

Assert that the constructor of an object can be constructed without throwing an exception of any type.

Author
  Patrick M. Niedzielski

Date
  2012-11-15

Since
  1.0

Template Parameters

  T | The type of object to attempt creating.

Parameters

  [in] | args | The arguments to pass to the constructor of type `T`. These arguments will be perfectly forwarded to the constructor.

Returns
  An object of type `T`.

Note
  If the type `T` is NonCopyable, it must be Movable.

Warning
  If the object cannot be created, the rest of the subtest (or test, if subtests are not used) will be skipped, to prevent operations on the incorrectly constructed object.

Todo:
  Implement the aborting of subtests/tests.

void cipra::fixture::note | ( | std::string | message | ) |
| protected

Print out a non-diagnostic note to the test output.

Author
  Patrick M. Niedzielski

Date
  2012-09-26

Since
  1.0

Parameters

  [in] | message | A string to print to the test output.

template<typename funcT >

void cipra::fixture::nothrows | ( | funcT | expr,
|  | std::string | name = `std::string("")`
| ) |  |
| protected

Assert that some expression does not throw an exception of any type.

Author
  Patrick M. Niedzielski

Date
  2012-09-07

Since
  1.0

Parameters

  [in] | expr | Some object providing the `operator()`. This expression will be your assertion expression.
  [in] | name | A user-readable description of this test assertion.

Note
  `expr` can't simply be a boolean value indicating true or false. In order to catch exceptions thrown by the expression, we need to run the expression inside a `try`-`catch` block. If `expr` were a boolean value, the expression would already have been evaluated and the exception already thrown by the time the function would begin.

template<typename exceptionT , typename funcT >

void cipra::fixture::nothrows | ( | funcT | expr,
|  | std::string | name = `std::string("")`
| ) |  |
| protected

Assert that some expression does not throw an exception of a specified type.

Author
  Patrick M. Niedzielski

Date
  2012-09-07

Since
  1.0

Template Parameters

  exceptionT | The type of the exception that running `expr` should not cause.

Parameters

  [in] | expr | Some object providing the `operator()`. This expression will be your assertion expression.
  [in] | name | A user-readable description of this test assertion.

Note
  `expr` can't simply be a boolean value indicating true or false. In order to catch exceptions thrown by the expression, we need to run the expression inside a `try`-`catch` block. If `expr` were a boolean value, the expression would already have been evaluated and the exception already thrown by the time the function would begin.

template<typename funcT >

void cipra::fixture::ok | ( | funcT | expr,
|  | std::string | name = `std::string("")`
| ) |  |
| protected

Assert that some expression returns a value that when converted to a `bool` will be `true`.

Author
  Patrick M. Niedzielski

Date
  2012-09-07

Since
  1.0

Parameters

  [in] | expr | Some object providing the `operator()` that will return a value convertable to `bool`. This expression will be your assertion expression.
  [in] | name | A user-readable description of this test assertion.

Note
  `expr` can't simply be a boolean value indicating true or false. In order to catch exceptions thrown by the expression, we need to run the expression inside a `try`-`catch` block. If `expr` were a boolean value, the expression would already have been evaluated and the exception already thrown by the time the function would begin.

void cipra::fixture::pass | ( | std::string | name = `std::string("")` | ) |
| protected

Say that some test has passed.

Author
  Patrick M. Niedzielski

Date
  2012-11-15

Since
  1.0

Parameters

  [in] | name | A user-readable description of this test assertion.

Note
  This is a synonym for ok(true, name).

void cipra::fixture::plan | ( | int | total | ) |
| inlineprotected

Sets the number of tests you plan to have run by the end of this fixture.

This is used as a checksum after all tests are run.

Author
  Patrick M. Niedzielski

Date
  2012-09-08

Since
  1.0

Parameters

  [in] | total | The number of tests you want to run.

void cipra::fixture::plan | ( | skip_all_t | ,
|  | std::string | reason = `std::string("")`
| ) |  |
| inlineprotected

Tells the fixture to skip all test cases.

Author
  Patrick M. Niedzielski

Date
  2012-10-02

Since
  1.0

Parameters

  [in] | reason | Why this test fixture is being skipped.

int cipra::fixture::run | ( |  | ) |
| inline

Run this test fixture and produce output from the user-defined `test()` method.

Returns a value suitable for the return value of the program's `main()` function.

Author
  Patrick M. Niedzielski

Date
  2012-09-02

Since
  1.0

Returns
  The program's return value to the operating system.

Return values

  0 | Successful test execution.

Note
  Calling this function will implicitly call your `test()` method. It runs additional initialization and cleanup code for your test fixture.

template<typename funcT >

void cipra::fixture::throws | ( | funcT | expr,
|  | std::string | name = `std::string("")`
| ) |  |
| protected

Assert that some expression throws an exception of any type.

Author
  Patrick M. Niedzielski

Date
  2012-09-07

Since
  1.0

Parameters

  [in] | expr | Some object providing the `operator()`. This expression will be your assertion expression.
  [in] | name | A user-readable description of this test assertion.

Note
  `expr` can't simply be a boolean value indicating true or false. In order to catch exceptions thrown by the expression, we need to run the expression inside a `try`-`catch` block. If `expr` were a boolean value, the expression would already have been evaluated and the exception already thrown by the time the function would begin.

template<typename exceptionT , typename funcT >

void cipra::fixture::throws | ( | funcT | expr,
|  | std::string | name = `std::string("")`
| ) |  |
| protected

Assert that some expression throws an exception of a specified type.

Author
  Patrick M. Niedzielski

Date
  2012-09-07

Since
  1.0

Template Parameters

  exceptionT | The type of the exception that running `expr` should cause.

Parameters

  [in] | expr | Some object providing the `operator()`. This expression will be your assertion expression.
  [in] | name | A user-readable description of this test assertion.

Note
  `expr` can't simply be a boolean value indicating true or false. In order to catch exceptions thrown by the expression, we need to run the expression inside a `try`-`catch` block. If `expr` were a boolean value, the expression would already have been evaluated and the exception already thrown by the time the function would begin.