Testing

Testing — a test framework

Synopsis


#include <glib.h>

void                g_test_minimized_result             (double minimized_quantity,
                                                         const char *format,
                                                         ...);
void                g_test_maximized_result             (double maximized_quantity,
                                                         const char *format,
                                                         ...);
void                g_test_init                         (int *argc,
                                                         char ***argv,
                                                         ...);
#define             g_test_quick                        ()
#define             g_test_slow                         ()
#define             g_test_thorough                     ()
#define             g_test_perf                         ()
#define             g_test_verbose                      ()
#define             g_test_quiet                        ()
int                 g_test_run                          (void);
void                g_test_add_func                     (const char *testpath,
                                                         void (test_funcvoid) ());
void                g_test_add_data_func                (const char *testpath,
                                                         gconstpointer test_data,
                                                         void (test_funcgconstpointer) ());
#define             g_test_add                          (testpath, Fixture, tdata, fsetup, ftest, fteardown)
void                g_test_message                      (const char *format,
                                                         ...);
void                g_test_bug_base                     (const char *uri_pattern);
void                g_test_bug                          (const char *bug_uri_snippet);
void                g_test_timer_start                  (void);
double              g_test_timer_elapsed                (void);
double              g_test_timer_last                   (void);
void                g_test_queue_free                   (gpointer gfree_pointer);
void                g_test_queue_destroy                (GDestroyNotify destroy_func,
                                                         gpointer destroy_data);
#define             g_test_queue_unref                  (gobject)
enum                GTestTrapFlags;
gboolean            g_test_trap_fork                    (guint64 usec_timeout,
                                                         GTestTrapFlags test_trap_flags);
gboolean            g_test_trap_has_passed              (void);
gboolean            g_test_trap_reached_timeout         (void);
#define             g_test_trap_assert_passed           ()
#define             g_test_trap_assert_failed           ()
#define             g_test_trap_assert_stdout           (soutpattern)
#define             g_test_trap_assert_stdout_unmatched (soutpattern)
#define             g_test_trap_assert_stderr           (serrpattern)
#define             g_test_trap_assert_stderr_unmatched (serrpattern)
#define             g_test_rand_bit                     ()
gint32              g_test_rand_int                     (void);
gint32              g_test_rand_int_range               (gint32 begin,
                                                         gint32 end);
double              g_test_rand_double                  (void);
double              g_test_rand_double_range            (double range_start,
                                                         double range_end);
#define             g_assert                            (expr)
#define             g_assert_not_reached                ()
#define             g_assert_cmpstr                     (s1, cmp, s2)
#define             g_assert_cmpint                     (n1, cmp, n2)
#define             g_assert_cmpuint                    (n1, cmp, n2)
#define             g_assert_cmphex                     (n1, cmp, n2)
#define             g_assert_cmpfloat                   (n1,cmp,n2)
typedef             GTestCase;
typedef             GTestSuite;
GTestCase*          g_test_create_case                  (const char *test_name,
                                                         gsize data_size,
                                                         gconstpointer test_data,
                                                         void (data_setupvoid) (),
                                                         void (data_testvoid) (),
                                                         void (data_teardownvoid) ());
GTestSuite*         g_test_create_suite                 (const char *suite_name);
GTestSuite*         g_test_get_root                     (void);
void                g_test_suite_add                    (GTestSuite *suite,
                                                         GTestCase *test_case);
void                g_test_suite_add_suite              (GTestSuite *suite,
                                                         GTestSuite *nestedsuite);
int                 g_test_run_suite                    (GTestSuite *suite);

Description

GLib provides a framework for writing and maintaining unit tests in parallel to the code they are testing. The API is designed according to established concepts found in the other test frameworks (JUnit, NUnit, RUnit), which in turn is based on smalltalk unit testing concepts.

Test case

Tests (test methods) are grouped together with their fixture into test cases.

Fixture

A test fixture consists of fixture data and setup and teardown methods to establish the environment for the test functions. We use fresh fixtures, i.e. fixtures are newly set up and torn down around each test invokation to avoid dependencies between tests.

Test suite

Test cases can be grouped into test suites, to allow subsets of the available tests to be run. Test suites can be grouped into other test suites as well.

The API is designed to handle creation and registration of test suites and test cases implicitly. A simple call like

  g_test_add_func ("/misc/assertions", test_assertions);

creates a test suite called "misc" with a single test case named "assertions", which consists of running the test_assertions function.

In addition to the traditional g_assert(), the test framework provides an extended set of assertions for string and numerical comparisons: g_assert_cmpfloat(), g_assert_cmpint(), g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpstr(). The advantage of these variants over plain g_assert() is that the assertion messages can be more elaborate, and include the values of the compared entities.

