<refentry id="glib-Testing">
<refmeta>
<refentrytitle role="top_of_page">Testing</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Testing</refname>
<refpurpose></refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;


typedef             <link linkend="GTestCase">GTestCase</link>;
typedef             <link linkend="GTestSuite">GTestSuite</link>;
<link linkend="void">void</link>                <link linkend="g-test-minimized-result">g_test_minimized_result</link>             (<link linkend="double">double</link> minimized_quantity,
                                                         const <link linkend="char">char</link> *format,
                                                         ...);
<link linkend="void">void</link>                <link linkend="g-test-maximized-result">g_test_maximized_result</link>             (<link linkend="double">double</link> maximized_quantity,
                                                         const <link linkend="char">char</link> *format,
                                                         ...);
<link linkend="void">void</link>                <link linkend="g-test-init">g_test_init</link>                         (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv,
                                                         ...);
#define             <link linkend="g-test-quick">g_test_quick</link>                        ()
#define             <link linkend="g-test-slow">g_test_slow</link>                         ()
#define             <link linkend="g-test-thorough">g_test_thorough</link>                     ()
#define             <link linkend="g-test-perf">g_test_perf</link>                         ()
#define             <link linkend="g-test-verbose">g_test_verbose</link>                      ()
#define             <link linkend="g-test-quiet">g_test_quiet</link>                        ()
<link linkend="int">int</link>                 <link linkend="g-test-run">g_test_run</link>                          (void);
<link linkend="void">void</link>                <link linkend="g-test-add-func">g_test_add_func</link>                     (const <link linkend="char">char</link> *testpath,
                                                         <link linkend="void">void</link> (test_funcvoid) ());
<link linkend="void">void</link>                <link linkend="g-test-add-data-func">g_test_add_data_func</link>                (const <link linkend="char">char</link> *testpath,
                                                         <link linkend="gconstpointer">gconstpointer</link> test_data,
                                                         <link linkend="void">void</link> (test_funcgconstpointer) ());
#define             <link linkend="g-test-add">g_test_add</link>                          (testpath, Fixture, tdata, fsetup, ftest, fteardown)
<link linkend="void">void</link>                <link linkend="g-test-message">g_test_message</link>                      (const <link linkend="char">char</link> *format,
                                                         ...);
<link linkend="void">void</link>                <link linkend="g-test-bug-base">g_test_bug_base</link>                     (const <link linkend="char">char</link> *uri_pattern);
<link linkend="void">void</link>                <link linkend="g-test-bug">g_test_bug</link>                          (const <link linkend="char">char</link> *bug_uri_snippet);
<link linkend="void">void</link>                <link linkend="g-test-timer-start">g_test_timer_start</link>                  (void);
<link linkend="double">double</link>              <link linkend="g-test-timer-elapsed">g_test_timer_elapsed</link>                (void);
<link linkend="double">double</link>              <link linkend="g-test-timer-last">g_test_timer_last</link>                   (void);
<link linkend="void">void</link>                <link linkend="g-test-queue-free">g_test_queue_free</link>                   (<link linkend="gpointer">gpointer</link> gfree_pointer);
<link linkend="void">void</link>                <link linkend="g-test-queue-destroy">g_test_queue_destroy</link>                (<link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func,
                                                         <link linkend="gpointer">gpointer</link> destroy_data);
#define             <link linkend="g-test-queue-unref">g_test_queue_unref</link>                  (gobject)
enum                <link linkend="GTestTrapFlags">GTestTrapFlags</link>;
<link linkend="gboolean">gboolean</link>            <link linkend="g-test-trap-fork">g_test_trap_fork</link>                    (<link linkend="guint64">guint64</link> usec_timeout,
                                                         <link linkend="GTestTrapFlags">GTestTrapFlags</link> test_trap_flags);
