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

<refnamediv>
<refname>Testing</refname>
<refpurpose>a test framework</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Testing.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

<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)
#define             <link linkend="g-assert-no-error">g_assert_no_error</link>                   (err)
#define             <link linkend="g-assert-error">g_assert_error</link>                      (err, dom, c)
typedef             <link linkend="GTestCase">GTestCase</link>;
typedef             <link linkend="GTestSuite">GTestSuite</link>;
<link linkend="GTestCase">GTestCase</link>*          <link linkend="g-test-create-case">g_test_create_case</link>                  (const <link linkend="char">char</link> *test_name,
                                                         <link linkend="gsize">gsize</link> data_size,
                                                         <link linkend="gconstpointer">gconstpointer</link> test_data,
                                                         <link linkend="void">void</link> (data_setupvoid) (),
                                                         <link linkend="void">void</link> (data_testvoid) (),
                                                         <link linkend="void">void</link> (data_teardownvoid) ());
<link linkend="GTestSuite">GTestSuite</link>*         <link linkend="g-test-create-suite">g_test_create_suite</link>                 (const <link linkend="char">char</link> *suite_name);
<link linkend="GTestSuite">GTestSuite</link>*         <link linkend="g-test-get-root">g_test_get_root</link>                     (void);
<link linkend="void">void</link>                <link linkend="g-test-suite-add">g_test_suite_add</link>                    (<link linkend="GTestSuite">GTestSuite</link> *suite,
                                                         <link linkend="GTestCase">GTestCase</link> *test_case);
<link linkend="void">void</link>                <link linkend="g-test-suite-add-suite">g_test_suite_add_suite</link>              (<link linkend="GTestSuite">GTestSuite</link> *suite,
                                                         <link linkend="GTestSuite">GTestSuite</link> *nestedsuite);
<link linkend="int">int</link>                 <link linkend="g-test-run-suite">g_test_run_suite</link>                    (<link linkend="GTestSuite">GTestSuite</link> *suite);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Testing.description" role="desc">
<title role="desc.title">Description</title>
<para>
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.
<variablelist>
  <varlistentry>
    <term>Test case</term>
    <listitem><para>
      Tests (test methods) are grouped together with their
      fixture into test cases.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>Fixture</term>
    <listitem><para>
      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.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>Test suite</term>
    <listitem><para>
      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.
    </para></listitem>
  </varlistentry>
</variablelist>
The API is designed to handle creation and registration of test suites and
test cases implicitly. A simple call like
<informalexample><programlisting>
  g_test_add_func ("/misc/assertions", test_assertions);
</programlisting></informalexample>
creates a test suite called "misc" with a single test case named "assertions",
which consists of running the test_assertions function.
</para>
<para>
In addition to the traditional <link linkend="g-assert"><function>g_assert()</function></link>, the test framework provides
an extended set of assertions for string and numerical comparisons:
<link linkend="g-assert-cmpfloat"><function>g_assert_cmpfloat()</function></link>, <link linkend="g-assert-cmpint"><function>g_assert_cmpint()</function></link>, <link linkend="g-assert-cmpuint"><function>g_assert_cmpuint()</function></link>, <link linkend="g-assert-cmphex"><function>g_assert_cmphex()</function></link>,
<link linkend="g-assert-cmpstr"><function>g_assert_cmpstr()</function></link>. The advantage of these variants over plain <link linkend="g-assert"><function>g_assert()</function></link>
is that the assertion messages can be more elaborate, and include the
values of the compared entities.
</para>
<para>
GLib ships with two utilities called gtester and gtester-report to
facilitate running tests and producing nicely formatted test reports.
</para>
</refsect1>