GLib ships with two utilites called gtester and gtester-report to facilitate running tests and producing nicely formatted test reports.

Details

g_test_minimized_result ()

void                g_test_minimized_result             (double minimized_quantity,
                                                         const char *format,
                                                         ...);

Report the result of a performance or measurement test. The test should generally strive to minimize the reported quantities (smaller values are better than larger ones), this and minimized_quantity can determine sorting order for test result reports.

minimized_quantity : the reported value
format : the format string of the report message
... : arguments to pass to the printf() function

Since 2.16


g_test_maximized_result ()

void                g_test_maximized_result             (double maximized_quantity,
                                                         const char *format,
                                                         ...);

Report the result of a performance or measurement test. The test should generally strive to maximize the reported quantities (larger values are better than smaller ones), this and maximized_quantity can determine sorting order for test result reports.

maximized_quantity : the reported value
format : the format string of the report message
... : arguments to pass to the printf() function

Since 2.16


g_test_init ()

void                g_test_init                         (int *argc,
                                                         char ***argv,
                                                         ...);

Initialize the GLib testing framework, e.g. by seeding the test random number generator, the name for g_get_prgname() and parsing test related command line args. So far, the following arguments are understood:

-l

list test cases available in a test executable.

--seed=RANDOMSEED

provide a random seed to reproduce test runs using random numbers.

--verbose

run tests verbosely.

-q, --quiet

run tests quietly.

-p TESTPATH

execute all tests matching TESTPATH.

-m {perf|slow|thorough|quick}

execute tests according to these test modes:

perf

performance tests, may take long and report results.

slow, thorough

slow and thorough tests, may take quite long and maximize coverage.

quick

quick tests, should run really quickly and give good coverage.

--debug-log

debug test logging output.

-k, --keep-going

gtester-specific argument.

--GTestLogFD N

gtester-specific argument.

--GTestSkipCount N

gtester-specific argument.

argc : Address of the argc parameter of the main() function. Changed if any arguments were handled.
argv : Address of the argv parameter of main(). Any parameters understood by g_test_init() stripped before return.
... : Reserved for future extension. Currently, you must pass NULL.

Since 2.16


g_test_quick()

#define             g_test_quick()

Returns TRUE if tests are run in quick mode.


g_test_slow()

#define             g_test_slow()

Returns TRUE if tests are run in slow mode.


g_test_thorough()

#define             g_test_thorough()

Returns TRUE if tests are run in thorough mode.


g_test_perf()

#define             g_test_perf()

Returns TRUE if tests are run in performance mode.


g_test_verbose()

#define             g_test_verbose()

Returns TRUE if tests are run in verbose mode.


g_test_quiet()

#define             g_test_quiet()

Returns TRUE if tests are run in quiet mode.


g_test_run ()

int                 g_test_run                          (void);

Runs all tests under the toplevel suite which can be retrieved with g_test_get_root(). Similar to g_test_run_suite(), the test cases to be run are filtered according to test path arguments (-p testpath) as parsed by g_test_init(). g_test_run_suite() or g_test_run() may only be called once in a program.

Returns : 0 on success

Since 2.16


g_test_add_func ()

void                g_test_add_func                     (const char *testpath,
                                                         void (test_funcvoid) ());

Create a new test case, similar to g_test_create_case(). However the test is assumed to use no fixture, and test suites are automatically created on the fly and added to the root fixture, based on the slash-separated portions of testpath.

testpath : Slash-separated test case path name for the test.
test_func : The test function to invoke for this test.

Since 2.16


g_test_add_data_func ()

void                g_test_add_data_func                (const char *testpath,
                                                         gconstpointer test_data,
                                                         void (test_funcgconstpointer) ());

Create a new test case, similar to g_test_create_case(). However the test is assumed to use no fixture, and test suites are automatically created on the fly and added to the root fixture, based on the slash-separated portions of testpath. The test_data argument will be passed as first argument to test_func.

testpath : Slash-separated test case path name for the test.
test_data : Test data argument for the test function.
test_func : The test function to invoke for this test.

Since 2.16


g_test_add()

#define             g_test_add(testpath, Fixture, tdata, fsetup, ftest, fteardown)

Hook up a new test case at testpath, similar to g_test_add_func(). A fixture data structure with setup and teardown function may be provided though, similar to g_test_create_case(). g_test_add() is implemented as a macro, so that the fsetup(), ftest() and fteardown() callbacks can expect a Fixture pointer as first argument in a type safe manner.