<link linkend="gboolean">gboolean</link>            <link linkend="g-test-trap-has-passed">g_test_trap_has_passed</link>              (void);
<link linkend="gboolean">gboolean</link>            <link linkend="g-test-trap-reached-timeout">g_test_trap_reached_timeout</link>         (void);
#define             <link linkend="g-test-trap-assert-passed">g_test_trap_assert_passed</link>           ()
#define             <link linkend="g-test-trap-assert-failed">g_test_trap_assert_failed</link>           ()
#define             <link linkend="g-test-trap-assert-stdout">g_test_trap_assert_stdout</link>           (soutpattern)
#define             <link linkend="g-test-trap-assert-stdout-unmatched">g_test_trap_assert_stdout_unmatched</link> (soutpattern)
#define             <link linkend="g-test-trap-assert-stderr">g_test_trap_assert_stderr</link>           (serrpattern)
#define             <link linkend="g-test-trap-assert-stderr-unmatched">g_test_trap_assert_stderr_unmatched</link> (serrpattern)
#define             <link linkend="g-test-rand-bit">g_test_rand_bit</link>                     ()
<link linkend="gint32">gint32</link>              <link linkend="g-test-rand-int">g_test_rand_int</link>                     (void);
<link linkend="gint32">gint32</link>              <link linkend="g-test-rand-int-range">g_test_rand_int_range</link>               (<link linkend="gint32">gint32</link> begin,
                                                         <link linkend="gint32">gint32</link> end);
<link linkend="double">double</link>              <link linkend="g-test-rand-double">g_test_rand_double</link>                  (void);
<link linkend="double">double</link>              <link linkend="g-test-rand-double-range">g_test_rand_double_range</link>            (<link linkend="double">double</link> range_start,
                                                         <link linkend="double">double</link> range_end);
#define             <link linkend="g-assert">g_assert</link>                            (expr)
#define             <link linkend="g-assert-not-reached">g_assert_not_reached</link>                ()
#define             <link linkend="g-assert-cmpstr">g_assert_cmpstr</link>                     (s1, cmp, s2)
#define             <link linkend="g-assert-cmpint">g_assert_cmpint</link>                     (n1, cmp, n2)
#define             <link linkend="g-assert-cmpuint">g_assert_cmpuint</link>                    (n1, cmp, n2)
#define             <link linkend="g-assert-cmphex">g_assert_cmphex</link>                     (n1, cmp, n2)
#define             <link linkend="g-assert-cmpfloat">g_assert_cmpfloat</link>                   (n1,cmp,n2)
<link linkend="int">int</link>                 <link linkend="g-strcmp0">g_strcmp0</link>                           (const <link linkend="char">char</link> *str1,
                                                         const <link linkend="char">char</link> *str2);

</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="GTestCase" role="typedef"/>GTestCase</title>
<indexterm><primary>GTestCase</primary></indexterm><programlisting>typedef struct GTestCase  GTestCase;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GTestSuite" role="typedef"/>GTestSuite</title>
<indexterm><primary>GTestSuite</primary></indexterm><programlisting>typedef struct GTestSuite GTestSuite;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-minimized-result" role="function"/>g_test_minimized_result ()</title>
<indexterm><primary>g_test_minimized_result</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_minimized_result             (<link linkend="double">double</link> minimized_quantity,
                                                         const <link linkend="char">char</link> *format,
                                                         ...);</programlisting>
<para>
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 <parameter>minimized_quantity</parameter> can determine sorting
order for test result reports.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>minimized_quantity</parameter>&nbsp;:</term>
<listitem><simpara> the reported value
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> the format string of the report message
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> arguments to pass to the <link linkend="printf"><function>printf()</function></link> function
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-maximized-result" role="function"/>g_test_maximized_result ()</title>
<indexterm><primary>g_test_maximized_result</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_maximized_result             (<link linkend="double">double</link> maximized_quantity,
                                                         const <link linkend="char">char</link> *format,
                                                         ...);</programlisting>
