## 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_initialized
    #define             g_test_quick
    #define             g_test_slow
    #define             g_test_thorough
    #define             g_test_perf
    #define             g_test_verbose
    #define             g_test_undefined
    #define             g_test_quiet
    gboolean            g_test_subprocess                   (void);
    int                 g_test_run                          (void);
    void                (*GTestFunc)                        (void);
    void                g_test_add_func                     (const char *testpath,
                                                             GTestFunc test_func);
    void                (*GTestDataFunc)                    (gconstpointer user_data);
    void                g_test_add_data_func                (const char *testpath,
                                                             gconstpointer test_data,
                                                             GTestDataFunc test_func);
    void                g_test_add_data_func_full           (const char *testpath,
                                                             gpointer test_data,
                                                             GTestDataFunc test_func,
                                                             GDestroyNotify data_free_func);
    #define             g_test_add                          (testpath,
                                                             Fixture,
                                                             tdata,
                                                             fsetup,
                                                             ftest,
                                                             fteardown)
    enum                GTestFileType;
    gchar *             g_test_build_filename               (GTestFileType file_type,
                                                             const gchar *first_path,
                                                             ...);
    const gchar *       g_test_get_filename                 (GTestFileType file_type,
                                                             const gchar *first_path,
                                                             ...);
    const gchar *       g_test_get_dir                      (GTestFileType file_type);
    void                g_test_fail                         (void);
    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);
    gboolean            (*GTestLogFatalFunc)                (const gchar *log_domain,
                                                             GLogLevelFlags log_level,
                                                             const gchar *message,
                                                             gpointer user_data);
    void                g_test_log_set_fatal_handler        (GTestLogFatalFunc log_func,
                                                             gpointer user_data);
    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)
    void                g_test_expect_message               (const gchar *log_domain,
                                                             GLogLevelFlags log_level,
                                                             const gchar *pattern);
    #define             g_test_assert_expected_messages
    enum                GTestTrapFlags;
    enum                GTestSubprocessFlags;
    void                g_test_trap_subprocess              (const char *test_path,
                                                             guint64 usec_timeout,
                                                             GTestSubprocessFlags test_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)
    gboolean            g_test_trap_fork                    (guint64 usec_timeout,
                                                             GTestTrapFlags test_trap_flags);
    #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)
    #define             g_assert_no_error                   (err)
    #define             g_assert_error                      (err,
                                                             dom,
                                                             c)
    typedef             GTestCase;
    typedef             GTestSuite;
    void                (*GTestFixtureFunc)                 (gpointer fixture,
                                                             gconstpointer user_data);
    GTestCase *         g_test_create_case                  (const char *test_name,
                                                             gsize data_size,
                                                             gconstpointer test_data,
                                                             GTestFixtureFunc data_setup,
                                                             GTestFixtureFunc data_test,
                                                             GTestFixtureFunc data_teardown);
    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 invocation 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

    1
    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 utilities 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`. This can also be used to force a test to run that would otherwise be skipped (ie, a test whose name contains "/subprocess").
`-m {perf|slow|thorough|quick|undefined|no-undefined}` | 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.
undefined | Tests for undefined behaviour, may provoke programming errors under `g_test_trap_subprocess()` or `g_test_expect_messages()` to check that appropriate assertions or warnings are given
no-undefined | Avoid tests for undefined behaviour
`--debug-log` | Debug test logging output.

`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_initialized

    #define             g_test_initialized()

Returns `TRUE` if `g_test_init()` has been called.

Returns : | `TRUE` if `g_test_init()` has been called.

Since 2.36

### 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".

Returns : | `TRUE` if in quick mode

### 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".

Returns : | the opposite of `g_test_quick()`

### g_test_thorough

    #define             g_test_thorough()

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

Returns : | the same thing as `g_test_slow()`

### g_test_perf

    #define             g_test_perf()

Returns `TRUE` if tests are run in performance mode.

Returns : | `TRUE` if 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()`.

Returns : | `TRUE` if in verbose mode

### g_test_undefined

    #define             g_test_undefined()

Returns `TRUE` if tests may provoke assertions and other formally-undefined behaviour, to verify that appropriate warnings are given. It might, in some cases, be useful to turn this off if running tests under valgrind.

Returns : | `TRUE` if tests may provoke programming errors

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

Returns : | `TRUE` if in quiet mode

### g_test_subprocess ()

    gboolean            g_test_subprocess                   (void);

Returns `TRUE` (after `g_test_init()` has been called) if the test program is running under `g_test_trap_subprocess()`.

Returns : | `TRUE` if the test program is running under `g_test_trap_subprocess()`.

Since 2.38

### 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

### 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`.