testpath : The test path for a new test case.
Fixture : The type of a fixture data structure.
tdata : Data argument for the test functions.
fsetup : The function to set up the fixture data.
ftest : The actual test function.
fteardown : The function to tear down the fixture data.

Since 2.16


g_test_message ()

void                g_test_message                      (const char *format,
                                                         ...);

Add a message to the test report.

format : the format string
... : printf-like arguments to format

Since 2.16


g_test_bug_base ()

void                g_test_bug_base                     (const char *uri_pattern);

Specify the base URI for bug reports.

The base URI is used to construct bug report messages for g_test_message() when g_test_bug() is called. Calling this function outside of a test case sets the default base URI for all test cases. Calling it from within a test case changes the base URI for the scope of the test case only. Bug URIs are constructed by appending a bug specific URI portion to uri_pattern, or by replacing the special string 's' within uri_pattern if that is present.

uri_pattern : the base pattern for bug URIs

Since 2.16


g_test_bug ()

void                g_test_bug                          (const char *bug_uri_snippet);

This function adds a message to test reports that associates a bug URI with a test case. Bug URIs are constructed from a base URI set with g_test_bug_base() and bug_uri_snippet.

bug_uri_snippet : Bug specific bug tracker URI portion.

Since 2.16


g_test_timer_start ()

void                g_test_timer_start                  (void);

Start a timing test. Call g_test_timer_elapsed() when the task is supposed to be done. Call this function again to restart the timer.

Since 2.16


g_test_timer_elapsed ()

double              g_test_timer_elapsed                (void);

Get the time since the last start of the timer with g_test_timer_start().

Returns : the time since the last start of the timer, as a double

Since 2.16


g_test_timer_last ()

double              g_test_timer_last                   (void);

Report the last result of g_test_timer_elapsed().

Returns : the last result of g_test_timer_elapsed(), as a double

Since 2.16


g_test_queue_free ()

void                g_test_queue_free                   (gpointer gfree_pointer);

Enqueue a pointer to be released with g_free() during the next teardown phase. This is equivalent to calling g_test_queue_destroy() with a destroy callback of g_free().

gfree_pointer : the pointer to be stored.

Since 2.16


g_test_queue_destroy ()

void                g_test_queue_destroy                (GDestroyNotify destroy_func,
                                                         gpointer destroy_data);

This function enqueus a callback @destroy_func() to be executed during the next test case teardown phase. This is most useful to auto destruct allocted test resources at the end of a test run. Resources are released in reverse queue order, that means enqueueing callback A before callback B will cause B() to be called before A() during teardown.

destroy_func : Destroy callback for teardown phase.
destroy_data : Destroy callback data.

Since 2.16


g_test_queue_unref()

#define             g_test_queue_unref(gobject)

Enqueue an object to be released with g_object_unref() during the next teardown phase. This is equivalent to calling g_test_queue_destroy() with a destroy callback of g_object_unref().

gobject : the object to unref

Since 2.16


enum GTestTrapFlags

typedef enum {
  G_TEST_TRAP_SILENCE_STDOUT    = 1 << 7,
  G_TEST_TRAP_SILENCE_STDERR    = 1 << 8,
  G_TEST_TRAP_INHERIT_STDIN     = 1 << 9
} GTestTrapFlags;

Test traps are guards around forked tests. These flags determine what traps to set.

G_TEST_TRAP_SILENCE_STDOUT Redirect stdout of the test child to /dev/null so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stdout().
G_TEST_TRAP_SILENCE_STDERR Redirect stderr of the test child to /dev/null so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stderr().
G_TEST_TRAP_INHERIT_STDIN If this flag is given, stdin of the forked child process is shared with stdin of its parent process. It is redirected to /dev/null otherwise.

g_test_trap_fork ()

gboolean            g_test_trap_fork                    (guint64 usec_timeout,
                                                         GTestTrapFlags test_trap_flags);

Fork the current test program to execute a test case that might not return or that might abort. The forked test case is aborted and considered failing if its run time exceeds usec_timeout.

The forking behavior can be configured with the GTestTrapFlags flags.

In the following example, the test code forks, the forked child process produces some sample output and exits successfully. The forking parent process then asserts successful child program termination and validates child program outputs.

  static void
  test_fork_patterns (void)
  {
    if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
      {
        g_print ("some stdout text: somagic17\n");
        g_printerr ("some stderr text: semagic43\n");
        exit (0); /* successful test run */
      }
    g_test_trap_assert_passed();
    g_test_trap_assert_stdout ("*somagic17*");
    g_test_trap_assert_stderr ("*semagic43*");
  }

This function is implemented only on Unix platforms.