<para>
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 <parameter>maximized_quantity</parameter> can determine sorting
order for test result reports.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>maximized_quantity</parameter>&nbsp;:</term>
<listitem><simpara> the reported value
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> the format string of the report message
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> arguments to pass to the <link linkend="printf"><function>printf()</function></link> function
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-init" role="function"/>g_test_init ()</title>
<indexterm><primary>g_test_init</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_init                         (<link linkend="int">int</link> *argc,
                                                         <link linkend="char">char</link> ***argv,
                                                         ...);</programlisting>
<para>
Initialize the GLib testing framework, e.g. by seeding the
test random number generator, the name for <link linkend="g-get-prgname"><function>g_get_prgname()</function></link>
and parsing test related command line args.
So far, the following arguments are understood:
<informalexample>
-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.
</informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&nbsp;:</term>
<listitem><simpara> Address of the <parameter>argc</parameter> parameter of the <link linkend="main"><function>main()</function></link> function.
       Changed if any arguments were handled.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>argv</parameter>&nbsp;:</term>
<listitem><simpara> Address of the <parameter>argv</parameter> parameter of <link linkend="main"><function>main()</function></link>.
       Any parameters understood by <link linkend="g-test-init"><function>g_test_init()</function></link> stripped before return.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> Reserved for future extension. Currently, you must pass <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-quick" role="macro"/>g_test_quick()</title>
<indexterm><primary>g_test_quick</primary></indexterm><programlisting>#define             g_test_quick()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-slow" role="macro"/>g_test_slow()</title>
<indexterm><primary>g_test_slow</primary></indexterm><programlisting>#define             g_test_slow()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-thorough" role="macro"/>g_test_thorough()</title>
<indexterm><primary>g_test_thorough</primary></indexterm><programlisting>#define             g_test_thorough()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-perf" role="macro"/>g_test_perf()</title>
<indexterm><primary>g_test_perf</primary></indexterm><programlisting>#define             g_test_perf()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-verbose" role="macro"/>g_test_verbose()</title>
<indexterm><primary>g_test_verbose</primary></indexterm><programlisting>#define             g_test_verbose()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-quiet" role="macro"/>g_test_quiet()</title>
<indexterm><primary>g_test_quiet</primary></indexterm><programlisting>#define             g_test_quiet()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-run" role="function"/>g_test_run ()</title>
<indexterm><primary>g_test_run</primary></indexterm><programlisting><link linkend="int">int</link>                 g_test_run                          (void);</programlisting>
<para>
Runs all tests under the toplevel suite which can be retrieved
with <link linkend="g-test-get-root"><function>g_test_get_root()</function></link>. Similar to <link linkend="g-test-run-suite"><function>g_test_run_suite()</function></link>, the test
cases to be run are filtered according to
test path arguments (-p <replaceable>testpath</replaceable>) as 
parsed by <link linkend="g-test-init"><function>g_test_init()</function></link>.
<link linkend="g-test-run-suite"><function>g_test_run_suite()</function></link> or <link linkend="g-test-run"><function>g_test_run()</function></link> may only be called once
in a program.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 0 on success
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-add-func" role="function"/>g_test_add_func ()</title>
<indexterm><primary>g_test_add_func</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_add_func                     (const <link linkend="char">char</link> *testpath,
                                                         <link linkend="void">void</link> (test_funcvoid) ());</programlisting>
<para>
Create a new test case, similar to <link linkend="g-test-create-case"><function>g_test_create_case()</function></link>. 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 <parameter>testpath</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>testpath</parameter>&nbsp;:</term>
<listitem><simpara>   Slash seperated test case path name for the test.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_func</parameter>&nbsp;:</term>
<listitem><simpara>  The test function to invoke for this test.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-add-data-func" role="function"/>g_test_add_data_func ()</title>
<indexterm><primary>g_test_add_data_func</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_add_data_func                (const <link linkend="char">char</link> *testpath,
                                                         <link linkend="gconstpointer">gconstpointer</link> test_data,
                                                         <link linkend="void">void</link> (test_funcgconstpointer) ());</programlisting>