<refsect1 id="glib-Testing.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="g-test-minimized-result" role="function" condition="since:2.16">
<title>g_test_minimized_result ()</title>
<indexterm zone="g-test-minimized-result" role="2.16"><primary sortas="test_minimized_result">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>&#160;:</term>
<listitem><simpara> the reported value
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara> the format string of the report message
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> arguments to pass to the <link linkend="printf"><function>printf()</function></link> function
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-maximized-result" role="function" condition="since:2.16">
<title>g_test_maximized_result ()</title>
<indexterm zone="g-test-maximized-result" role="2.16"><primary sortas="test_maximized_result">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>&#160;:</term>
<listitem><simpara> the reported value
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara> the format string of the report message
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> arguments to pass to the <link linkend="printf"><function>printf()</function></link> function
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-init" role="function" condition="since:2.16">
<title>g_test_init ()</title>
<indexterm zone="g-test-init" role="2.16"><primary sortas="test_init">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:
<variablelist>
  <varlistentry>
    <term><option>-l</option></term>
    <listitem><para>
      list test cases available in a test executable.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><option>--seed=<replaceable>RANDOMSEED</replaceable></option></term>
    <listitem><para>
      provide a random seed to reproduce test runs using random numbers.
    </para></listitem>
    </varlistentry>
    <varlistentry>
      <term><option>--verbose</option></term>
      <listitem><para>run tests verbosely.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-q</option>, <option>--quiet</option></term>
      <listitem><para>run tests quietly.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-p <replaceable>TESTPATH</replaceable></option></term>
      <listitem><para>
        execute all tests matching <replaceable>TESTPATH</replaceable>.
      </para></listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-m {perf|slow|thorough|quick}</option></term>
      <listitem><para>
        execute tests according to these test modes:
        <variablelist>
          <varlistentry>
            <term>perf</term>
            <listitem><para>
              performance tests, may take long and report results.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>slow, thorough</term>
            <listitem><para>
              slow and thorough tests, may take quite long and 
              maximize coverage.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>quick</term>
            <listitem><para>
              quick tests, should run really quickly and give good coverage.
            </para></listitem>
          </varlistentry>
        </variablelist>
      </para></listitem>
    </varlistentry>
    <varlistentry>
      <term><option>--debug-log</option></term>
      <listitem><para>debug test logging output.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-k</option>, <option>--keep-going</option></term>
      <listitem><para>gtester-specific argument.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term><option>--GTestLogFD <replaceable>N</replaceable></option></term>
      <listitem><para>gtester-specific argument.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term><option>--GTestSkipCount <replaceable>N</replaceable></option></term>
      <listitem><para>gtester-specific argument.</para></listitem>
    </varlistentry>
 </variablelist></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>argc</parameter>&#160;:</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>&#160;:</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>&#160;:</term>