If `testpath` includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly required via the `-p` command-line option or `g_test_trap_subprocess()`.

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

Since 2.16

### GTestDataFunc ()

    void                (*GTestDataFunc)                    (gconstpointer user_data);

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

`user_data` : | the data provided when registering the test

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`.

If `testpath` includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly required via the `-p` command-line option or `g_test_trap_subprocess()`.

`testpath` : | /-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_data_func_full ()

    void                g_test_add_data_func_full           (const char *testpath,
                                                             gpointer test_data,
                                                             GTestDataFunc test_func,
                                                             GDestroyNotify data_free_func);

Create a new test case, as with `g_test_add_data_func()`, but freeing `test_data` after the test run is complete.

`testpath` : | /-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.
`data_free_func` : | GDestroyNotify for `test_data`.

Since 2.34

### 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

### enum GTestFileType

    typedef enum {
      G_TEST_DIST,
      G_TEST_BUILT
    } GTestFileType;

The type of file to return the filename for, when used with `g_test_build_filename()`.

These two options correspond rather directly to the 'dist' and 'built' terminology that automake uses and are explicitly used to distinguish between the 'srcdir' and 'builddir' being separate. All files in your project should either be dist (in the `DIST_EXTRA` or `dist_schema_DATA` sense, in which case they will always be in the srcdir) or built (in the `BUILT_SOURCES` sense, in which case they will always be in the builddir).

Note: as a general rule of automake, files that are generated only as part of the build-from-git process (but then are distributed with the tarball) always go in srcdir (even if doing a srcdir != builddir build from git) and are considered as distributed files.

`G_TEST_DIST` | a file that was included in the distribution tarball
`G_TEST_BUILT` | a file that was built on the compiling machine

Since 2.38

### g_test_build_filename ()

    gchar *             g_test_build_filename               (GTestFileType file_type,
                                                             const gchar *first_path,
                                                             ...);

Creates the pathname to a data file that is required for a test.

This function is conceptually similar to `g_build_filename()` except that the first argument has been replaced with a GTestFileType argument.

The data file should either have been distributed with the module containing the test (`G_TEST_DIST`) or built as part of the build system of that module (`G_TEST_BUILT`).

In order for this function to work in srcdir != builddir situations, the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to have been defined. As of 2.38, this is done by the Makefile.decl included in GLib. Please ensure that your copy is up to date before using this function.

In case neither variable is set, this function will fall back to using the dirname portion of argv[0], possibly removing ".libs". This allows for casual running of tests directly from the commandline in the srcdir == builddir case and should also support running of installed tests, assuming the data files have been installed in the same relative path as the test binary.

`file_type` : | the type of file (built vs. distributed)
`first_path` : | the first segment of the pathname
`...` : | `NULL`-terminated additional path segments
Returns : | the path of the file, to be freed using `g_free()`

Since 2.38

### g_test_get_filename ()

    const gchar *       g_test_get_filename                 (GTestFileType file_type,
                                                             const gchar *first_path,
                                                             ...);

Gets the pathname to a data file that is required for a test.

This is the same as `g_test_build_filename()` with two differences. The first difference is that must only use this function from within a testcase function. The second difference is that you need not free the return value -- it will be automatically freed when the testcase finishes running.

It is safe to use this function from a thread inside of a testcase but you must ensure that all such uses occur before the main testcase function returns (ie: it is best to ensure that all threads have been joined).

`file_type` : | the type of file (built vs. distributed)
`first_path` : | the first segment of the pathname
`...` : | `NULL`-terminated additional path segments
Returns : | the path, automatically freed at the end of the testcase

Since 2.38

### g_test_get_dir ()

    const gchar *       g_test_get_dir                      (GTestFileType file_type);

Gets the pathname of the directory containing test files of the type specified by `file_type`.

This is approximately the same as calling g_test_build_filename("."), but you don't need to free the return value.

`file_type` : | the type of file (built vs. distributed)
Returns : | the path of the directory, owned by GLib

Since 2.38

### 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.

`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

### GTestLogFatalFunc ()

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

Specifies the prototype of fatal log handler functions.

`log_domain` : | the log domain of the message
`log_level` : | the log level of the message (including the fatal and recursion flags)
`message` : | the message to process
`user_data` : | user data, set in `g_test_log_set_fatal_handler()`
Returns : | `TRUE` if the program should abort, `FALSE` otherwise

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.

`log_func` : | the log handler function.
`user_data` : | data passed to the log handler.

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

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

### g_test_expect_message ()

    void                g_test_expect_message               (const gchar *log_domain,
                                                             GLogLevelFlags log_level,
                                                             const gchar *pattern);