<para>
Create a new test case, similar to <link linkend="g-test-create-case"><function>g_test_create_case()</function></link>. 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 <parameter>testpath</parameter>. The <parameter>test_data</parameter> argument
will be passed as first argument to <parameter>test_func</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>testpath</parameter>&nbsp;:</term>
<listitem><simpara>   Slash separated test case path name for the test.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_data</parameter>&nbsp;:</term>
<listitem><simpara>  Test data argument for the test function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_func</parameter>&nbsp;:</term>
<listitem><simpara>  The test function to invoke for this test.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-add" role="macro"/>g_test_add()</title>
<indexterm><primary>g_test_add</primary></indexterm><programlisting>#define             g_test_add(testpath, Fixture, tdata, fsetup, ftest, fteardown)</programlisting>
<para>
Hook up a new test case at <parameter>testpath</parameter>, similar to <link linkend="g-test-add-func"><function>g_test_add_func()</function></link>.
A fixture data structure with setup and teardown function may be provided
though, simmilar to <link linkend="g-test-create-case"><function>g_test_create_case()</function></link>.
<link linkend="g-test-add"><function>g_test_add()</function></link> is implemented as a macro, so that the <link linkend="fsetup"><function>fsetup()</function></link>, <link linkend="ftest"><function>ftest()</function></link> and
<link linkend="fteardown"><function>fteardown()</function></link> callbacks can expect a <parameter>Fixture</parameter> pointer as first argument in
a type safe manner.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>testpath</parameter>&nbsp;:</term>
<listitem><simpara>  The test path for a new test case.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>Fixture</parameter>&nbsp;:</term>
<listitem><simpara>   The type of a fixture data structure.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tdata</parameter>&nbsp;:</term>
<listitem><simpara>     Data argument for the test functions.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fsetup</parameter>&nbsp;:</term>
<listitem><simpara>    The function to set up the fixture data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ftest</parameter>&nbsp;:</term>
<listitem><simpara>     The actual test function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fteardown</parameter>&nbsp;:</term>
<listitem><simpara> The function to tear down the fixture data.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-message" role="function"/>g_test_message ()</title>
<indexterm><primary>g_test_message</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_message                      (const <link linkend="char">char</link> *format,
                                                         ...);</programlisting>
<para>
Add a message to the test report.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> the format string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>    printf-like arguments to <parameter>format</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-bug-base" role="function"/>g_test_bug_base ()</title>
<indexterm><primary>g_test_bug_base</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_bug_base                     (const <link linkend="char">char</link> *uri_pattern);</programlisting>
<para>
Specify the base URI for bug reports.
The base URI is used to construct bug report messages for
<link linkend="g-test-message"><function>g_test_message()</function></link> when <link linkend="g-test-bug"><function>g_test_bug()</function></link> 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 <parameter>uri_pattern</parameter>, or by replacing the special string
'<link linkend="s"><literal>s</literal></link>' within <parameter>uri_pattern</parameter> if that is present.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri_pattern</parameter>&nbsp;:</term>
<listitem><simpara> the base pattern for bug URIs
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-bug" role="function"/>g_test_bug ()</title>
<indexterm><primary>g_test_bug</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_bug                          (const <link linkend="char">char</link> *bug_uri_snippet);</programlisting>
<para>
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 <link linkend="g-test-bug-base"><function>g_test_bug_base()</function></link>
and <parameter>bug_uri_snippet</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>bug_uri_snippet</parameter>&nbsp;:</term>
<listitem><simpara> Bug specific bug tracker URI portion.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-timer-start" role="function"/>g_test_timer_start ()</title>
<indexterm><primary>g_test_timer_start</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_timer_start                  (void);</programlisting>
<para>
Start a timing test. Call <link linkend="g-test-timer-elapsed"><function>g_test_timer_elapsed()</function></link> when the task is supposed
to be done. Call this function again to restart the timer.</para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-timer-elapsed" role="function"/>g_test_timer_elapsed ()</title>
<indexterm><primary>g_test_timer_elapsed</primary></indexterm><programlisting><link linkend="double">double</link>              g_test_timer_elapsed                (void);</programlisting>
<para>
Get the time since the last start of the timer with <link linkend="g-test-timer-start"><function>g_test_timer_start()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the time since the last start of the timer, as a double
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-timer-last" role="function"/>g_test_timer_last ()</title>
<indexterm><primary>g_test_timer_last</primary></indexterm><programlisting><link linkend="double">double</link>              g_test_timer_last                   (void);</programlisting>
<para>
Report the last result of <link linkend="g-test-timer-elapsed"><function>g_test_timer_elapsed()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the last result of <link linkend="g-test-timer-elapsed"><function>g_test_timer_elapsed()</function></link>, as a double
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-queue-free" role="function"/>g_test_queue_free ()</title>
<indexterm><primary>g_test_queue_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_queue_free                   (<link linkend="gpointer">gpointer</link> gfree_pointer);</programlisting>
<para>
Enqueue a pointer to be released with <link linkend="g-free"><function>g_free()</function></link> during the next
teardown phase. This is equivalent to calling <link linkend="g-test-queue-destroy"><function>g_test_queue_destroy()</function></link>
with a destroy callback of <link linkend="g-free"><function>g_free()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>gfree_pointer</parameter>&nbsp;:</term>
<listitem><simpara> the pointer to be stored.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-queue-destroy" role="function"/>g_test_queue_destroy ()</title>
<indexterm><primary>g_test_queue_destroy</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_queue_destroy                (<link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func,
                                                         <link linkend="gpointer">gpointer</link> destroy_data);</programlisting>
