Testing

## Testing Testing |

## Synopsis

    #include <glib.h>

    typedef             GTestCase;
    typedef             GTestSuite;
    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)
    int                 g_strcmp0                           (const char *str1,
                                                             const char *str2);

## Description

## Details

### GTestCase

    typedef struct GTestCase  GTestCase;

### GTestSuite

    typedef struct GTestSuite GTestSuite;

### 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 - slow and thorough tests, may take quite long and maximize coverage. thorough - currently an alias for "slow". 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()

### g_test_slow()

    #define             g_test_slow()

### g_test_thorough()

    #define             g_test_thorough()

### g_test_perf()

    #define             g_test_perf()

### g_test_verbose()

    #define             g_test_verbose()

### g_test_quiet()

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

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 seperated portions of `testpath`.

`testpath` : | Slash seperated 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 seperated 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, simmilar 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)

`gobject` : |

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

### 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 following flags: `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.

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 successfull 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 reuslt 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 reuslt 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()

### g_test_trap_assert_failed()

    #define             g_test_trap_assert_failed()

### g_test_trap_assert_stdout()

    #define             g_test_trap_assert_stdout(soutpattern)

`soutpattern` : |

### g_test_trap_assert_stdout_unmatched()

    #define             g_test_trap_assert_stdout_unmatched(soutpattern)

`soutpattern` : |

### g_test_trap_assert_stderr()

    #define             g_test_trap_assert_stderr(serrpattern)

`serrpattern` : |

### g_test_trap_assert_stderr_unmatched()

    #define             g_test_trap_assert_stderr_unmatched(serrpattern)

`serrpattern` : |

### g_test_rand_bit()

    #define             g_test_rand_bit()

### g_test_rand_int ()

    gint32              g_test_rand_int                     (void);

Get a reproducable random integer number. The random numbers generate 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 reproducable 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 reproducable 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 reproducable 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)

`expr` : |

### g_assert_not_reached()

    #define             g_assert_not_reached()

### g_assert_cmpstr()

    #define             g_assert_cmpstr(s1, cmp, s2)

`s1` : |
`cmp` : |
`s2` : |

### g_assert_cmpint()

    #define             g_assert_cmpint(n1, cmp, n2)

`n1` : |
`cmp` : |
`n2` : |

### g_assert_cmpuint()

    #define             g_assert_cmpuint(n1, cmp, n2)

`n1` : |
`cmp` : |
`n2` : |

### g_assert_cmphex()

    #define             g_assert_cmphex(n1, cmp, n2)

`n1` : |
`cmp` : |
`n2` : |

### g_assert_cmpfloat()

    #define             g_assert_cmpfloat(n1,cmp,n2)

`n1` : |
`cmp` : |
`n2` : |

### g_strcmp0 ()

    int                 g_strcmp0                           (const char *str1,
                                                             const char *str2);

Compares `str1` and `str2` like `strcmp()`. Handles `NULL` strings gracefully.

`str1` : | a C string or `NULL`
`str2` : | another C string or `NULL`
Returns : | -1, 0 or 1, if `str1` is <, == or > than `str2`.

Since 2.16