<listitem><simpara> Reserved for future extension. Currently, you must pass <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-quick" role="macro">
<title>g_test_quick()</title>
<indexterm zone="g-test-quick"><primary sortas="test_quick">g_test_quick</primary></indexterm><programlisting>#define             g_test_quick()</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if tests are run in quick mode.
</para></refsect2>
<refsect2 id="g-test-slow" role="macro">
<title>g_test_slow()</title>
<indexterm zone="g-test-slow"><primary sortas="test_slow">g_test_slow</primary></indexterm><programlisting>#define             g_test_slow()</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if tests are run in slow mode.
</para></refsect2>
<refsect2 id="g-test-thorough" role="macro">
<title>g_test_thorough()</title>
<indexterm zone="g-test-thorough"><primary sortas="test_thorough">g_test_thorough</primary></indexterm><programlisting>#define             g_test_thorough()</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if tests are run in thorough mode.
</para></refsect2>
<refsect2 id="g-test-perf" role="macro">
<title>g_test_perf()</title>
<indexterm zone="g-test-perf"><primary sortas="test_perf">g_test_perf</primary></indexterm><programlisting>#define             g_test_perf()</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if tests are run in performance mode.
</para></refsect2>
<refsect2 id="g-test-verbose" role="macro">
<title>g_test_verbose()</title>
<indexterm zone="g-test-verbose"><primary sortas="test_verbose">g_test_verbose</primary></indexterm><programlisting>#define             g_test_verbose()</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if tests are run in verbose mode.
</para></refsect2>
<refsect2 id="g-test-quiet" role="macro">
<title>g_test_quiet()</title>
<indexterm zone="g-test-quiet"><primary sortas="test_quiet">g_test_quiet</primary></indexterm><programlisting>#define             g_test_quiet()</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if tests are run in quiet mode.
</para></refsect2>
<refsect2 id="g-test-run" role="function" condition="since:2.16">
<title>g_test_run ()</title>
<indexterm zone="g-test-run" role="2.16"><primary sortas="test_run">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>&#160;:</term><listitem><simpara> 0 on success

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-add-func" role="function" condition="since:2.16">
<title>g_test_add_func ()</title>
<indexterm zone="g-test-add-func" role="2.16"><primary sortas="test_add_func">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-separated portions of <parameter>testpath</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>testpath</parameter>&#160;:</term>
<listitem><simpara>   Slash-separated test case path name for the test.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_func</parameter>&#160;:</term>
<listitem><simpara>  The test function to invoke for this test.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-add-data-func" role="function" condition="since:2.16">
<title>g_test_add_data_func ()</title>
<indexterm zone="g-test-add-data-func" role="2.16"><primary sortas="test_add_data_func">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-separated 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>&#160;:</term>
<listitem><simpara>   Slash-separated test case path name for the test.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_data</parameter>&#160;:</term>
<listitem><simpara>  Test data argument for the test function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_func</parameter>&#160;:</term>
<listitem><simpara>  The test function to invoke for this test.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-add" role="macro" condition="since:2.16">
<title>g_test_add()</title>
<indexterm zone="g-test-add" role="2.16"><primary sortas="test_add">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, similar 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>&#160;:</term>
<listitem><simpara>  The test path for a new test case.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>Fixture</parameter>&#160;:</term>
<listitem><simpara>   The type of a fixture data structure.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tdata</parameter>&#160;:</term>
<listitem><simpara>     Data argument for the test functions.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fsetup</parameter>&#160;:</term>
<listitem><simpara>    The function to set up the fixture data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ftest</parameter>&#160;:</term>
<listitem><simpara>     The actual test function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fteardown</parameter>&#160;:</term>
<listitem><simpara> The function to tear down the fixture data.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-message" role="function" condition="since:2.16">
<title>g_test_message ()</title>
<indexterm zone="g-test-message" role="2.16"><primary sortas="test_message">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>&#160;:</term>
<listitem><simpara> the format string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>    printf-like arguments to <parameter>format</parameter>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-bug-base" role="function" condition="since:2.16">
<title>g_test_bug_base ()</title>
<indexterm zone="g-test-bug-base" role="2.16"><primary sortas="test_bug_base">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.
</para>
<para>
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>&#160;:</term>
<listitem><simpara> the base pattern for bug URIs
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-bug" role="function" condition="since:2.16">
<title>g_test_bug ()</title>
<indexterm zone="g-test-bug" role="2.16"><primary sortas="test_bug">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>&#160;:</term>
<listitem><simpara> Bug specific bug tracker URI portion.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-timer-start" role="function" condition="since:2.16">
<title>g_test_timer_start ()</title>
<indexterm zone="g-test-timer-start" role="2.16"><primary sortas="test_timer_start">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><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-timer-elapsed" role="function" condition="since:2.16">
<title>g_test_timer_elapsed ()</title>
<indexterm zone="g-test-timer-elapsed" role="2.16"><primary sortas="test_timer_elapsed">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>&#160;:</term><listitem><simpara> the time since the last start of the timer, as a double

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-timer-last" role="function" condition="since:2.16">
<title>g_test_timer_last ()</title>
<indexterm zone="g-test-timer-last" role="2.16"><primary sortas="test_timer_last">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>&#160;:</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><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-queue-free" role="function" condition="since:2.16">
<title>g_test_queue_free ()</title>
<indexterm zone="g-test-queue-free" role="2.16"><primary sortas="test_queue_free">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>&#160;:</term>
<listitem><simpara> the pointer to be stored.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-queue-destroy" role="function" condition="since:2.16">
<title>g_test_queue_destroy ()</title>
<indexterm zone="g-test-queue-destroy" role="2.16"><primary sortas="test_queue_destroy">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>&#160;:</term>
<listitem><simpara>       Destroy callback for teardown phase.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_data</parameter>&#160;:</term>
<listitem><simpara>       Destroy callback data.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-queue-unref" role="macro" condition="since:2.16">
<title>g_test_queue_unref()</title>
<indexterm zone="g-test-queue-unref" role="2.16"><primary sortas="test_queue_unref">g_test_queue_unref</primary></indexterm><programlisting>#define             g_test_queue_unref(gobject)</programlisting>
<para>
Enqueue an object to be released with <link linkend="g-object-unref"><function>g_object_unref()</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-object-unref"><function>g_object_unref()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>gobject</parameter>&#160;:</term>
<listitem><simpara>the object to unref
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="GTestTrapFlags" role="enum">
<title>enum GTestTrapFlags</title>
<indexterm zone="GTestTrapFlags"><primary sortas="TestTrapFlags">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>
Test traps are guards around forked tests. These flags
determine what traps to set.
</para><variablelist role="enum">
<varlistentry id="G-TEST-TRAP-SILENCE-STDOUT--CAPS" role="constant">
<term><literal>G_TEST_TRAP_SILENCE_STDOUT</literal></term>
<listitem><simpara>Redirect stdout of the test child to 
    <filename>/dev/null</filename> 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>.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-TEST-TRAP-SILENCE-STDERR--CAPS" role="constant">