usec_timeout : Timeout for the forked test in micro seconds.
test_trap_flags : Flags to modify forking behaviour.
Returns : TRUE for the forked child and FALSE for the executing parent process.

Since 2.16


g_test_trap_has_passed ()

gboolean            g_test_trap_has_passed              (void);

Check the result of the last g_test_trap_fork() call.

Returns : TRUE if the last forked child terminated successfully.

Since 2.16


g_test_trap_reached_timeout ()

gboolean            g_test_trap_reached_timeout         (void);

Check the result of the last g_test_trap_fork() call.

Returns : TRUE if the last forked child got killed due to a fork timeout.

Since 2.16


g_test_trap_assert_passed()

#define             g_test_trap_assert_passed()

Assert that the last forked test passed. See g_test_trap_fork().

Since 2.16


g_test_trap_assert_failed()

#define             g_test_trap_assert_failed()

Assert that the last forked test failed. See g_test_trap_fork().

Since 2.16


g_test_trap_assert_stdout()

#define             g_test_trap_assert_stdout(soutpattern)

Assert that the stdout output of the last forked test matches soutpattern. See g_test_trap_fork().

soutpattern : a glob-style pattern

Since 2.16


g_test_trap_assert_stdout_unmatched()

#define             g_test_trap_assert_stdout_unmatched(soutpattern)

Assert that the stdout output of the last forked test does not match soutpattern. See g_test_trap_fork().

soutpattern : a glob-style pattern

Since 2.16


g_test_trap_assert_stderr()

#define             g_test_trap_assert_stderr(serrpattern)

Assert that the stderr output of the last forked test matches serrpattern. See g_test_trap_fork().

serrpattern : a glob-style pattern

Since 2.16


g_test_trap_assert_stderr_unmatched()

#define             g_test_trap_assert_stderr_unmatched(serrpattern)

Assert that the stderr output of the last forked test does not match serrpattern. See g_test_trap_fork().

serrpattern : a glob-style pattern

Since 2.16


g_test_rand_bit()

#define             g_test_rand_bit()

Get a reproducible random bit (0 or 1), see g_test_rand_int() for details on test case random numbers.

Since 2.16


g_test_rand_int ()

gint32              g_test_rand_int                     (void);

Get a reproducible random integer number.

The random numbers generated by the g_test_rand_*() family of functions change with every new test program start, unless the --seed option is given when starting test programs.

For individual test cases however, the random number generator is reseeded, to avoid dependencies between tests and to make --seed effective for all test cases.

Returns : a random number from the seeded random number generator.

Since 2.16


g_test_rand_int_range ()

gint32              g_test_rand_int_range               (gint32 begin,
                                                         gint32 end);

Get a reproducible random integer number out of a specified range, see g_test_rand_int() for details on test case random numbers.

begin : the minimum value returned by this function
end : the smallest value not to be returned by this function
Returns : a number with begin <= number < end.

Since 2.16


g_test_rand_double ()

double              g_test_rand_double                  (void);

Get a reproducible random floating point number, see g_test_rand_int() for details on test case random numbers.

Returns : a random number from the seeded random number generator.

Since 2.16


g_test_rand_double_range ()

double              g_test_rand_double_range            (double range_start,
                                                         double range_end);

Get a reproducible random floating pointer number out of a specified range, see g_test_rand_int() for details on test case random numbers.

range_start : the minimum value returned by this function
range_end : the minimum value not returned by this function
Returns : a number with range_start <= number < range_end.

Since 2.16


g_assert()

#define             g_assert(expr)

Debugging macro to terminate the application if the assertion fails. If the assertion fails (i.e. the expression is not true), an error message is logged and the application is terminated.

The macro can be turned off in final releases of code by defining G_DISABLE_ASSERT when compiling the application.

expr : the expression to check.

g_assert_not_reached()

#define             g_assert_not_reached()

Debugging macro to terminate the application if it is ever reached. If it is reached, an error message is logged and the application is terminated.

The macro can be turned off in final releases of code by defining G_DISABLE_ASSERT when compiling the application.


g_assert_cmpstr()

#define             g_assert_cmpstr(s1, cmp, s2)

Debugging macro to terminate the application with a warning message if a string comparison fails. The strings are compared using g_strcmp0().

The effect of g_assert_cmpstr (s1, op, s2) is the same as g_assert (s1 op s2). The advantage of this macro is that it can produce a message that includes the actual values of s1 and s2.

  g_assert_cmpstr (mystring, ==, "fubar");
s1 : a string (may be NULL)
cmp : The comparsion operator to use. One of ==, !=, <, >, <=, >=.
s2 : another string (may be NULL)