<para>
This function enqueus a callback @<link linkend="destroy-func"><function>destroy_func()</function></link> 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 <link linkend="B:CAPS"><function>B()</function></link> to be called before
<link linkend="A:CAPS"><function>A()</function></link> during teardown.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>destroy_func</parameter>&nbsp;:</term>
<listitem><simpara>       Destroy callback for teardown phase.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_data</parameter>&nbsp;:</term>
<listitem><simpara>       Destroy callback data.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-queue-unref" role="macro"/>g_test_queue_unref()</title>
<indexterm><primary>g_test_queue_unref</primary></indexterm><programlisting>#define             g_test_queue_unref(gobject)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>gobject</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GTestTrapFlags" role="enum"/>enum GTestTrapFlags</title>
<indexterm><primary>GTestTrapFlags</primary></indexterm><programlisting>typedef enum {
  G_TEST_TRAP_SILENCE_STDOUT    = 1 &lt;&lt; 7,
  G_TEST_TRAP_SILENCE_STDERR    = 1 &lt;&lt; 8,
  G_TEST_TRAP_INHERIT_STDIN     = 1 &lt;&lt; 9
} GTestTrapFlags;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-trap-fork" role="function"/>g_test_trap_fork ()</title>
<indexterm><primary>g_test_trap_fork</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_test_trap_fork                    (<link linkend="guint64">guint64</link> usec_timeout,
                                                         <link linkend="GTestTrapFlags">GTestTrapFlags</link> test_trap_flags);</programlisting>
<para>
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 <parameter>usec_timeout</parameter>.
The forking behavior can be configured with the following flags:
<link linkend="G-TEST-TRAP-SILENCE-STDOUT:CAPS"><literal>G_TEST_TRAP_SILENCE_STDOUT</literal></link> - 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 <link linkend="g-test-trap-assert-stdout"><function>g_test_trap_assert_stdout()</function></link>.
<link linkend="G-TEST-TRAP-SILENCE-STDERR:CAPS"><literal>G_TEST_TRAP_SILENCE_STDERR</literal></link> - 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 <link linkend="g-test-trap-assert-stderr"><function>g_test_trap_assert_stderr()</function></link>.
<link linkend="G-TEST-TRAP-INHERIT-STDIN:CAPS"><literal>G_TEST_TRAP_INHERIT_STDIN</literal></link> - 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.
</para>
<para>
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 cihld program outputs.
</para>
<para>
<informalexample><programlisting>
  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); /&ast; successful test run &ast;/
      }
    g_test_trap_assert_passed();
    g_test_trap_assert_stdout ("*somagic17*");
    g_test_trap_assert_stderr ("*semagic43*");
  }
