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.

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.

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:

Since 2.16

g_test_quick

#define             g_test_quick()

Returns TRUE if tests are run in quick mode. Exactly one of g_test_quick() and g_test_slow() is active in any run; there is no "medium speed".

g_test_slow

#define             g_test_slow()

Returns TRUE if tests are run in slow mode. Exactly one of g_test_quick() and g_test_slow() is active in any run; there is no "medium speed".

g_test_thorough

#define             g_test_thorough()

Returns TRUE if tests are run in thorough mode, equivalent to g_test_slow().

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. The default is neither g_test_verbose() nor g_test_quiet().

g_test_undefined

#define             g_test_undefined()

Returns TRUE if tests may provoke assertions and other formally-undefined behaviour under g_test_trap_fork(), to verify that appropriate warnings are given. It can be useful to turn this off if running tests under valgrind.

g_test_quiet

#define             g_test_quiet()

Returns TRUE if tests are run in quiet mode. The default is neither g_test_verbose() nor g_test_quiet().

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.

Since 2.16

GTestFunc ()

void
(*GTestFunc) (void);

The type used for test case functions.

Since 2.28

g_test_add_func ()

void
g_test_add_func (const char *testpath,
                 GTestFunc test_func);

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 .

Since 2.16

GTestDataFunc ()

void
(*GTestDataFunc) (gconstpointer user_data);

The type used for test case functions that take an extra pointer argument.

Since 2.28

g_test_add_data_func ()

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

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 .

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.

Since 2.16

g_test_fail ()

void
g_test_fail (void);

Indicates that a test failed. This function can be called multiple times from the same test. You can use this function if your test failed in a recoverable way.

Do not use this function if the failure of a test could cause other tests to malfunction.

Calling this function will not stop the test from running, you need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test.

If not called from inside a test, this function does nothing.

Since 2.30

g_test_message ()

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

Add a message to the test report.

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.

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 .

Since 2.16

GTestLogFatalFunc ()

gboolean
(*GTestLogFatalFunc) (const gchar *log_domain,
                      GLogLevelFlags log_level,
                      const gchar *message,
                      gpointer user_data);

Specifies the prototype of fatal log handler functions.

Since 2.22

g_test_log_set_fatal_handler ()

void
g_test_log_set_fatal_handler (GTestLogFatalFunc log_func,
                              gpointer user_data);

Installs a non-error fatal log handler which can be used to decide whether log messages which are counted as fatal abort the program.

The use case here is that you are running a test case that depends on particular libraries or circumstances and cannot prevent certain known critical or warning messages. So you install a handler that compares the domain and message to precisely not abort in such a case.

Note that the handler is reset at the beginning of any test case, so you have to set it inside each test function which needs the special behavior.

This handler has no effect on g_error messages.

Since 2.22

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().

Since 2.16

g_test_timer_last ()

double
g_test_timer_last (void);

Report the last result of g_test_timer_elapsed().

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().

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.

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().

Since 2.16

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.

1
2
3
4
5
6
7
8
9
10
11
12
13

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.

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.

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.

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().

This is sometimes used to test situations that are formally considered to be undefined behaviour, like inputs that fail a g_return_if_fail() check. In these situations you should skip the entire test, including the call to g_test_trap_fork(), unless g_test_undefined() returns TRUE to indicate that undefined behaviour may be tested.

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().

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().

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().

This is sometimes used to test situations that are formally considered to be undefined behaviour, like inputs that fail a g_return_if_fail() check. In these situations you should skip the entire test, including the call to g_test_trap_fork(), unless g_test_undefined() returns TRUE to indicate that undefined behaviour may be tested.

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().

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.

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.

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.

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.

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.

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 (g_strcmp0 (s1, s2) op 0). The advantage of this macro is that it can produce a message that includes the actual values of s1 and s2 .

1

g_assert_cmpstr (mystring, ==, "fubar");

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 .

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 .

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.

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_cmpfloat (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 .

Since 2.16

g_assert_no_error()

#define             g_assert_no_error(err)

Debugging macro to terminate the application with a warning message if a method has returned a GError.

The effect of g_assert_no_error (err) is the same as g_assert (err == NULL). The advantage of this macro is that it can produce a message that includes the error message and code.

Since 2.20

g_assert_error()

#define             g_assert_error(err, dom, c)

Debugging macro to terminate the application with a warning message if a method has not returned the correct GError.

The effect of g_assert_error (err, dom, c) is the same as g_assert (err != NULL && err->domain == dom && err->code == c). The advantage of this macro is that it can produce a message that includes the incorrect error message and code.

This can only be used to test for a specific error. If you want to test that err is set, but don't care what it's set to, just use g_assert (err != NULL)

Since 2.20

GTestFixtureFunc ()

void
(*GTestFixtureFunc) (gpointer fixture,
                     gconstpointer user_data);

The type used for functions that operate on test fixtures. This is used for the fixture setup and teardown functions as well as for the testcases themselves.

user_data is a pointer to the data that was given when registering the test case.

fixture will be a pointer to the area of memory allocated by the test framework, of the size requested. If the requested size was zero then fixture will be equal to user_data .

Since 2.28

g_test_create_case ()

GTestCase *
g_test_create_case (const char *test_name,
                    gsize data_size,
                    gconstpointer test_data,
                    GTestFixtureFunc data_setup,
                    GTestFixtureFunc data_test,
                    GTestFixtureFunc data_teardown);

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.

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 .

Since 2.16

g_test_get_root ()

GTestSuite *
g_test_get_root (void);

Get the toplevel test suite for the test path API.

Since 2.16

g_test_suite_add ()

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

Adds test_case to suite .

Since 2.16

g_test_suite_add_suite ()

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

Adds nestedsuite to suite .

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.

Since 2.16

enum GTestTrapFlags

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

GTestCase

typedef struct GTestCase  GTestCase;

An opaque structure representing a test case.

GTestSuite

typedef struct GTestSuite GTestSuite;

An opaque structure representing a test suite.