Since 2.16


g_assert_cmpint()

#define             g_assert_cmpint(n1, cmp, n2)

Debugging macro to terminate the application with a warning message if an integer comparison fails.

The effect of g_assert_cmpint (n1, op, n2) is the same as g_assert (n1 op n2). The advantage of this macro is that it can produce a message that includes the actual values of n1 and n2.

n1 : an integer
cmp : The comparsion operator to use. One of ==, !=, <, >, <=, >=.
n2 : another integer

Since 2.16


g_assert_cmpuint()

#define             g_assert_cmpuint(n1, cmp, n2)

Debugging macro to terminate the application with a warning message if an unsigned integer comparison fails.

The effect of g_assert_cmpuint (n1, op, n2) is the same as g_assert (n1 op n2). The advantage of this macro is that it can produce a message that includes the actual values of n1 and n2.

n1 : an unsigned integer
cmp : The comparsion operator to use. One of ==, !=, <, >, <=, >=.
n2 : another unsigned integer

Since 2.16


g_assert_cmphex()

#define             g_assert_cmphex(n1, cmp, n2)

Debugging macro to terminate the application with a warning message if an unsigned integer comparison fails. This is a variant of g_assert_cmpuint() that displays the numbers in hexadecimal notation in the message.

n1 : an unsigned integer
cmp : The comparsion operator to use. One of ==, !=, <, >, <=, >=.
n2 : another unsigned integer

Since 2.16


g_assert_cmpfloat()

#define             g_assert_cmpfloat(n1,cmp,n2)

Debugging macro to terminate the application with a warning message if a floating point number comparison fails.

The effect of g_assert_cmpflott (n1, op, n2) is the same as g_assert (n1 op n2). The advantage of this function is that it can produce a message that includes the actual values of n1 and n2.

n1 : an floating point number
cmp : The comparsion operator to use. One of ==, !=, <, >, <=, >=.
n2 : another floating point number

Since 2.16


GTestCase

typedef struct GTestCase  GTestCase;

An opaque structure representing a test case.


GTestSuite

typedef struct GTestSuite GTestSuite;

An opaque structure representing a test suite.


g_test_create_case ()

GTestCase*          g_test_create_case                  (const char *test_name,
                                                         gsize data_size,
                                                         gconstpointer test_data,
                                                         void (data_setupvoid) (),
                                                         void (data_testvoid) (),
                                                         void (data_teardownvoid) ());

Create a new GTestCase, named test_name, this API is fairly low level, calling g_test_add() or g_test_add_func() is preferable. When this test is executed, a fixture structure of size data_size will be allocated and filled with 0s. Then data_setup() is called to initialize the fixture. After fixture setup, the actual test function data_test() is called. Once the test run completed, the fixture structure is torn down by calling data_teardown() and after that the memory is released.

Splitting up a test run into fixture setup, test function and fixture teardown is most usful if the same fixture is used for multiple tests. In this cases, g_test_create_case() will be called with the same fixture, but varying test_name and data_test arguments.

test_name : the name for the test case
data_size : the size of the fixture data structure
test_data : test data argument for the test functions
data_setup : the function to set up the fixture data
data_test : the actual test function
data_teardown : the function to teardown the fixture data
Returns : a newly allocated GTestCase.

Since 2.16


g_test_create_suite ()

GTestSuite*         g_test_create_suite                 (const char *suite_name);

Create a new test suite with the name suite_name.

suite_name : a name for the suite
Returns : A newly allocated GTestSuite instance.

Since 2.16


g_test_get_root ()

GTestSuite*         g_test_get_root                     (void);

Get the toplevel test suite for the test path API.

Returns : the toplevel GTestSuite

Since 2.16


g_test_suite_add ()

void                g_test_suite_add                    (GTestSuite *suite,
                                                         GTestCase *test_case);

Adds test_case to suite.

suite : a GTestSuite
test_case : a GTestCase

Since 2.16


g_test_suite_add_suite ()

void                g_test_suite_add_suite              (GTestSuite *suite,
                                                         GTestSuite *nestedsuite);

Adds nestedsuite to suite.

suite : a GTestSuite
nestedsuite : another GTestSuite

Since 2.16


g_test_run_suite ()

int                 g_test_run_suite                    (GTestSuite *suite);

Execute the tests within suite and all nested GTestSuites. The test suites to be executed are filtered according to test path arguments (-p testpath) as parsed by g_test_init(). g_test_run_suite() or g_test_run() may only be called once in a program.

suite : a GTestSuite
Returns : 0 on success

Since 2.16

See Also

gtester, gtester-report