</programlisting></informalexample>
</para>
<para>
This function is implemented only on Unix platforms.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>usec_timeout</parameter>&nbsp;:</term>
<listitem><simpara>    Timeout for the forked test in micro seconds.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_trap_flags</parameter>&nbsp;:</term>
<listitem><simpara> Flags to modify forking behaviour.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for the forked child and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for the executing parent process.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-trap-has-passed" role="function"/>g_test_trap_has_passed ()</title>
<indexterm><primary>g_test_trap_has_passed</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_test_trap_has_passed              (void);</programlisting>
<para>
Check the reuslt of the last <link linkend="g-test-trap-fork"><function>g_test_trap_fork()</function></link> call.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the last forked child terminated successfully.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-trap-reached-timeout" role="function"/>g_test_trap_reached_timeout ()</title>
<indexterm><primary>g_test_trap_reached_timeout</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_test_trap_reached_timeout         (void);</programlisting>
<para>
Check the reuslt of the last <link linkend="g-test-trap-fork"><function>g_test_trap_fork()</function></link> call.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the last forked child got killed due to a fork timeout.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-trap-assert-passed" role="macro"/>g_test_trap_assert_passed()</title>
<indexterm><primary>g_test_trap_assert_passed</primary></indexterm><programlisting>#define             g_test_trap_assert_passed()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-trap-assert-failed" role="macro"/>g_test_trap_assert_failed()</title>
<indexterm><primary>g_test_trap_assert_failed</primary></indexterm><programlisting>#define             g_test_trap_assert_failed()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-trap-assert-stdout" role="macro"/>g_test_trap_assert_stdout()</title>
<indexterm><primary>g_test_trap_assert_stdout</primary></indexterm><programlisting>#define             g_test_trap_assert_stdout(soutpattern)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>soutpattern</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-trap-assert-stdout-unmatched" role="macro"/>g_test_trap_assert_stdout_unmatched()</title>
<indexterm><primary>g_test_trap_assert_stdout_unmatched</primary></indexterm><programlisting>#define             g_test_trap_assert_stdout_unmatched(soutpattern)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>soutpattern</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-trap-assert-stderr" role="macro"/>g_test_trap_assert_stderr()</title>
<indexterm><primary>g_test_trap_assert_stderr</primary></indexterm><programlisting>#define             g_test_trap_assert_stderr(serrpattern)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>serrpattern</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-trap-assert-stderr-unmatched" role="macro"/>g_test_trap_assert_stderr_unmatched()</title>
<indexterm><primary>g_test_trap_assert_stderr_unmatched</primary></indexterm><programlisting>#define             g_test_trap_assert_stderr_unmatched(serrpattern)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>serrpattern</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-rand-bit" role="macro"/>g_test_rand_bit()</title>
<indexterm><primary>g_test_rand_bit</primary></indexterm><programlisting>#define             g_test_rand_bit()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-test-rand-int" role="function"/>g_test_rand_int ()</title>
<indexterm><primary>g_test_rand_int</primary></indexterm><programlisting><link linkend="gint32">gint32</link>              g_test_rand_int                     (void);</programlisting>
<para>
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.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a random number from the seeded random number generator.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-rand-int-range" role="function"/>g_test_rand_int_range ()</title>
<indexterm><primary>g_test_rand_int_range</primary></indexterm><programlisting><link linkend="gint32">gint32</link>              g_test_rand_int_range               (<link linkend="gint32">gint32</link> begin,
                                                         <link linkend="gint32">gint32</link> end);</programlisting>