Indicates that a message with the given `log_domain` and `log_level`, with text matching `pattern`, is expected to be logged. When this message is logged, it will not be printed, and the test case will not abort.

Use `g_test_assert_expected_messages()` to assert that all previously-expected messages have been seen and suppressed.

You can call this multiple times in a row, if multiple messages are expected as a result of a single call. (The messages must appear in the same order as the calls to `g_test_expect_message()`.)

For example:

    1
    2
    3
    4
    5
    6
    7
    8
    /* g_main_context_push_thread_default() should fail if the
     * context is already owned by another thread.
     */
    g_test_expect_message (G_LOG_DOMAIN,
                           G_LOG_LEVEL_CRITICAL,
                           "assertion*acquired_context*failed");
    g_main_context_push_thread_default (bad_context);
    g_test_assert_expected_messages ();

Note that you cannot use this to test `g_error()` messages, since `g_error()` intentionally never returns even if the program doesn't abort; use `g_test_trap_subprocess()` in this case.

`log_domain` : | the log domain of the message. [allow-none]
`log_level` : | the log level of the message
`pattern` : | a glob-style pattern

Since 2.34

### g_test_assert_expected_messages

    #define             g_test_assert_expected_messages()

Asserts that all messages previously indicated via `g_test_expect_message()` have been seen and suppressed.

Since 2.34

### 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;

### Warning

`GTestTrapFlags` is deprecated and should not be used in newly-written code. GTestTrapFlags is used only with `g_test_trap_fork()`, which is deprecated. `g_test_trap_subprocess()` uses GTestTrapSubprocessFlags.

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 child process is shared with stdin of its parent process. It is redirected to `/dev/null` otherwise.

### enum GTestSubprocessFlags

    typedef enum {
      G_TEST_SUBPROCESS_INHERIT_STDIN  = 1 << 0,
      G_TEST_SUBPROCESS_INHERIT_STDOUT = 1 << 1,
      G_TEST_SUBPROCESS_INHERIT_STDERR = 1 << 2
    } GTestSubprocessFlags;

Flags to pass to `g_test_trap_subprocess()` to control input and output.

Note that in contrast with `g_test_trap_fork()`, the default is to not show stdout and stderr.

`G_TEST_SUBPROCESS_INHERIT_STDIN` | If this flag is given, the child process will inherit the parent's stdin. Otherwise, the child's stdin is redirected to `/dev/null`.
`G_TEST_SUBPROCESS_INHERIT_STDOUT` | If this flag is given, the child process will inherit the parent's stdout. Otherwise, the child's stdout will not be visible, but it will be captured to allow later tests with `g_test_trap_assert_stdout()`.
`G_TEST_SUBPROCESS_INHERIT_STDERR` | If this flag is given, the child process will inherit the parent's stderr. Otherwise, the child's stderr will not be visible, but it will be captured to allow later tests with `g_test_trap_assert_stderr()`.

### g_test_trap_subprocess ()

    void                g_test_trap_subprocess              (const char *test_path,
                                                             guint64 usec_timeout,
                                                             GTestSubprocessFlags test_flags);

Respawns the test program to run only `test_path` in a subprocess. This can be used for a test case that might not return, or that might abort. `test_path` will normally be the name of the parent test, followed by "`/subprocess/`" and then a name for the specific subtest (or just ending with "`/subprocess`" if the test only has one child test); tests with names of this form will automatically be skipped in the parent process.

If `usec_timeout` is non-0, the test subprocess is aborted and considered failing if its run time exceeds it.

The subprocess behavior can be configured with the GTestSubprocessFlags flags.

You can use methods such as `g_test_trap_assert_passed()`, `g_test_trap_assert_failed()`, and `g_test_trap_assert_stderr()` to check the results of the subprocess. (But note that `g_test_trap_assert_stdout()` and `g_test_trap_assert_stderr()` cannot be used if `test_flags` specifies that the child should inherit the parent stdout/stderr.)

If your ``main()`` needs to behave differently in the subprocess, you can call `g_test_subprocess()` (after calling `g_test_init()`) to see whether you are in a subprocess.

The following example tests that calling `my_object_new(1000000)` will abort with an error message.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    static void
    test_create_large_object_subprocess (void)
    {
      my_object_new (1000000);
    }

    static void
    test_create_large_object (void)
    {
      g_test_trap_subprocess ("/myobject/create_large_object/subprocess", 0, 0);
      g_test_trap_assert_failed ();
      g_test_trap_assert_stderr ("*ERROR*too large*");
    }

    int
    main (int argc, char **argv)
    {
      g_test_init (&argc, &argv, NULL);

      g_test_add_func ("/myobject/create_large_object",
                       test_create_large_object);
      /* Because of the '/subprocess' in the name, this test will
       * not be run by the g_test_run () call below.
       */
      g_test_add_func ("/myobject/create_large_object/subprocess",
                       test_create_large_object_subprocess);

      return g_test_run ();
    }

