### 6.5 C++ unit testing API ¶

The C++ API is also provided in the `dejagnu.h` header file. This header provides a self-contained implementation. For convenience, the `totals()` method outputs summary totals to be used at the end of unit test program. DejaGnu does not depend on this summary and counts the test results independently.

All of the methods that take a `msg` parameter use a STL string as the message to be displayed. There currently is no support for formatted output in the C++ API; build the desired string before passing it to these functions.

Note that the C API is also available in C++ unit test programs; using both will cause confusion because each `TestState` object carries its own set of summary counters, while the C API has an independent global set of summary counters.

The `TestState` class supports the following instance methods:

- `pass` prints a message for a successful test completion.

  > `TestState::pass(msg);`

- `fail` prints a message for an unsuccessful test completion.

  > `TestState::fail(msg);`

- `xfail` prints a message for an expected unsuccessful test completion.

  > `TestState::xfail(msg);`

- `xpass` prints a message for an unexpected successful test completion.

  > `TestState::xpass(msg);`

- `untested` prints a placeholder message for a test case that is not yet implemented or that could not be run for some reason.

  > `TestState::untested(msg);`

- `unresolved` prints a message for a test case that was run, but did not produce a clear result. These output states require a human to look over the results to determine what happened.

  > `TestState::unresolved(msg);`

- `totals` prints out the total counts of all of the test results as a convenience when running the unit test program directly. DejaGnu does not use this information and instead counts the results independently.

  In the C++ API, this method is automatically called when a `TestState` instance is destroyed.

  > `TestState::totals();`