<para>
Get a reproducable random integer number out of a specified range,
see <link linkend="g-test-rand-int"><function>g_test_rand_int()</function></link> for details on test case random numbers.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>begin</parameter>&nbsp;:</term>
<listitem><simpara> the minimum value returned by this function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>end</parameter>&nbsp;:</term>
<listitem><simpara>   the smallest value not to be returned by this function
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a number with <parameter>begin</parameter> &lt;= number &lt; <parameter>end</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-rand-double" role="function"/>g_test_rand_double ()</title>
<indexterm><primary>g_test_rand_double</primary></indexterm><programlisting><link linkend="double">double</link>              g_test_rand_double                  (void);</programlisting>
<para>
Get a reproducable random floating point number,
see <link linkend="g-test-rand-int"><function>g_test_rand_int()</function></link> for details on test case random numbers.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a random number from the seeded random number generator.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-test-rand-double-range" role="function"/>g_test_rand_double_range ()</title>
<indexterm><primary>g_test_rand_double_range</primary></indexterm><programlisting><link linkend="double">double</link>              g_test_rand_double_range            (<link linkend="double">double</link> range_start,
                                                         <link linkend="double">double</link> range_end);</programlisting>
<para>
Get a reproducable random floating pointer number out of a specified range,
see <link linkend="g-test-rand-int"><function>g_test_rand_int()</function></link> for details on test case random numbers.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>range_start</parameter>&nbsp;:</term>
<listitem><simpara> the minimum value returned by this function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>range_end</parameter>&nbsp;:</term>
<listitem><simpara> the minimum value not returned by this function
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a number with <parameter>range_start</parameter> &lt;= number &lt; <parameter>range_end</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-assert" role="macro"/>g_assert()</title>
<indexterm><primary>g_assert</primary></indexterm><programlisting>#define             g_assert(expr)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>expr</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-assert-not-reached" role="macro"/>g_assert_not_reached()</title>
<indexterm><primary>g_assert_not_reached</primary></indexterm><programlisting>#define             g_assert_not_reached()</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="g-assert-cmpstr" role="macro"/>g_assert_cmpstr()</title>
<indexterm><primary>g_assert_cmpstr</primary></indexterm><programlisting>#define             g_assert_cmpstr(s1, cmp, s2)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-assert-cmpint" role="macro"/>g_assert_cmpint()</title>
<indexterm><primary>g_assert_cmpint</primary></indexterm><programlisting>#define             g_assert_cmpint(n1, cmp, n2)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>n1</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n2</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-assert-cmpuint" role="macro"/>g_assert_cmpuint()</title>
<indexterm><primary>g_assert_cmpuint</primary></indexterm><programlisting>#define             g_assert_cmpuint(n1, cmp, n2)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>n1</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n2</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-assert-cmphex" role="macro"/>g_assert_cmphex()</title>
<indexterm><primary>g_assert_cmphex</primary></indexterm><programlisting>#define             g_assert_cmphex(n1, cmp, n2)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>n1</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n2</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-assert-cmpfloat" role="macro"/>g_assert_cmpfloat()</title>
<indexterm><primary>g_assert_cmpfloat</primary></indexterm><programlisting>#define             g_assert_cmpfloat(n1,cmp,n2)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>n1</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n2</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strcmp0" role="function"/>g_strcmp0 ()</title>
<indexterm><primary>g_strcmp0</primary></indexterm><programlisting><link linkend="int">int</link>                 g_strcmp0                           (const <link linkend="char">char</link> *str1,
                                                         const <link linkend="char">char</link> *str2);</programlisting>
<para>
Compares <parameter>str1</parameter> and <parameter>str2</parameter> like <link linkend="strcmp"><function>strcmp()</function></link>. Handles <link linkend="NULL:CAPS"><literal>NULL</literal></link> strings gracefully.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>str1</parameter>&nbsp;:</term>
<listitem><simpara> a C string or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str2</parameter>&nbsp;:</term>
<listitem><simpara> another C string or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> -1, 0 or 1, if <parameter>str1</parameter> is &lt;, == or &gt; than <parameter>str2</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>





<refsect1><refsect2 /><refsect2 /></refsect1>
</refentry>