`test_path` : | Test to run in a subprocess
`usec_timeout` : | Timeout for the subprocess test in micro seconds.
`test_flags` : | Flags to modify subprocess behaviour.

Since 2.38

### g_test_trap_has_passed ()

    gboolean            g_test_trap_has_passed              (void);

Check the result of the last `g_test_trap_subprocess()` call.

Returns : | `TRUE` if the last test subprocess 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_subprocess()` call.

Returns : | `TRUE` if the last test subprocess got killed due to a timeout.

Since 2.16

### g_test_trap_assert_passed

    #define             g_test_trap_assert_passed()

Assert that the last test subprocess passed. See `g_test_trap_subprocess()`.

Since 2.16

### g_test_trap_assert_failed

    #define             g_test_trap_assert_failed()

Assert that the last test subprocess failed. See `g_test_trap_subprocess()`.

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_subprocess()`, 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 test subprocess matches `soutpattern`. See `g_test_trap_subprocess()`.

`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 test subprocess does not match `soutpattern`. See `g_test_trap_subprocess()`.

`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 test subprocess matches `serrpattern`. See `g_test_trap_subprocess()`.

This is sometimes used to test situations that are formally considered to be undefined behaviour, like code that hits a `g_assert()` or `g_error()`. In these situations you should skip the entire test, including the call to `g_test_trap_subprocess()`, unless `g_test_undefined()` returns `TRUE` to indicate that undefined behaviour may be tested.

`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 test subprocess does not match `serrpattern`. See `g_test_trap_subprocess()`.

`serrpattern` : | a glob-style pattern

Since 2.16

### g_test_trap_fork ()

    gboolean            g_test_trap_fork                    (guint64 usec_timeout,
                                                             GTestTrapFlags test_trap_flags);

### Warning

`g_test_trap_fork` is deprecated and should not be used in newly-written code. This function is implemented only on Unix platforms, and is not always reliable due to problems inherent in fork-without-exec. Use `g_test_trap_subprocess()` instead.

Fork the current test program to execute a test case that might not return or that might abort.

If `usec_timeout` is non-0, the forked test case is aborted and considered failing if its run time exceeds it.

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*");
    }

`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_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 compare two strings. If the comparison fails, an error message is logged and the application is either terminated or the testcase marked as failed. The strings are compared using `g_strcmp0()`.

The effect of `g_assert_cmpstr (s1, op, s2)` is the same as `g_assert_true (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");

`s1` : | a string (may be `NULL`)
`cmp` : | The comparison 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 compare two integers.

The effect of `g_assert_cmpint (n1, op, n2)` is the same as `g_assert_true (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 comparison operator to use. One of ==, !=, <, >, <=, >=.
`n2` : | another integer

Since 2.16

### g_assert_cmpuint()

    #define             g_assert_cmpuint(n1, cmp, n2)

Debugging macro to compare two unsigned integers.

The effect of `g_assert_cmpuint (n1, op, n2)` is the same as `g_assert_true (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 comparison 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 compare to unsigned integers.

This is a variant of `g_assert_cmpuint()` that displays the numbers in hexadecimal notation in the message.

`n1` : | an unsigned integer
`cmp` : | The comparison 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 compare two floating point numbers.

The effect of `g_assert_cmpfloat (n1, op, n2)` is the same as `g_assert_true (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 floating point number
`cmp` : | The comparison operator to use. One of ==, !=, <, >, <=, >=.
`n2` : | another floating point number

Since 2.16

### g_assert_no_error()

    #define             g_assert_no_error(err)

Debugging macro to check that a GError is not set.

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

`err` : | a GError, possibly `NULL`

Since 2.20

### g_assert_error()

    #define             g_assert_error(err, dom, c)

Debugging macro to check that a method has returned the correct GError.

The effect of `g_assert_error (err, dom, c)` is the same as `g_assert_true (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)`

`err` : | a GError, possibly `NULL`
`dom` : | the expected error domain (a GQuark)
`c` : | the expected error code

Since 2.20

### GTestCase

    typedef struct GTestCase  GTestCase;

An opaque structure representing a test case.

### GTestSuite

    typedef struct GTestSuite GTestSuite;

An opaque structure representing a test suite.

### 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`.

`fixture` : | the test fixture
`user_data` : | the data provided when registering the test

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.

`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