3 Library initialisation

A test suite under the management of CCTests is a collection of test programs. Each test program should have the following structure:

#include <cctests.h>

cctests_fun_t   test_1_1;
cctests_fun_t   test_1_2;
cctests_fun_t   test_2_1;
cctests_fun_t   test_2_2;

int
main (void)
{
  cctests_init("demo");
  {
    cctests_begin_group("one");
    {
      cctests_run(test_1_1);
      cctests_run(test_1_2);
    }
    cctests_end_group();

    cctests_begin_group("two");
    {
      cctests_run(test_2_1);
      cctests_run(test_2_2);
    }
    cctests_end_group();
  }
  cctests_final();
}

void test_1_1 (cce_destination_t L) { ... }
void test_1_2 (cce_destination_t L) { ... }
void test_2_1 (cce_destination_t L) { ... }
void test_2_2 (cce_destination_t L) { ... }

notice that first of all we must call the initialisation function cctests_init(). We are free to put the test groups in subordinate functions.

Function: void cctests_init (char const * test_file_name)

Initialise the internal structures of the library; this function must be called before doing everything else in a test program. It is fine to call this function multiple times.

The argument test_file_name must reference an ASCIIZ string representing the name of the test program.

NOTE We could generate the value of the argument test_file_name with the preprocessor macro __FILE__, but we must be ware that such value includes directory and file extension parts we may not want (because they make it more complex to compose a regular expression that matches).

The test file name is used as follows:

• If the string matches the POSIX regular expression in the environment variable cctests_file: this function initialises the library and returns. This way the test program is executed. If cctests_file is unset or set to the empty string: the test program name matches and the tests are executed.
• Otherwise this function terminates the current process by calling:

  exit(77);
  

  effectively skipping this test program. The exit status 77 is recognised by GNU Automake’s test harness as the code signalling a skipped test.

Function: void cctests_final (void)

Finalise a test program. This function calls exit() to terminate the current process. The main purpose of this function is to select the correct exit status to interface, for example, to GNU Automake’s test harness.

Function: void cctests_reset_global_state (void)

Reset the internal state to represent an all–successful execution so far. We can use this function if we want cctests_final() to exit successfully the current process.

Variable: FILE * cctests_log_stream

An output stream used to log messages. It is initialised to stderr.

This document describes version 0.4.1-devel.1 of CCTests.