<term><literal>G_TEST_TRAP_SILENCE_STDERR</literal></term>
<listitem><simpara>Redirect stderr of the test child to 
    <filename>/dev/null</filename> 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>.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-TEST-TRAP-INHERIT-STDIN--CAPS" role="constant">
<term><literal>G_TEST_TRAP_INHERIT_STDIN</literal></term>
<listitem><simpara>If this flag is given, stdin of the forked 
    child process is shared with stdin of its parent process. It is
    redirected to <filename>/dev/null</filename> otherwise.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-test-trap-fork" role="function" condition="since:2.16">
<title>g_test_trap_fork ()</title>
<indexterm zone="g-test-trap-fork" role="2.16"><primary sortas="test_trap_fork">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>.
</para>
<para>
The forking behavior can be configured with the <link linkend="GTestTrapFlags"><type>GTestTrapFlags</type></link> flags.
</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 successful child program
termination and validates child 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>&#160;:</term>
<listitem><simpara>    Timeout for the forked test in micro seconds.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_trap_flags</parameter>&#160;:</term>
<listitem><simpara> Flags to modify forking behaviour.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-trap-has-passed" role="function" condition="since:2.16">
<title>g_test_trap_has_passed ()</title>
<indexterm zone="g-test-trap-has-passed" role="2.16"><primary sortas="test_trap_has_passed">g_test_trap_has_passed</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_test_trap_has_passed              (void);</programlisting>
<para>
Check the result 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>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the last forked child terminated successfully.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-trap-reached-timeout" role="function" condition="since:2.16">
<title>g_test_trap_reached_timeout ()</title>
<indexterm zone="g-test-trap-reached-timeout" role="2.16"><primary sortas="test_trap_reached_timeout">g_test_trap_reached_timeout</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_test_trap_reached_timeout         (void);</programlisting>
<para>
Check the result 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>&#160;:</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><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-trap-assert-passed" role="macro" condition="since:2.16">
<title>g_test_trap_assert_passed()</title>
<indexterm zone="g-test-trap-assert-passed" role="2.16"><primary sortas="test_trap_assert_passed">g_test_trap_assert_passed</primary></indexterm><programlisting>#define             g_test_trap_assert_passed()</programlisting>
<para>
Assert that the last forked test passed. See <link linkend="g-test-trap-fork"><function>g_test_trap_fork()</function></link>.
</para><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-trap-assert-failed" role="macro" condition="since:2.16">
<title>g_test_trap_assert_failed()</title>
<indexterm zone="g-test-trap-assert-failed" role="2.16"><primary sortas="test_trap_assert_failed">g_test_trap_assert_failed</primary></indexterm><programlisting>#define             g_test_trap_assert_failed()</programlisting>
<para>
Assert that the last forked test failed. See <link linkend="g-test-trap-fork"><function>g_test_trap_fork()</function></link>.
</para><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-trap-assert-stdout" role="macro" condition="since:2.16">
<title>g_test_trap_assert_stdout()</title>
<indexterm zone="g-test-trap-assert-stdout" role="2.16"><primary sortas="test_trap_assert_stdout">g_test_trap_assert_stdout</primary></indexterm><programlisting>#define             g_test_trap_assert_stdout(soutpattern)</programlisting>
<para>
Assert that the stdout output of the last forked test matches <parameter>soutpattern</parameter>.
See <link linkend="g-test-trap-fork"><function>g_test_trap_fork()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>soutpattern</parameter>&#160;:</term>
<listitem><simpara>a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-trap-assert-stdout-unmatched" role="macro" condition="since:2.16">
<title>g_test_trap_assert_stdout_unmatched()</title>
<indexterm zone="g-test-trap-assert-stdout-unmatched" role="2.16"><primary sortas="test_trap_assert_stdout_unmatched">g_test_trap_assert_stdout_unmatched</primary></indexterm><programlisting>#define             g_test_trap_assert_stdout_unmatched(soutpattern)</programlisting>
<para>
Assert that the stdout output of the last forked test does not match
<parameter>soutpattern</parameter>.  See <link linkend="g-test-trap-fork"><function>g_test_trap_fork()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>soutpattern</parameter>&#160;:</term>
<listitem><simpara>a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-trap-assert-stderr" role="macro" condition="since:2.16">
<title>g_test_trap_assert_stderr()</title>
<indexterm zone="g-test-trap-assert-stderr" role="2.16"><primary sortas="test_trap_assert_stderr">g_test_trap_assert_stderr</primary></indexterm><programlisting>#define             g_test_trap_assert_stderr(serrpattern)</programlisting>
<para>
Assert that the stderr output of the last forked test matches <parameter>serrpattern</parameter>.
See <link linkend="g-test-trap-fork"><function>g_test_trap_fork()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>serrpattern</parameter>&#160;:</term>
<listitem><simpara>a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-trap-assert-stderr-unmatched" role="macro" condition="since:2.16">
<title>g_test_trap_assert_stderr_unmatched()</title>
<indexterm zone="g-test-trap-assert-stderr-unmatched" role="2.16"><primary sortas="test_trap_assert_stderr_unmatched">g_test_trap_assert_stderr_unmatched</primary></indexterm><programlisting>#define             g_test_trap_assert_stderr_unmatched(serrpattern)</programlisting>
<para>
Assert that the stderr output of the last forked test does not match
<parameter>serrpattern</parameter>.  See <link linkend="g-test-trap-fork"><function>g_test_trap_fork()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>serrpattern</parameter>&#160;:</term>
<listitem><simpara>a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-rand-bit" role="macro" condition="since:2.16">
<title>g_test_rand_bit()</title>
<indexterm zone="g-test-rand-bit" role="2.16"><primary sortas="test_rand_bit">g_test_rand_bit</primary></indexterm><programlisting>#define             g_test_rand_bit()</programlisting>
<para>
Get a reproducible random bit (0 or 1),
see <link linkend="g-test-rand-int"><function>g_test_rand_int()</function></link> for details on test case random numbers.
</para><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-rand-int" role="function" condition="since:2.16">
<title>g_test_rand_int ()</title>
<indexterm zone="g-test-rand-int" role="2.16"><primary sortas="test_rand_int">g_test_rand_int</primary></indexterm><programlisting><link linkend="gint32">gint32</link>              g_test_rand_int                     (void);</programlisting>
<para>
Get a reproducible random integer number.
</para>
<para>
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.
</para>
<para>
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>&#160;:</term><listitem><simpara> a random number from the seeded random number generator.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-rand-int-range" role="function" condition="since:2.16">
<title>g_test_rand_int_range ()</title>
<indexterm zone="g-test-rand-int-range" role="2.16"><primary sortas="test_rand_int_range">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 reproducible 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>&#160;:</term>
<listitem><simpara> the minimum value returned by this function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>end</parameter>&#160;:</term>
<listitem><simpara>   the smallest value not to be returned by this function
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a number with <parameter>begin</parameter> &lt;= number &lt; <parameter>end</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-rand-double" role="function" condition="since:2.16">
<title>g_test_rand_double ()</title>
<indexterm zone="g-test-rand-double" role="2.16"><primary sortas="test_rand_double">g_test_rand_double</primary></indexterm><programlisting><link linkend="double">double</link>              g_test_rand_double                  (void);</programlisting>
<para>
Get a reproducible 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>&#160;:</term><listitem><simpara> a random number from the seeded random number generator.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-rand-double-range" role="function" condition="since:2.16">
<title>g_test_rand_double_range ()</title>
<indexterm zone="g-test-rand-double-range" role="2.16"><primary sortas="test_rand_double_range">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 reproducible 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>&#160;:</term>
<listitem><simpara> the minimum value returned by this function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>range_end</parameter>&#160;:</term>
<listitem><simpara> the minimum value not returned by this function
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a number with <parameter>range_start</parameter> &lt;= number &lt; <parameter>range_end</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-assert" role="macro">
<title>g_assert()</title>
<indexterm zone="g-assert"><primary sortas="assert">g_assert</primary></indexterm><programlisting>#define             g_assert(expr)</programlisting>
<para>
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.
</para>
<para>
The macro can be turned off in final releases of code by defining
<link linkend="G-DISABLE-ASSERT--CAPS"><type>G_DISABLE_ASSERT</type></link> when compiling the application.
</para><variablelist role="params">
<varlistentry><term><parameter>expr</parameter>&#160;:</term>
<listitem><simpara>the expression to check.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-assert-not-reached" role="macro">
<title>g_assert_not_reached()</title>
<indexterm zone="g-assert-not-reached"><primary sortas="assert_not_reached">g_assert_not_reached</primary></indexterm><programlisting>#define             g_assert_not_reached()</programlisting>
<para>
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.
</para>
<para>
The macro can be turned off in final releases of code by defining
<link linkend="G-DISABLE-ASSERT--CAPS"><type>G_DISABLE_ASSERT</type></link> when compiling the application.
</para></refsect2>
<refsect2 id="g-assert-cmpstr" role="macro" condition="since:2.16">
<title>g_assert_cmpstr()</title>
<indexterm zone="g-assert-cmpstr" role="2.16"><primary sortas="assert_cmpstr">g_assert_cmpstr</primary></indexterm><programlisting>#define             g_assert_cmpstr(s1, cmp, s2)</programlisting>
<para>
Debugging macro to terminate the application with a warning message
if a string comparison fails.
The strings are compared using <link linkend="g-strcmp0"><function>g_strcmp0()</function></link>.
</para>
<para>
The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is the same
as <literal>g_assert (g_strcmp0 (s1, s2) op 0)</literal>. The advantage of this macro
is that it can produce a message that includes the actual values of <parameter>s1</parameter>
and <parameter>s2</parameter>.
</para>
<informalexample><programlisting>
  g_assert_cmpstr (mystring, ==, "fubar");
</programlisting></informalexample><variablelist role="params">
<varlistentry><term><parameter>s1</parameter>&#160;:</term>
<listitem><simpara>a string (may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&#160;:</term>
<listitem><simpara>The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&#160;:</term>
<listitem><simpara>another string (may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>)
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-assert-cmpint" role="macro" condition="since:2.16">
<title>g_assert_cmpint()</title>
<indexterm zone="g-assert-cmpint" role="2.16"><primary sortas="assert_cmpint">g_assert_cmpint</primary></indexterm><programlisting>#define             g_assert_cmpint(n1, cmp, n2)</programlisting>
<para>
Debugging macro to terminate the application with a warning message
if an integer comparison fails.
</para>
<para>
The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is the same
as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
is that it can produce a message that includes the actual values of <parameter>n1</parameter>
and <parameter>n2</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>n1</parameter>&#160;:</term>
<listitem><simpara>an integer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&#160;:</term>
<listitem><simpara>The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n2</parameter>&#160;:</term>
<listitem><simpara>another integer
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-assert-cmpuint" role="macro" condition="since:2.16">
<title>g_assert_cmpuint()</title>
<indexterm zone="g-assert-cmpuint" role="2.16"><primary sortas="assert_cmpuint">g_assert_cmpuint</primary></indexterm><programlisting>#define             g_assert_cmpuint(n1, cmp, n2)</programlisting>
<para>
Debugging macro to terminate the application with a warning message
if an unsigned integer comparison fails.
</para>
<para>
The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is the same
as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
is that it can produce a message that includes the actual values of <parameter>n1</parameter>
and <parameter>n2</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>n1</parameter>&#160;:</term>
<listitem><simpara>an unsigned integer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&#160;:</term>
<listitem><simpara>The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n2</parameter>&#160;:</term>
<listitem><simpara>another unsigned integer
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-assert-cmphex" role="macro" condition="since:2.16">
<title>g_assert_cmphex()</title>
<indexterm zone="g-assert-cmphex" role="2.16"><primary sortas="assert_cmphex">g_assert_cmphex</primary></indexterm><programlisting>#define             g_assert_cmphex(n1, cmp, n2)</programlisting>
<para>
Debugging macro to terminate the application with a warning message
if an unsigned integer comparison fails. This is a variant of
<link linkend="g-assert-cmpuint"><function>g_assert_cmpuint()</function></link> that displays the numbers in hexadecimal notation
in the message.
</para><variablelist role="params">
<varlistentry><term><parameter>n1</parameter>&#160;:</term>
<listitem><simpara>an unsigned integer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&#160;:</term>
<listitem><simpara>The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n2</parameter>&#160;:</term>
<listitem><simpara>another unsigned integer
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-assert-cmpfloat" role="macro" condition="since:2.16">
<title>g_assert_cmpfloat()</title>
<indexterm zone="g-assert-cmpfloat" role="2.16"><primary sortas="assert_cmpfloat">g_assert_cmpfloat</primary></indexterm><programlisting>#define             g_assert_cmpfloat(n1,cmp,n2)</programlisting>
<para>
Debugging macro to terminate the application with a warning message
if a floating point number comparison fails.
</para>
<para>
The effect of <literal>g_assert_cmpfloat (n1, op, n2)</literal> is the same
as <literal>g_assert (n1 op n2)</literal>. The advantage of this function
is that it can produce a message that includes the actual values of <parameter>n1</parameter>
and <parameter>n2</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>n1</parameter>&#160;:</term>
<listitem><simpara>an floating point number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cmp</parameter>&#160;:</term>
<listitem><simpara>The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n2</parameter>&#160;:</term>
<listitem><simpara>another floating point number
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-assert-no-error" role="macro" condition="since:2.20">
<title>g_assert_no_error()</title>
<indexterm zone="g-assert-no-error" role="2.20"><primary sortas="assert_no_error">g_assert_no_error</primary></indexterm><programlisting>#define             g_assert_no_error(err)</programlisting>
<para>
Debugging macro to terminate the application with a warning message
if a method has returned a <link linkend="GError"><type>GError</type></link>.
</para>
<para>
The effect of <literal>g_assert_no_error (err)</literal> is the same
as <literal>g_assert (err == NULL)</literal>. The advantage of this macro
is that it can produce a message that includes the error message and code.
</para><variablelist role="params">
<varlistentry><term><parameter>err</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GError"><type>GError</type></link>, possibly <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.20</para></refsect2>
<refsect2 id="g-assert-error" role="macro" condition="since:2.20">
<title>g_assert_error()</title>
<indexterm zone="g-assert-error" role="2.20"><primary sortas="assert_error">g_assert_error</primary></indexterm><programlisting>#define             g_assert_error(err, dom, c)</programlisting>
<para>
Debugging macro to terminate the application with a warning message
if a method has not returned the correct <link linkend="GError"><type>GError</type></link>.
</para>
<para>
The effect of <literal>g_assert_error (err, dom, c)</literal> is the same
as <literal>g_assert (err != NULL &amp;&amp; err->domain == dom &amp;&amp; err->code == c)</literal>.
The advantage of this macro is that it can produce a message that
includes the incorrect error message and code.
</para>
<para>
This can only be used to test for a specific error. If you want to
test that <parameter>err</parameter> is set, but don't care what it's set to, just use
<literal>g_assert (err != NULL)</literal>
</para><variablelist role="params">
<varlistentry><term><parameter>err</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GError"><type>GError</type></link>, possibly <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dom</parameter>&#160;:</term>
<listitem><simpara>the expected error domain (a <link linkend="GQuark"><type>GQuark</type></link>)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>c</parameter>&#160;:</term>
<listitem><simpara>the expected error code
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.20</para></refsect2>
<refsect2 id="GTestCase" role="typedef">
<title>GTestCase</title>
<indexterm zone="GTestCase"><primary sortas="TestCase">GTestCase</primary></indexterm><programlisting>typedef struct GTestCase  GTestCase;
</programlisting>
<para>
An opaque structure representing a test case.
</para></refsect2>
<refsect2 id="GTestSuite" role="typedef">
<title>GTestSuite</title>
<indexterm zone="GTestSuite"><primary sortas="TestSuite">GTestSuite</primary></indexterm><programlisting>typedef struct GTestSuite GTestSuite;
</programlisting>
<para>
An opaque structure representing a test suite.
</para></refsect2>
<refsect2 id="g-test-create-case" role="function" condition="since:2.16">
<title>g_test_create_case ()</title>
<indexterm zone="g-test-create-case" role="2.16"><primary sortas="test_create_case">g_test_create_case</primary></indexterm><programlisting><link linkend="GTestCase">GTestCase</link>*          g_test_create_case                  (const <link linkend="char">char</link> *test_name,
                                                         <link linkend="gsize">gsize</link> data_size,
                                                         <link linkend="gconstpointer">gconstpointer</link> test_data,
                                                         <link linkend="void">void</link> (data_setupvoid) (),
                                                         <link linkend="void">void</link> (data_testvoid) (),
                                                         <link linkend="void">void</link> (data_teardownvoid) ());</programlisting>
<para>
Create a new <link linkend="GTestCase"><type>GTestCase</type></link>, named <parameter>test_name</parameter>, this API is fairly
low level, calling <link linkend="g-test-add"><function>g_test_add()</function></link> or <link linkend="g-test-add-func"><function>g_test_add_func()</function></link> is preferable.
When this test is executed, a fixture structure of size <parameter>data_size</parameter>
will be allocated and filled with 0s. Then <link linkend="data-setup"><function>data_setup()</function></link> is called
to initialize the fixture. After fixture setup, the actual test
function <link linkend="data-test"><function>data_test()</function></link> is called. Once the test run completed, the
fixture structure is torn down  by calling <link linkend="data-teardown"><function>data_teardown()</function></link> and
after that the memory is released.
</para>
<para>
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, <link linkend="g-test-create-case"><function>g_test_create_case()</function></link> will be
called with the same fixture, but varying <parameter>test_name</parameter> and
<parameter>data_test</parameter> arguments.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>test_name</parameter>&#160;:</term>
<listitem><simpara>     the name for the test case
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data_size</parameter>&#160;:</term>
<listitem><simpara>     the size of the fixture data structure
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_data</parameter>&#160;:</term>
<listitem><simpara>     test data argument for the test functions
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data_setup</parameter>&#160;:</term>
<listitem><simpara>    the function to set up the fixture data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data_test</parameter>&#160;:</term>
<listitem><simpara>     the actual test function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data_teardown</parameter>&#160;:</term>
<listitem><simpara> the function to teardown the fixture data
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated <link linkend="GTestCase"><type>GTestCase</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-create-suite" role="function" condition="since:2.16">
<title>g_test_create_suite ()</title>
<indexterm zone="g-test-create-suite" role="2.16"><primary sortas="test_create_suite">g_test_create_suite</primary></indexterm><programlisting><link linkend="GTestSuite">GTestSuite</link>*         g_test_create_suite                 (const <link linkend="char">char</link> *suite_name);</programlisting>
<para>
Create a new test suite with the name <parameter>suite_name</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>suite_name</parameter>&#160;:</term>
<listitem><simpara> a name for the suite
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly allocated <link linkend="GTestSuite"><type>GTestSuite</type></link> instance.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-get-root" role="function" condition="since:2.16">
<title>g_test_get_root ()</title>
<indexterm zone="g-test-get-root" role="2.16"><primary sortas="test_get_root">g_test_get_root</primary></indexterm><programlisting><link linkend="GTestSuite">GTestSuite</link>*         g_test_get_root                     (void);</programlisting>
<para>
Get the toplevel test suite for the test path API.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the toplevel <link linkend="GTestSuite"><type>GTestSuite</type></link>

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-suite-add" role="function" condition="since:2.16">
<title>g_test_suite_add ()</title>
<indexterm zone="g-test-suite-add" role="2.16"><primary sortas="test_suite_add">g_test_suite_add</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_suite_add                    (<link linkend="GTestSuite">GTestSuite</link> *suite,
                                                         <link linkend="GTestCase">GTestCase</link> *test_case);</programlisting>
<para>
Adds <parameter>test_case</parameter> to <parameter>suite</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>suite</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTestSuite"><type>GTestSuite</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>test_case</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTestCase"><type>GTestCase</type></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-suite-add-suite" role="function" condition="since:2.16">
<title>g_test_suite_add_suite ()</title>
<indexterm zone="g-test-suite-add-suite" role="2.16"><primary sortas="test_suite_add_suite">g_test_suite_add_suite</primary></indexterm><programlisting><link linkend="void">void</link>                g_test_suite_add_suite              (<link linkend="GTestSuite">GTestSuite</link> *suite,
                                                         <link linkend="GTestSuite">GTestSuite</link> *nestedsuite);</programlisting>
<para>
Adds <parameter>nestedsuite</parameter> to <parameter>suite</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>suite</parameter>&#160;:</term>
<listitem><simpara>       a <link linkend="GTestSuite"><type>GTestSuite</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nestedsuite</parameter>&#160;:</term>
<listitem><simpara> another <link linkend="GTestSuite"><type>GTestSuite</type></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-test-run-suite" role="function" condition="since:2.16">
<title>g_test_run_suite ()</title>
<indexterm zone="g-test-run-suite" role="2.16"><primary sortas="test_run_suite">g_test_run_suite</primary></indexterm><programlisting><link linkend="int">int</link>                 g_test_run_suite                    (<link linkend="GTestSuite">GTestSuite</link> *suite);</programlisting>
<para>
Execute the tests within <parameter>suite</parameter> and all nested <link linkend="GTestSuites"><type>GTestSuites</type></link>.
The test suites to be executed 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><parameter>suite</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTestSuite"><type>GTestSuite</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 on success

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>

</refsect1>



<refsect1 id="glib-Testing.see-also">
<title>See Also</title>
<para>
<link linkend="gtester">gtester</link>,
<link linkend="gtester-report">gtester-report</link>
</para>
</refsect1>

</refentry>
