docs/reference/glib/html/glib-Testing.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Testing</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-utilities.html" title="GLib Utilities">
   9 <link rel="prev" href="glib-Bookmark-file-parser.html" title="Bookmark file parser">
  10 <link rel="next" href="glib-UNIX-specific-utilities-and-integration.html" title="UNIX-specific utilities and integration">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Bookmark-file-parser.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-UNIX-specific-utilities-and-integration.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Testing.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Testing.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Testing"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Testing.top_of_page"></a>Testing</span></h2>
  34 <p>Testing — a test framework</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="glib-Testing.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42
  43 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-minimized-result" title="g_test_minimized_result ()">g_test_minimized_result</a>             (<em class="parameter"><code><span class="type">double</span> minimized_quantity</code></em>,
  44                                                          <em class="parameter"><code>const <span class="type">char</span> *format</code></em>,
  45                                                          <em class="parameter"><code>...</code></em>);
  46 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-maximized-result" title="g_test_maximized_result ()">g_test_maximized_result</a>             (<em class="parameter"><code><span class="type">double</span> maximized_quantity</code></em>,
  47                                                          <em class="parameter"><code>const <span class="type">char</span> *format</code></em>,
  48                                                          <em class="parameter"><code>...</code></em>);
  49 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-init" title="g_test_init ()">g_test_init</a>                         (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
  50                                                          <em class="parameter"><code><span class="type">char</span> ***argv</code></em>,
  51                                                          <em class="parameter"><code>...</code></em>);
  52 #define             <a class="link" href="glib-Testing.html#g-test-quick" title="g_test_quick">g_test_quick</a>
  53 #define             <a class="link" href="glib-Testing.html#g-test-slow" title="g_test_slow">g_test_slow</a>
  54 #define             <a class="link" href="glib-Testing.html#g-test-thorough" title="g_test_thorough">g_test_thorough</a>
  55 #define             <a class="link" href="glib-Testing.html#g-test-perf" title="g_test_perf">g_test_perf</a>
  56 #define             <a class="link" href="glib-Testing.html#g-test-verbose" title="g_test_verbose">g_test_verbose</a>
  57 #define             <a class="link" href="glib-Testing.html#g-test-undefined" title="g_test_undefined">g_test_undefined</a>
  58 #define             <a class="link" href="glib-Testing.html#g-test-quiet" title="g_test_quiet">g_test_quiet</a>
  59 <span class="returnvalue">int</span>                 <a class="link" href="glib-Testing.html#g-test-run" title="g_test_run ()">g_test_run</a>                          (<em class="parameter"><code><span class="type">void</span></code></em>);
  60 <span class="returnvalue">void</span>                (<a class="link" href="glib-Testing.html#GTestFunc" title="GTestFunc ()">*GTestFunc</a>)                        (<em class="parameter"><code><span class="type">void</span></code></em>);
  61 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-add-func" title="g_test_add_func ()">g_test_add_func</a>                     (<em class="parameter"><code>const <span class="type">char</span> *testpath</code></em>,
  62                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestFunc" title="GTestFunc ()"><span class="type">GTestFunc</span></a> test_func</code></em>);
  63 <span class="returnvalue">void</span>                (<a class="link" href="glib-Testing.html#GTestDataFunc" title="GTestDataFunc ()">*GTestDataFunc</a>)                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> user_data</code></em>);
  64 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-add-data-func" title="g_test_add_data_func ()">g_test_add_data_func</a>                (<em class="parameter"><code>const <span class="type">char</span> *testpath</code></em>,
  65                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> test_data</code></em>,
  66                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestDataFunc" title="GTestDataFunc ()"><span class="type">GTestDataFunc</span></a> test_func</code></em>);
  67 #define             <a class="link" href="glib-Testing.html#g-test-add" title="g_test_add()">g_test_add</a>                          (testpath,
  68                                                          Fixture,
  69                                                          tdata,
  70                                                          fsetup,
  71                                                          ftest,
  72                                                          fteardown)
  73 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-fail" title="g_test_fail ()">g_test_fail</a>                         (<em class="parameter"><code><span class="type">void</span></code></em>);
  74 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-message" title="g_test_message ()">g_test_message</a>                      (<em class="parameter"><code>const <span class="type">char</span> *format</code></em>,
  75                                                          <em class="parameter"><code>...</code></em>);
  76 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-bug-base" title="g_test_bug_base ()">g_test_bug_base</a>                     (<em class="parameter"><code>const <span class="type">char</span> *uri_pattern</code></em>);
  77 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-bug" title="g_test_bug ()">g_test_bug</a>                          (<em class="parameter"><code>const <span class="type">char</span> *bug_uri_snippet</code></em>);
  78 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            (<a class="link" href="glib-Testing.html#GTestLogFatalFunc" title="GTestLogFatalFunc ()">*GTestLogFatalFunc</a>)                (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *log_domain</code></em>,
  79                                                          <em class="parameter"><code><a class="link" href="glib-Message-Logging.html#GLogLevelFlags" title="enum GLogLevelFlags"><span class="type">GLogLevelFlags</span></a> log_level</code></em>,
  80                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *message</code></em>,
  81                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  82 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-log-set-fatal-handler" title="g_test_log_set_fatal_handler ()">g_test_log_set_fatal_handler</a>        (<em class="parameter"><code><a class="link" href="glib-Testing.html#GTestLogFatalFunc" title="GTestLogFatalFunc ()"><span class="type">GTestLogFatalFunc</span></a> log_func</code></em>,
  83                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  84 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-timer-start" title="g_test_timer_start ()">g_test_timer_start</a>                  (<em class="parameter"><code><span class="type">void</span></code></em>);
  85 <span class="returnvalue">double</span>              <a class="link" href="glib-Testing.html#g-test-timer-elapsed" title="g_test_timer_elapsed ()">g_test_timer_elapsed</a>                (<em class="parameter"><code><span class="type">void</span></code></em>);
  86 <span class="returnvalue">double</span>              <a class="link" href="glib-Testing.html#g-test-timer-last" title="g_test_timer_last ()">g_test_timer_last</a>                   (<em class="parameter"><code><span class="type">void</span></code></em>);
  87 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-queue-free" title="g_test_queue_free ()">g_test_queue_free</a>                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> gfree_pointer</code></em>);
  88 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-queue-destroy" title="g_test_queue_destroy ()">g_test_queue_destroy</a>                (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> destroy_func</code></em>,
  89                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> destroy_data</code></em>);
  90 #define             <a class="link" href="glib-Testing.html#g-test-queue-unref" title="g_test_queue_unref()">g_test_queue_unref</a>                  (gobject)
  91 enum                <a class="link" href="glib-Testing.html#GTestTrapFlags" title="enum GTestTrapFlags">GTestTrapFlags</a>;
  92 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()">g_test_trap_fork</a>                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> usec_timeout</code></em>,
  93                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestTrapFlags" title="enum GTestTrapFlags"><span class="type">GTestTrapFlags</span></a> test_trap_flags</code></em>);
  94 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Testing.html#g-test-trap-has-passed" title="g_test_trap_has_passed ()">g_test_trap_has_passed</a>              (<em class="parameter"><code><span class="type">void</span></code></em>);
  95 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Testing.html#g-test-trap-reached-timeout" title="g_test_trap_reached_timeout ()">g_test_trap_reached_timeout</a>         (<em class="parameter"><code><span class="type">void</span></code></em>);
  96 #define             <a class="link" href="glib-Testing.html#g-test-trap-assert-passed" title="g_test_trap_assert_passed">g_test_trap_assert_passed</a>
  97 #define             <a class="link" href="glib-Testing.html#g-test-trap-assert-failed" title="g_test_trap_assert_failed">g_test_trap_assert_failed</a>
  98 #define             <a class="link" href="glib-Testing.html#g-test-trap-assert-stdout" title="g_test_trap_assert_stdout()">g_test_trap_assert_stdout</a>           (soutpattern)
  99 #define             <a class="link" href="glib-Testing.html#g-test-trap-assert-stdout-unmatched" title="g_test_trap_assert_stdout_unmatched()">g_test_trap_assert_stdout_unmatched</a> (soutpattern)
 100 #define             <a class="link" href="glib-Testing.html#g-test-trap-assert-stderr" title="g_test_trap_assert_stderr()">g_test_trap_assert_stderr</a>           (serrpattern)
 101 #define             <a class="link" href="glib-Testing.html#g-test-trap-assert-stderr-unmatched" title="g_test_trap_assert_stderr_unmatched()">g_test_trap_assert_stderr_unmatched</a> (serrpattern)
 102 #define             <a class="link" href="glib-Testing.html#g-test-rand-bit" title="g_test_rand_bit">g_test_rand_bit</a>
 103 <a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a>              <a class="link" href="glib-Testing.html#g-test-rand-int" title="g_test_rand_int ()">g_test_rand_int</a>                     (<em class="parameter"><code><span class="type">void</span></code></em>);
 104 <a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a>              <a class="link" href="glib-Testing.html#g-test-rand-int-range" title="g_test_rand_int_range ()">g_test_rand_int_range</a>               (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="type">gint32</span></a> begin</code></em>,
 105                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="type">gint32</span></a> end</code></em>);
 106 <span class="returnvalue">double</span>              <a class="link" href="glib-Testing.html#g-test-rand-double" title="g_test_rand_double ()">g_test_rand_double</a>                  (<em class="parameter"><code><span class="type">void</span></code></em>);
 107 <span class="returnvalue">double</span>              <a class="link" href="glib-Testing.html#g-test-rand-double-range" title="g_test_rand_double_range ()">g_test_rand_double_range</a>            (<em class="parameter"><code><span class="type">double</span> range_start</code></em>,
 108                                                          <em class="parameter"><code><span class="type">double</span> range_end</code></em>);
 109 #define             <a class="link" href="glib-Testing.html#g-assert" title="g_assert()">g_assert</a>                            (expr)
 110 #define             <a class="link" href="glib-Testing.html#g-assert-not-reached" title="g_assert_not_reached">g_assert_not_reached</a>
 111 #define             <a class="link" href="glib-Testing.html#g-assert-cmpstr" title="g_assert_cmpstr()">g_assert_cmpstr</a>                     (s1,
 112                                                          cmp,
 113                                                          s2)
 114 #define             <a class="link" href="glib-Testing.html#g-assert-cmpint" title="g_assert_cmpint()">g_assert_cmpint</a>                     (n1,
 115                                                          cmp,
 116                                                          n2)
 117 #define             <a class="link" href="glib-Testing.html#g-assert-cmpuint" title="g_assert_cmpuint()">g_assert_cmpuint</a>                    (n1,
 118                                                          cmp,
 119                                                          n2)
 120 #define             <a class="link" href="glib-Testing.html#g-assert-cmphex" title="g_assert_cmphex()">g_assert_cmphex</a>                     (n1,
 121                                                          cmp,
 122                                                          n2)
 123 #define             <a class="link" href="glib-Testing.html#g-assert-cmpfloat" title="g_assert_cmpfloat()">g_assert_cmpfloat</a>                   (n1,
 124                                                          cmp,
 125                                                          n2)
 126 #define             <a class="link" href="glib-Testing.html#g-assert-no-error" title="g_assert_no_error()">g_assert_no_error</a>                   (err)
 127 #define             <a class="link" href="glib-Testing.html#g-assert-error" title="g_assert_error()">g_assert_error</a>                      (err,
 128                                                          dom,
 129                                                          c)
 130 typedef             <a class="link" href="glib-Testing.html#GTestCase" title="GTestCase">GTestCase</a>;
 131 typedef             <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite">GTestSuite</a>;
 132 <span class="returnvalue">void</span>                (<a class="link" href="glib-Testing.html#GTestFixtureFunc" title="GTestFixtureFunc ()">*GTestFixtureFunc</a>)                 (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> fixture</code></em>,
 133                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> user_data</code></em>);
 134 <a class="link" href="glib-Testing.html#GTestCase" title="GTestCase"><span class="returnvalue">GTestCase</span></a> *         <a class="link" href="glib-Testing.html#g-test-create-case" title="g_test_create_case ()">g_test_create_case</a>                  (<em class="parameter"><code>const <span class="type">char</span> *test_name</code></em>,
 135                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> data_size</code></em>,
 136                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> test_data</code></em>,
 137                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestFixtureFunc" title="GTestFixtureFunc ()"><span class="type">GTestFixtureFunc</span></a> data_setup</code></em>,
 138                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestFixtureFunc" title="GTestFixtureFunc ()"><span class="type">GTestFixtureFunc</span></a> data_test</code></em>,
 139                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestFixtureFunc" title="GTestFixtureFunc ()"><span class="type">GTestFixtureFunc</span></a> data_teardown</code></em>);
 140 <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="returnvalue">GTestSuite</span></a> *        <a class="link" href="glib-Testing.html#g-test-create-suite" title="g_test_create_suite ()">g_test_create_suite</a>                 (<em class="parameter"><code>const <span class="type">char</span> *suite_name</code></em>);
 141 <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="returnvalue">GTestSuite</span></a> *        <a class="link" href="glib-Testing.html#g-test-get-root" title="g_test_get_root ()">g_test_get_root</a>                     (<em class="parameter"><code><span class="type">void</span></code></em>);
 142 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-suite-add" title="g_test_suite_add ()">g_test_suite_add</a>                    (<em class="parameter"><code><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> *suite</code></em>,
 143                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestCase" title="GTestCase"><span class="type">GTestCase</span></a> *test_case</code></em>);
 144 <span class="returnvalue">void</span>                <a class="link" href="glib-Testing.html#g-test-suite-add-suite" title="g_test_suite_add_suite ()">g_test_suite_add_suite</a>              (<em class="parameter"><code><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> *suite</code></em>,
 145                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> *nestedsuite</code></em>);
 146 <span class="returnvalue">int</span>                 <a class="link" href="glib-Testing.html#g-test-run-suite" title="g_test_run_suite ()">g_test_run_suite</a>                    (<em class="parameter"><code><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> *suite</code></em>);
 147 </pre>
 148 </div>
 149 <div class="refsect1">
 150 <a name="glib-Testing.description"></a><h2>Description</h2>
 151 <p>
 152 GLib provides a framework for writing and maintaining unit tests
 153 in parallel to the code they are testing. The API is designed according
 154 to established concepts found in the other test frameworks (JUnit, NUnit,
 155 RUnit), which in turn is based on smalltalk unit testing concepts.
 156 </p>
 157 <p>
 158 </p>
 159 <div class="variablelist"><table border="0">
 160 <col align="left" valign="top">
 161 <tbody>
 162 <tr>
 163 <td><p><span class="term">Test case</span></p></td>
 164 <td>Tests (test methods) are grouped together with their
 165       fixture into test cases.</td>
 166 </tr>
 167 <tr>
 168 <td><p><span class="term">Fixture</span></p></td>
 169 <td>A test fixture consists of fixture data and setup and
 170       teardown methods to establish the environment for the test
 171       functions. We use fresh fixtures, i.e. fixtures are newly set
 172       up and torn down around each test invocation to avoid dependencies
 173       between tests.</td>
 174 </tr>
 175 <tr>
 176 <td><p><span class="term">Test suite</span></p></td>
 177 <td>Test cases can be grouped into test suites, to allow
 178       subsets of the available tests to be run. Test suites can be
 179       grouped into other test suites as well.</td>
 180 </tr>
 181 </tbody>
 182 </table></div>
 183 <p>
 184 The API is designed to handle creation and registration of test suites
 185 and test cases implicitly. A simple call like
 186 </p>
 187 <div class="informalexample"><pre class="programlisting">
 188   g_test_add_func ("/misc/assertions", test_assertions);
 189 </pre></div>
 190 <p>
 191 creates a test suite called "misc" with a single test case named
 192 "assertions", which consists of running the test_assertions function.
 193 </p>
 194 <p>
 195 In addition to the traditional <a class="link" href="glib-Testing.html#g-assert" title="g_assert()"><code class="function">g_assert()</code></a>, the test framework provides
 196 an extended set of assertions for string and numerical comparisons:
 197 <a class="link" href="glib-Testing.html#g-assert-cmpfloat" title="g_assert_cmpfloat()"><code class="function">g_assert_cmpfloat()</code></a>, <a class="link" href="glib-Testing.html#g-assert-cmpint" title="g_assert_cmpint()"><code class="function">g_assert_cmpint()</code></a>, <a class="link" href="glib-Testing.html#g-assert-cmpuint" title="g_assert_cmpuint()"><code class="function">g_assert_cmpuint()</code></a>,
 198 <a class="link" href="glib-Testing.html#g-assert-cmphex" title="g_assert_cmphex()"><code class="function">g_assert_cmphex()</code></a>, <a class="link" href="glib-Testing.html#g-assert-cmpstr" title="g_assert_cmpstr()"><code class="function">g_assert_cmpstr()</code></a>. The advantage of these variants
 199 over plain <a class="link" href="glib-Testing.html#g-assert" title="g_assert()"><code class="function">g_assert()</code></a> is that the assertion messages can be more
 200 elaborate, and include the values of the compared entities.
 201 </p>
 202 <p>
 203 GLib ships with two utilities called gtester and gtester-report to
 204 facilitate running tests and producing nicely formatted test reports.
 205 </p>
 206 </div>
 207 <div class="refsect1">
 208 <a name="glib-Testing.details"></a><h2>Details</h2>
 209 <div class="refsect2">
 210 <a name="g-test-minimized-result"></a><h3>g_test_minimized_result ()</h3>
 211 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_minimized_result             (<em class="parameter"><code><span class="type">double</span> minimized_quantity</code></em>,
 212                                                          <em class="parameter"><code>const <span class="type">char</span> *format</code></em>,
 213                                                          <em class="parameter"><code>...</code></em>);</pre>
 214 <p>
 215 Report the result of a performance or measurement test.
 216 The test should generally strive to minimize the reported
 217 quantities (smaller values are better than larger ones),
 218 this and <em class="parameter"><code>minimized_quantity</code></em> can determine sorting
 219 order for test result reports.
 220 </p>
 221 <div class="variablelist"><table border="0">
 222 <col align="left" valign="top">
 223 <tbody>
 224 <tr>
 225 <td><p><span class="term"><em class="parameter"><code>minimized_quantity</code></em> :</span></p></td>
 226 <td>the reported value</td>
 227 </tr>
 228 <tr>
 229 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 230 <td>the format string of the report message</td>
 231 </tr>
 232 <tr>
 233 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 234 <td>arguments to pass to the <code class="function">printf()</code> function</td>
 235 </tr>
 236 </tbody>
 237 </table></div>
 238 <p class="since">Since 2.16</p>
 239 </div>
 240 <hr>
 241 <div class="refsect2">
 242 <a name="g-test-maximized-result"></a><h3>g_test_maximized_result ()</h3>
 243 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_maximized_result             (<em class="parameter"><code><span class="type">double</span> maximized_quantity</code></em>,
 244                                                          <em class="parameter"><code>const <span class="type">char</span> *format</code></em>,
 245                                                          <em class="parameter"><code>...</code></em>);</pre>
 246 <p>
 247 Report the result of a performance or measurement test.
 248 The test should generally strive to maximize the reported
 249 quantities (larger values are better than smaller ones),
 250 this and <em class="parameter"><code>maximized_quantity</code></em> can determine sorting
 251 order for test result reports.
 252 </p>
 253 <div class="variablelist"><table border="0">
 254 <col align="left" valign="top">
 255 <tbody>
 256 <tr>
 257 <td><p><span class="term"><em class="parameter"><code>maximized_quantity</code></em> :</span></p></td>
 258 <td>the reported value</td>
 259 </tr>
 260 <tr>
 261 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 262 <td>the format string of the report message</td>
 263 </tr>
 264 <tr>
 265 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 266 <td>arguments to pass to the <code class="function">printf()</code> function</td>
 267 </tr>
 268 </tbody>
 269 </table></div>
 270 <p class="since">Since 2.16</p>
 271 </div>
 272 <hr>
 273 <div class="refsect2">
 274 <a name="g-test-init"></a><h3>g_test_init ()</h3>
 275 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_init                         (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
 276                                                          <em class="parameter"><code><span class="type">char</span> ***argv</code></em>,
 277                                                          <em class="parameter"><code>...</code></em>);</pre>
 278 <p>
 279 Initialize the GLib testing framework, e.g. by seeding the
 280 test random number generator, the name for <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-prgname" title="g_get_prgname ()"><code class="function">g_get_prgname()</code></a>
 281 and parsing test related command line args.
 282 So far, the following arguments are understood:
 283 </p>
 284 <div class="variablelist"><table border="0">
 285 <col align="left" valign="top">
 286 <tbody>
 287 <tr>
 288 <td><p><span class="term"><code class="option">-l</code></span></p></td>
 289 <td><p>
 290       list test cases available in a test executable.
 291     </p></td>
 292 </tr>
 293 <tr>
 294 <td><p><span class="term"><code class="option">--seed=<em class="replaceable"><code>RANDOMSEED</code></em></code></span></p></td>
 295 <td><p>
 296       provide a random seed to reproduce test runs using random numbers.
 297     </p></td>
 298 </tr>
 299 <tr>
 300 <td><p><span class="term"><code class="option">--verbose</code></span></p></td>
 301 <td><p>run tests verbosely.</p></td>
 302 </tr>
 303 <tr>
 304 <td><p><span class="term"><code class="option">-q</code>, <code class="option">--quiet</code></span></p></td>
 305 <td><p>run tests quietly.</p></td>
 306 </tr>
 307 <tr>
 308 <td><p><span class="term"><code class="option">-p <em class="replaceable"><code>TESTPATH</code></em></code></span></p></td>
 309 <td><p>
 310         execute all tests matching <em class="replaceable"><code>TESTPATH</code></em>.
 311       </p></td>
 312 </tr>
 313 <tr>
 314 <td><p><span class="term"><code class="option">-m {perf|slow|thorough|quick|undefined|no-undefined}</code></span></p></td>
 315 <td>
 316 <p>
 317         execute tests according to these test modes:
 318         </p>
 319 <div class="variablelist"><table border="0">
 320 <col align="left" valign="top">
 321 <tbody>
 322 <tr>
 323 <td><p><span class="term">perf</span></p></td>
 324 <td><p>
 325               performance tests, may take long and report results.
 326             </p></td>
 327 </tr>
 328 <tr>
 329 <td><p><span class="term">slow, thorough</span></p></td>
 330 <td><p>
 331               slow and thorough tests, may take quite long and
 332               maximize coverage.
 333             </p></td>
 334 </tr>
 335 <tr>
 336 <td><p><span class="term">quick</span></p></td>
 337 <td><p>
 338               quick tests, should run really quickly and give good coverage.
 339             </p></td>
 340 </tr>
 341 <tr>
 342 <td><p><span class="term">undefined</span></p></td>
 343 <td><p>
 344               tests for undefined behaviour, may provoke programming errors
 345               under <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a> to check that appropriate assertions
 346               or warnings are given
 347             </p></td>
 348 </tr>
 349 <tr>
 350 <td><p><span class="term">no-undefined</span></p></td>
 351 <td><p>
 352               avoid tests for undefined behaviour
 353             </p></td>
 354 </tr>
 355 </tbody>
 356 </table></div>
 357 <p>
 358       </p>
 359 </td>
 360 </tr>
 361 <tr>
 362 <td><p><span class="term"><code class="option">--debug-log</code></span></p></td>
 363 <td><p>debug test logging output.</p></td>
 364 </tr>
 365 <tr>
 366 <td><p><span class="term"><code class="option">-k</code>, <code class="option">--keep-going</code></span></p></td>
 367 <td><p>gtester-specific argument.</p></td>
 368 </tr>
 369 <tr>
 370 <td><p><span class="term"><code class="option">--GTestLogFD <em class="replaceable"><code>N</code></em></code></span></p></td>
 371 <td><p>gtester-specific argument.</p></td>
 372 </tr>
 373 <tr>
 374 <td><p><span class="term"><code class="option">--GTestSkipCount <em class="replaceable"><code>N</code></em></code></span></p></td>
 375 <td><p>gtester-specific argument.</p></td>
 376 </tr>
 377 </tbody>
 378 </table></div>
 379 <p>
 380 </p>
 381 <div class="variablelist"><table border="0">
 382 <col align="left" valign="top">
 383 <tbody>
 384 <tr>
 385 <td><p><span class="term"><em class="parameter"><code>argc</code></em> :</span></p></td>
 386 <td>Address of the <em class="parameter"><code>argc</code></em> parameter of the <code class="function">main()</code> function.
 387 Changed if any arguments were handled.</td>
 388 </tr>
 389 <tr>
 390 <td><p><span class="term"><em class="parameter"><code>argv</code></em> :</span></p></td>
 391 <td>Address of the <em class="parameter"><code>argv</code></em> parameter of <code class="function">main()</code>.
 392 Any parameters understood by <a class="link" href="glib-Testing.html#g-test-init" title="g_test_init ()"><code class="function">g_test_init()</code></a> stripped before return.</td>
 393 </tr>
 394 <tr>
 395 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 396 <td>Reserved for future extension. Currently, you must pass <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.</td>
 397 </tr>
 398 </tbody>
 399 </table></div>
 400 <p class="since">Since 2.16</p>
 401 </div>
 402 <hr>
 403 <div class="refsect2">
 404 <a name="g-test-quick"></a><h3>g_test_quick</h3>
 405 <pre class="programlisting">#define             g_test_quick()</pre>
 406 <p>
 407 Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if tests are run in quick mode.
 408 Exactly one of <a class="link" href="glib-Testing.html#g-test-quick" title="g_test_quick"><code class="function">g_test_quick()</code></a> and <a class="link" href="glib-Testing.html#g-test-slow" title="g_test_slow"><code class="function">g_test_slow()</code></a> is active in any run;
 409 there is no "medium speed".
 410 </p>
 411 <div class="variablelist"><table border="0">
 412 <col align="left" valign="top">
 413 <tbody><tr>
 414 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 415 <td>
 416 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if in quick mode</td>
 417 </tr></tbody>
 418 </table></div>
 419 </div>
 420 <hr>
 421 <div class="refsect2">
 422 <a name="g-test-slow"></a><h3>g_test_slow</h3>
 423 <pre class="programlisting">#define             g_test_slow()</pre>
 424 <p>
 425 Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if tests are run in slow mode.
 426 Exactly one of <a class="link" href="glib-Testing.html#g-test-quick" title="g_test_quick"><code class="function">g_test_quick()</code></a> and <a class="link" href="glib-Testing.html#g-test-slow" title="g_test_slow"><code class="function">g_test_slow()</code></a> is active in any run;
 427 there is no "medium speed".
 428 </p>
 429 <div class="variablelist"><table border="0">
 430 <col align="left" valign="top">
 431 <tbody><tr>
 432 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 433 <td>the opposite of <a class="link" href="glib-Testing.html#g-test-quick" title="g_test_quick"><code class="function">g_test_quick()</code></a>
 434 </td>
 435 </tr></tbody>
 436 </table></div>
 437 </div>
 438 <hr>
 439 <div class="refsect2">
 440 <a name="g-test-thorough"></a><h3>g_test_thorough</h3>
 441 <pre class="programlisting">#define             g_test_thorough()</pre>
 442 <p>
 443 Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if tests are run in thorough mode, equivalent to
 444 <a class="link" href="glib-Testing.html#g-test-slow" title="g_test_slow"><code class="function">g_test_slow()</code></a>.
 445 </p>
 446 <div class="variablelist"><table border="0">
 447 <col align="left" valign="top">
 448 <tbody><tr>
 449 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 450 <td>the same thing as <a class="link" href="glib-Testing.html#g-test-slow" title="g_test_slow"><code class="function">g_test_slow()</code></a>
 451 </td>
 452 </tr></tbody>
 453 </table></div>
 454 </div>
 455 <hr>
 456 <div class="refsect2">
 457 <a name="g-test-perf"></a><h3>g_test_perf</h3>
 458 <pre class="programlisting">#define             g_test_perf()</pre>
 459 <p>
 460 Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if tests are run in performance mode.
 461 </p>
 462 <div class="variablelist"><table border="0">
 463 <col align="left" valign="top">
 464 <tbody><tr>
 465 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 466 <td>
 467 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if in performance mode</td>
 468 </tr></tbody>
 469 </table></div>
 470 </div>
 471 <hr>
 472 <div class="refsect2">
 473 <a name="g-test-verbose"></a><h3>g_test_verbose</h3>
 474 <pre class="programlisting">#define             g_test_verbose()</pre>
 475 <p>
 476 Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if tests are run in verbose mode.
 477 The default is neither <a class="link" href="glib-Testing.html#g-test-verbose" title="g_test_verbose"><code class="function">g_test_verbose()</code></a> nor <a class="link" href="glib-Testing.html#g-test-quiet" title="g_test_quiet"><code class="function">g_test_quiet()</code></a>.
 478 </p>
 479 <div class="variablelist"><table border="0">
 480 <col align="left" valign="top">
 481 <tbody><tr>
 482 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 483 <td>
 484 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if in verbose mode</td>
 485 </tr></tbody>
 486 </table></div>
 487 </div>
 488 <hr>
 489 <div class="refsect2">
 490 <a name="g-test-undefined"></a><h3>g_test_undefined</h3>
 491 <pre class="programlisting">#define             g_test_undefined()</pre>
 492 <p>
 493 Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if tests may provoke assertions and other formally-undefined
 494 behaviour under <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>, to verify that appropriate warnings
 495 are given. It can be useful to turn this off if running tests under
 496 valgrind.
 497 </p>
 498 <div class="variablelist"><table border="0">
 499 <col align="left" valign="top">
 500 <tbody><tr>
 501 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 502 <td>
 503 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if tests may provoke programming errors</td>
 504 </tr></tbody>
 505 </table></div>
 506 </div>
 507 <hr>
 508 <div class="refsect2">
 509 <a name="g-test-quiet"></a><h3>g_test_quiet</h3>
 510 <pre class="programlisting">#define             g_test_quiet()</pre>
 511 <p>
 512 Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if tests are run in quiet mode.
 513 The default is neither <a class="link" href="glib-Testing.html#g-test-verbose" title="g_test_verbose"><code class="function">g_test_verbose()</code></a> nor <a class="link" href="glib-Testing.html#g-test-quiet" title="g_test_quiet"><code class="function">g_test_quiet()</code></a>.
 514 </p>
 515 <div class="variablelist"><table border="0">
 516 <col align="left" valign="top">
 517 <tbody><tr>
 518 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 519 <td>
 520 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if in quiet mode</td>
 521 </tr></tbody>
 522 </table></div>
 523 </div>
 524 <hr>
 525 <div class="refsect2">
 526 <a name="g-test-run"></a><h3>g_test_run ()</h3>
 527 <pre class="programlisting"><span class="returnvalue">int</span>                 g_test_run                          (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 528 <p>
 529 Runs all tests under the toplevel suite which can be retrieved
 530 with <a class="link" href="glib-Testing.html#g-test-get-root" title="g_test_get_root ()"><code class="function">g_test_get_root()</code></a>. Similar to <a class="link" href="glib-Testing.html#g-test-run-suite" title="g_test_run_suite ()"><code class="function">g_test_run_suite()</code></a>, the test
 531 cases to be run are filtered according to
 532 test path arguments (-p <em class="replaceable"><code>testpath</code></em>) as
 533 parsed by <a class="link" href="glib-Testing.html#g-test-init" title="g_test_init ()"><code class="function">g_test_init()</code></a>.
 534 <a class="link" href="glib-Testing.html#g-test-run-suite" title="g_test_run_suite ()"><code class="function">g_test_run_suite()</code></a> or <a class="link" href="glib-Testing.html#g-test-run" title="g_test_run ()"><code class="function">g_test_run()</code></a> may only be called once
 535 in a program.
 536 </p>
 537 <div class="variablelist"><table border="0">
 538 <col align="left" valign="top">
 539 <tbody><tr>
 540 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 541 <td>0 on success</td>
 542 </tr></tbody>
 543 </table></div>
 544 <p class="since">Since 2.16</p>
 545 </div>
 546 <hr>
 547 <div class="refsect2">
 548 <a name="GTestFunc"></a><h3>GTestFunc ()</h3>
 549 <pre class="programlisting"><span class="returnvalue">void</span>                (*GTestFunc)                        (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 550 <p>
 551 The type used for test case functions.
 552 </p>
 553 <p class="since">Since 2.28</p>
 554 </div>
 555 <hr>
 556 <div class="refsect2">
 557 <a name="g-test-add-func"></a><h3>g_test_add_func ()</h3>
 558 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_add_func                     (<em class="parameter"><code>const <span class="type">char</span> *testpath</code></em>,
 559                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestFunc" title="GTestFunc ()"><span class="type">GTestFunc</span></a> test_func</code></em>);</pre>
 560 <p>
 561 Create a new test case, similar to <a class="link" href="glib-Testing.html#g-test-create-case" title="g_test_create_case ()"><code class="function">g_test_create_case()</code></a>. However
 562 the test is assumed to use no fixture, and test suites are automatically
 563 created on the fly and added to the root fixture, based on the
 564 slash-separated portions of <em class="parameter"><code>testpath</code></em>.
 565 </p>
 566 <div class="variablelist"><table border="0">
 567 <col align="left" valign="top">
 568 <tbody>
 569 <tr>
 570 <td><p><span class="term"><em class="parameter"><code>testpath</code></em> :</span></p></td>
 571 <td>/-separated test case path name for the test.</td>
 572 </tr>
 573 <tr>
 574 <td><p><span class="term"><em class="parameter"><code>test_func</code></em> :</span></p></td>
 575 <td>The test function to invoke for this test.</td>
 576 </tr>
 577 </tbody>
 578 </table></div>
 579 <p class="since">Since 2.16</p>
 580 </div>
 581 <hr>
 582 <div class="refsect2">
 583 <a name="GTestDataFunc"></a><h3>GTestDataFunc ()</h3>
 584 <pre class="programlisting"><span class="returnvalue">void</span>                (*GTestDataFunc)                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> user_data</code></em>);</pre>
 585 <p>
 586 The type used for test case functions that take an extra pointer
 587 argument.
 588 </p>
 589 <div class="variablelist"><table border="0">
 590 <col align="left" valign="top">
 591 <tbody><tr>
 592 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 593 <td>the data provided when registering the test</td>
 594 </tr></tbody>
 595 </table></div>
 596 <p class="since">Since 2.28</p>
 597 </div>
 598 <hr>
 599 <div class="refsect2">
 600 <a name="g-test-add-data-func"></a><h3>g_test_add_data_func ()</h3>
 601 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_add_data_func                (<em class="parameter"><code>const <span class="type">char</span> *testpath</code></em>,
 602                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> test_data</code></em>,
 603                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestDataFunc" title="GTestDataFunc ()"><span class="type">GTestDataFunc</span></a> test_func</code></em>);</pre>
 604 <p>
 605 Create a new test case, similar to <a class="link" href="glib-Testing.html#g-test-create-case" title="g_test_create_case ()"><code class="function">g_test_create_case()</code></a>. However
 606 the test is assumed to use no fixture, and test suites are automatically
 607 created on the fly and added to the root fixture, based on the
 608 slash-separated portions of <em class="parameter"><code>testpath</code></em>. The <em class="parameter"><code>test_data</code></em> argument
 609 will be passed as first argument to <em class="parameter"><code>test_func</code></em>.
 610 </p>
 611 <div class="variablelist"><table border="0">
 612 <col align="left" valign="top">
 613 <tbody>
 614 <tr>
 615 <td><p><span class="term"><em class="parameter"><code>testpath</code></em> :</span></p></td>
 616 <td>/-separated test case path name for the test.</td>
 617 </tr>
 618 <tr>
 619 <td><p><span class="term"><em class="parameter"><code>test_data</code></em> :</span></p></td>
 620 <td>Test data argument for the test function.</td>
 621 </tr>
 622 <tr>
 623 <td><p><span class="term"><em class="parameter"><code>test_func</code></em> :</span></p></td>
 624 <td>The test function to invoke for this test.</td>
 625 </tr>
 626 </tbody>
 627 </table></div>
 628 <p class="since">Since 2.16</p>
 629 </div>
 630 <hr>
 631 <div class="refsect2">
 632 <a name="g-test-add"></a><h3>g_test_add()</h3>
 633 <pre class="programlisting">#define             g_test_add(testpath, Fixture, tdata, fsetup, ftest, fteardown)</pre>
 634 <p>
 635 Hook up a new test case at <em class="parameter"><code>testpath</code></em>, similar to <a class="link" href="glib-Testing.html#g-test-add-func" title="g_test_add_func ()"><code class="function">g_test_add_func()</code></a>.
 636 A fixture data structure with setup and teardown function may be provided
 637 though, similar to <a class="link" href="glib-Testing.html#g-test-create-case" title="g_test_create_case ()"><code class="function">g_test_create_case()</code></a>.
 638 <a class="link" href="glib-Testing.html#g-test-add" title="g_test_add()"><code class="function">g_test_add()</code></a> is implemented as a macro, so that the <code class="function">fsetup()</code>, <code class="function">ftest()</code> and
 639 <code class="function">fteardown()</code> callbacks can expect a <em class="parameter"><code>Fixture</code></em> pointer as first argument in
 640 a type safe manner.
 641 </p>
 642 <div class="variablelist"><table border="0">
 643 <col align="left" valign="top">
 644 <tbody>
 645 <tr>
 646 <td><p><span class="term"><em class="parameter"><code>testpath</code></em> :</span></p></td>
 647 <td>The test path for a new test case.</td>
 648 </tr>
 649 <tr>
 650 <td><p><span class="term"><em class="parameter"><code>Fixture</code></em> :</span></p></td>
 651 <td>The type of a fixture data structure.</td>
 652 </tr>
 653 <tr>
 654 <td><p><span class="term"><em class="parameter"><code>tdata</code></em> :</span></p></td>
 655 <td>Data argument for the test functions.</td>
 656 </tr>
 657 <tr>
 658 <td><p><span class="term"><em class="parameter"><code>fsetup</code></em> :</span></p></td>
 659 <td>The function to set up the fixture data.</td>
 660 </tr>
 661 <tr>
 662 <td><p><span class="term"><em class="parameter"><code>ftest</code></em> :</span></p></td>
 663 <td>The actual test function.</td>
 664 </tr>
 665 <tr>
 666 <td><p><span class="term"><em class="parameter"><code>fteardown</code></em> :</span></p></td>
 667 <td>The function to tear down the fixture data.</td>
 668 </tr>
 669 </tbody>
 670 </table></div>
 671 <p class="since">Since 2.16</p>
 672 </div>
 673 <hr>
 674 <div class="refsect2">
 675 <a name="g-test-fail"></a><h3>g_test_fail ()</h3>
 676 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_fail                         (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 677 <p>
 678 Indicates that a test failed. This function can be called
 679 multiple times from the same test. You can use this function
 680 if your test failed in a recoverable way.
 681 </p>
 682 <p>
 683 Do not use this function if the failure of a test could cause
 684 other tests to malfunction.
 685 </p>
 686 <p>
 687 Calling this function will not stop the test from running, you
 688 need to return from the test function yourself. So you can
 689 produce additional diagnostic messages or even continue running
 690 the test.
 691 </p>
 692 <p>
 693 If not called from inside a test, this function does nothing.
 694 </p>
 695 <p class="since">Since 2.30</p>
 696 </div>
 697 <hr>
 698 <div class="refsect2">
 699 <a name="g-test-message"></a><h3>g_test_message ()</h3>
 700 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_message                      (<em class="parameter"><code>const <span class="type">char</span> *format</code></em>,
 701                                                          <em class="parameter"><code>...</code></em>);</pre>
 702 <p>
 703 Add a message to the test report.
 704 </p>
 705 <div class="variablelist"><table border="0">
 706 <col align="left" valign="top">
 707 <tbody>
 708 <tr>
 709 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 710 <td>the format string</td>
 711 </tr>
 712 <tr>
 713 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 714 <td>printf-like arguments to <em class="parameter"><code>format</code></em>
 715 </td>
 716 </tr>
 717 </tbody>
 718 </table></div>
 719 <p class="since">Since 2.16</p>
 720 </div>
 721 <hr>
 722 <div class="refsect2">
 723 <a name="g-test-bug-base"></a><h3>g_test_bug_base ()</h3>
 724 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_bug_base                     (<em class="parameter"><code>const <span class="type">char</span> *uri_pattern</code></em>);</pre>
 725 <p>
 726 Specify the base URI for bug reports.
 727 </p>
 728 <p>
 729 The base URI is used to construct bug report messages for
 730 <a class="link" href="glib-Testing.html#g-test-message" title="g_test_message ()"><code class="function">g_test_message()</code></a> when <a class="link" href="glib-Testing.html#g-test-bug" title="g_test_bug ()"><code class="function">g_test_bug()</code></a> is called.
 731 Calling this function outside of a test case sets the
 732 default base URI for all test cases. Calling it from within
 733 a test case changes the base URI for the scope of the test
 734 case only.
 735 Bug URIs are constructed by appending a bug specific URI
 736 portion to <em class="parameter"><code>uri_pattern</code></em>, or by replacing the special string
 737 '%s' within <em class="parameter"><code>uri_pattern</code></em> if that is present.
 738 </p>
 739 <div class="variablelist"><table border="0">
 740 <col align="left" valign="top">
 741 <tbody><tr>
 742 <td><p><span class="term"><em class="parameter"><code>uri_pattern</code></em> :</span></p></td>
 743 <td>the base pattern for bug URIs</td>
 744 </tr></tbody>
 745 </table></div>
 746 <p class="since">Since 2.16</p>
 747 </div>
 748 <hr>
 749 <div class="refsect2">
 750 <a name="g-test-bug"></a><h3>g_test_bug ()</h3>
 751 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_bug                          (<em class="parameter"><code>const <span class="type">char</span> *bug_uri_snippet</code></em>);</pre>
 752 <p>
 753 This function adds a message to test reports that
 754 associates a bug URI with a test case.
 755 Bug URIs are constructed from a base URI set with <a class="link" href="glib-Testing.html#g-test-bug-base" title="g_test_bug_base ()"><code class="function">g_test_bug_base()</code></a>
 756 and <em class="parameter"><code>bug_uri_snippet</code></em>.
 757 </p>
 758 <div class="variablelist"><table border="0">
 759 <col align="left" valign="top">
 760 <tbody><tr>
 761 <td><p><span class="term"><em class="parameter"><code>bug_uri_snippet</code></em> :</span></p></td>
 762 <td>Bug specific bug tracker URI portion.</td>
 763 </tr></tbody>
 764 </table></div>
 765 <p class="since">Since 2.16</p>
 766 </div>
 767 <hr>
 768 <div class="refsect2">
 769 <a name="GTestLogFatalFunc"></a><h3>GTestLogFatalFunc ()</h3>
 770 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            (*GTestLogFatalFunc)                (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *log_domain</code></em>,
 771                                                          <em class="parameter"><code><a class="link" href="glib-Message-Logging.html#GLogLevelFlags" title="enum GLogLevelFlags"><span class="type">GLogLevelFlags</span></a> log_level</code></em>,
 772                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *message</code></em>,
 773                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 774 <p>
 775 Specifies the prototype of fatal log handler functions.
 776 </p>
 777 <div class="variablelist"><table border="0">
 778 <col align="left" valign="top">
 779 <tbody>
 780 <tr>
 781 <td><p><span class="term"><em class="parameter"><code>log_domain</code></em> :</span></p></td>
 782 <td>the log domain of the message</td>
 783 </tr>
 784 <tr>
 785 <td><p><span class="term"><em class="parameter"><code>log_level</code></em> :</span></p></td>
 786 <td>the log level of the message (including the fatal and recursion flags)</td>
 787 </tr>
 788 <tr>
 789 <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
 790 <td>the message to process</td>
 791 </tr>
 792 <tr>
 793 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 794 <td>user data, set in <a class="link" href="glib-Testing.html#g-test-log-set-fatal-handler" title="g_test_log_set_fatal_handler ()"><code class="function">g_test_log_set_fatal_handler()</code></a>
 795 </td>
 796 </tr>
 797 <tr>
 798 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 799 <td>
 800 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the program should abort, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> otherwise</td>
 801 </tr>
 802 </tbody>
 803 </table></div>
 804 <p class="since">Since 2.22</p>
 805 </div>
 806 <hr>
 807 <div class="refsect2">
 808 <a name="g-test-log-set-fatal-handler"></a><h3>g_test_log_set_fatal_handler ()</h3>
 809 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_log_set_fatal_handler        (<em class="parameter"><code><a class="link" href="glib-Testing.html#GTestLogFatalFunc" title="GTestLogFatalFunc ()"><span class="type">GTestLogFatalFunc</span></a> log_func</code></em>,
 810                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 811 <p>
 812 Installs a non-error fatal log handler which can be
 813 used to decide whether log messages which are counted
 814 as fatal abort the program.
 815 </p>
 816 <p>
 817 The use case here is that you are running a test case
 818 that depends on particular libraries or circumstances
 819 and cannot prevent certain known critical or warning
 820 messages. So you install a handler that compares the
 821 domain and message to precisely not abort in such a case.
 822 </p>
 823 <p>
 824 Note that the handler is reset at the beginning of
 825 any test case, so you have to set it inside each test
 826 function which needs the special behavior.
 827 </p>
 828 <p>
 829 This handler has no effect on g_error messages.
 830 </p>
 831 <div class="variablelist"><table border="0">
 832 <col align="left" valign="top">
 833 <tbody>
 834 <tr>
 835 <td><p><span class="term"><em class="parameter"><code>log_func</code></em> :</span></p></td>
 836 <td>the log handler function.</td>
 837 </tr>
 838 <tr>
 839 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 840 <td>data passed to the log handler.</td>
 841 </tr>
 842 </tbody>
 843 </table></div>
 844 <p class="since">Since 2.22</p>
 845 </div>
 846 <hr>
 847 <div class="refsect2">
 848 <a name="g-test-timer-start"></a><h3>g_test_timer_start ()</h3>
 849 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_timer_start                  (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 850 <p>
 851 Start a timing test. Call <a class="link" href="glib-Testing.html#g-test-timer-elapsed" title="g_test_timer_elapsed ()"><code class="function">g_test_timer_elapsed()</code></a> when the task is supposed
 852 to be done. Call this function again to restart the timer.
 853 </p>
 854 <p class="since">Since 2.16</p>
 855 </div>
 856 <hr>
 857 <div class="refsect2">
 858 <a name="g-test-timer-elapsed"></a><h3>g_test_timer_elapsed ()</h3>
 859 <pre class="programlisting"><span class="returnvalue">double</span>              g_test_timer_elapsed                (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 860 <p>
 861 Get the time since the last start of the timer with <a class="link" href="glib-Testing.html#g-test-timer-start" title="g_test_timer_start ()"><code class="function">g_test_timer_start()</code></a>.
 862 </p>
 863 <div class="variablelist"><table border="0">
 864 <col align="left" valign="top">
 865 <tbody><tr>
 866 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 867 <td>the time since the last start of the timer, as a double</td>
 868 </tr></tbody>
 869 </table></div>
 870 <p class="since">Since 2.16</p>
 871 </div>
 872 <hr>
 873 <div class="refsect2">
 874 <a name="g-test-timer-last"></a><h3>g_test_timer_last ()</h3>
 875 <pre class="programlisting"><span class="returnvalue">double</span>              g_test_timer_last                   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 876 <p>
 877 Report the last result of <a class="link" href="glib-Testing.html#g-test-timer-elapsed" title="g_test_timer_elapsed ()"><code class="function">g_test_timer_elapsed()</code></a>.
 878 </p>
 879 <div class="variablelist"><table border="0">
 880 <col align="left" valign="top">
 881 <tbody><tr>
 882 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 883 <td>the last result of <a class="link" href="glib-Testing.html#g-test-timer-elapsed" title="g_test_timer_elapsed ()"><code class="function">g_test_timer_elapsed()</code></a>, as a double</td>
 884 </tr></tbody>
 885 </table></div>
 886 <p class="since">Since 2.16</p>
 887 </div>
 888 <hr>
 889 <div class="refsect2">
 890 <a name="g-test-queue-free"></a><h3>g_test_queue_free ()</h3>
 891 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_queue_free                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> gfree_pointer</code></em>);</pre>
 892 <p>
 893 Enqueue a pointer to be released with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a> during the next
 894 teardown phase. This is equivalent to calling <a class="link" href="glib-Testing.html#g-test-queue-destroy" title="g_test_queue_destroy ()"><code class="function">g_test_queue_destroy()</code></a>
 895 with a destroy callback of <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.
 896 </p>
 897 <div class="variablelist"><table border="0">
 898 <col align="left" valign="top">
 899 <tbody><tr>
 900 <td><p><span class="term"><em class="parameter"><code>gfree_pointer</code></em> :</span></p></td>
 901 <td>the pointer to be stored.</td>
 902 </tr></tbody>
 903 </table></div>
 904 <p class="since">Since 2.16</p>
 905 </div>
 906 <hr>
 907 <div class="refsect2">
 908 <a name="g-test-queue-destroy"></a><h3>g_test_queue_destroy ()</h3>
 909 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_queue_destroy                (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> destroy_func</code></em>,
 910                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> destroy_data</code></em>);</pre>
 911 <p>
 912 This function enqueus a callback <em class="parameter"><code>destroy_func</code></em> to be executed
 913 during the next test case teardown phase. This is most useful
 914 to auto destruct allocted test resources at the end of a test run.
 915 Resources are released in reverse queue order, that means enqueueing
 916 callback A before callback B will cause <code class="function">B()</code> to be called before
 917 <code class="function">A()</code> during teardown.
 918 </p>
 919 <div class="variablelist"><table border="0">
 920 <col align="left" valign="top">
 921 <tbody>
 922 <tr>
 923 <td><p><span class="term"><em class="parameter"><code>destroy_func</code></em> :</span></p></td>
 924 <td>Destroy callback for teardown phase.</td>
 925 </tr>
 926 <tr>
 927 <td><p><span class="term"><em class="parameter"><code>destroy_data</code></em> :</span></p></td>
 928 <td>Destroy callback data.</td>
 929 </tr>
 930 </tbody>
 931 </table></div>
 932 <p class="since">Since 2.16</p>
 933 </div>
 934 <hr>
 935 <div class="refsect2">
 936 <a name="g-test-queue-unref"></a><h3>g_test_queue_unref()</h3>
 937 <pre class="programlisting">#define             g_test_queue_unref(gobject)</pre>
 938 <p>
 939 Enqueue an object to be released with <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a> during
 940 the next teardown phase. This is equivalent to calling
 941 <a class="link" href="glib-Testing.html#g-test-queue-destroy" title="g_test_queue_destroy ()"><code class="function">g_test_queue_destroy()</code></a> with a destroy callback of <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a>.
 942 </p>
 943 <div class="variablelist"><table border="0">
 944 <col align="left" valign="top">
 945 <tbody><tr>
 946 <td><p><span class="term"><em class="parameter"><code>gobject</code></em> :</span></p></td>
 947 <td>the object to unref</td>
 948 </tr></tbody>
 949 </table></div>
 950 <p class="since">Since 2.16</p>
 951 </div>
 952 <hr>
 953 <div class="refsect2">
 954 <a name="GTestTrapFlags"></a><h3>enum GTestTrapFlags</h3>
 955 <pre class="programlisting">typedef enum {
 956   G_TEST_TRAP_SILENCE_STDOUT    = 1 &lt;&lt; 7,
 957   G_TEST_TRAP_SILENCE_STDERR    = 1 &lt;&lt; 8,
 958   G_TEST_TRAP_INHERIT_STDIN     = 1 &lt;&lt; 9
 959 } GTestTrapFlags;
 960 </pre>
 961 <p>
 962 Test traps are guards around forked tests.
 963 These flags determine what traps to set.
 964 </p>
 965 <div class="variablelist"><table border="0">
 966 <col align="left" valign="top">
 967 <tbody>
 968 <tr>
 969 <td><p><a name="G-TEST-TRAP-SILENCE-STDOUT:CAPS"></a><span class="term"><code class="literal">G_TEST_TRAP_SILENCE_STDOUT</code></span></p></td>
 970 <td>Redirect stdout of the test child to
 971     <code class="filename">/dev/null</code> so it cannot be observed on the
 972     console during test runs. The actual output is still captured
 973     though to allow later tests with <a class="link" href="glib-Testing.html#g-test-trap-assert-stdout" title="g_test_trap_assert_stdout()"><code class="function">g_test_trap_assert_stdout()</code></a>.
 974 </td>
 975 </tr>
 976 <tr>
 977 <td><p><a name="G-TEST-TRAP-SILENCE-STDERR:CAPS"></a><span class="term"><code class="literal">G_TEST_TRAP_SILENCE_STDERR</code></span></p></td>
 978 <td>Redirect stderr of the test child to
 979     <code class="filename">/dev/null</code> so it cannot be observed on the
 980     console during test runs. The actual output is still captured
 981     though to allow later tests with <a class="link" href="glib-Testing.html#g-test-trap-assert-stderr" title="g_test_trap_assert_stderr()"><code class="function">g_test_trap_assert_stderr()</code></a>.
 982 </td>
 983 </tr>
 984 <tr>
 985 <td><p><a name="G-TEST-TRAP-INHERIT-STDIN:CAPS"></a><span class="term"><code class="literal">G_TEST_TRAP_INHERIT_STDIN</code></span></p></td>
 986 <td>If this flag is given, stdin of the
 987     forked child process is shared with stdin of its parent process.
 988     It is redirected to <code class="filename">/dev/null</code> otherwise.
 989 </td>
 990 </tr>
 991 </tbody>
 992 </table></div>
 993 </div>
 994 <hr>
 995 <div class="refsect2">
 996 <a name="g-test-trap-fork"></a><h3>g_test_trap_fork ()</h3>
 997 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_test_trap_fork                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> usec_timeout</code></em>,
 998                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestTrapFlags" title="enum GTestTrapFlags"><span class="type">GTestTrapFlags</span></a> test_trap_flags</code></em>);</pre>
 999 <p>
1000 Fork the current test program to execute a test case that might
1001 not return or that might abort. The forked test case is aborted
1002 and considered failing if its run time exceeds <em class="parameter"><code>usec_timeout</code></em>.
1003 </p>
1004 <p>
1005 The forking behavior can be configured with the <a class="link" href="glib-Testing.html#GTestTrapFlags" title="enum GTestTrapFlags"><span class="type">GTestTrapFlags</span></a> flags.
1006 </p>
1007 <p>
1008 In the following example, the test code forks, the forked child
1009 process produces some sample output and exits successfully.
1010 The forking parent process then asserts successful child program
1011 termination and validates child program outputs.
1012 </p>
1013 <p>
1014 </p>
1015 <div class="informalexample"><pre class="programlisting">
1016   static void
1017   test_fork_patterns (void)
1018   {
1019     if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
1020       {
1021         g_print ("some stdout text: somagic17\n");
1022         g_printerr ("some stderr text: semagic43\n");
1023         exit (0); /* successful test run */
1024       }
1025     g_test_trap_assert_passed();
1026     g_test_trap_assert_stdout ("*somagic17*");
1027     g_test_trap_assert_stderr ("*semagic43*");
1028   }
1029 </pre></div>
1030 <p>
1031 </p>
1032 <p>
1033 This function is implemented only on Unix platforms.
1034 </p>
1035 <div class="variablelist"><table border="0">
1036 <col align="left" valign="top">
1037 <tbody>
1038 <tr>
1039 <td><p><span class="term"><em class="parameter"><code>usec_timeout</code></em> :</span></p></td>
1040 <td>Timeout for the forked test in micro seconds.</td>
1041 </tr>
1042 <tr>
1043 <td><p><span class="term"><em class="parameter"><code>test_trap_flags</code></em> :</span></p></td>
1044 <td>Flags to modify forking behaviour.</td>
1045 </tr>
1046 <tr>
1047 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1048 <td>
1049 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> for the forked child and <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for the executing parent process.</td>
1050 </tr>
1051 </tbody>
1052 </table></div>
1053 <p class="since">Since 2.16</p>
1054 </div>
1055 <hr>
1056 <div class="refsect2">
1057 <a name="g-test-trap-has-passed"></a><h3>g_test_trap_has_passed ()</h3>
1058 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_test_trap_has_passed              (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1059 <p>
1060 Check the result of the last <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a> call.
1061 </p>
1062 <div class="variablelist"><table border="0">
1063 <col align="left" valign="top">
1064 <tbody><tr>
1065 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1066 <td>
1067 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the last forked child terminated successfully.</td>
1068 </tr></tbody>
1069 </table></div>
1070 <p class="since">Since 2.16</p>
1071 </div>
1072 <hr>
1073 <div class="refsect2">
1074 <a name="g-test-trap-reached-timeout"></a><h3>g_test_trap_reached_timeout ()</h3>
1075 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_test_trap_reached_timeout         (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1076 <p>
1077 Check the result of the last <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a> call.
1078 </p>
1079 <div class="variablelist"><table border="0">
1080 <col align="left" valign="top">
1081 <tbody><tr>
1082 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1083 <td>
1084 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the last forked child got killed due to a fork timeout.</td>
1085 </tr></tbody>
1086 </table></div>
1087 <p class="since">Since 2.16</p>
1088 </div>
1089 <hr>
1090 <div class="refsect2">
1091 <a name="g-test-trap-assert-passed"></a><h3>g_test_trap_assert_passed</h3>
1092 <pre class="programlisting">#define             g_test_trap_assert_passed()</pre>
1093 <p>
1094 Assert that the last forked test passed.
1095 See <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>.
1096 </p>
1097 <p class="since">Since 2.16</p>
1098 </div>
1099 <hr>
1100 <div class="refsect2">
1101 <a name="g-test-trap-assert-failed"></a><h3>g_test_trap_assert_failed</h3>
1102 <pre class="programlisting">#define             g_test_trap_assert_failed()</pre>
1103 <p>
1104 Assert that the last forked test failed.
1105 See <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>.
1106 </p>
1107 <p>
1108 This is sometimes used to test situations that are formally considered to
1109 be undefined behaviour, like inputs that fail a <a class="link" href="glib-Warnings-and-Assertions.html#g-return-if-fail" title="g_return_if_fail()"><code class="function">g_return_if_fail()</code></a>
1110 check. In these situations you should skip the entire test, including the
1111 call to <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>, unless <a class="link" href="glib-Testing.html#g-test-undefined" title="g_test_undefined"><code class="function">g_test_undefined()</code></a> returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>
1112 to indicate that undefined behaviour may be tested.
1113 </p>
1114 <p class="since">Since 2.16</p>
1115 </div>
1116 <hr>
1117 <div class="refsect2">
1118 <a name="g-test-trap-assert-stdout"></a><h3>g_test_trap_assert_stdout()</h3>
1119 <pre class="programlisting">#define             g_test_trap_assert_stdout(soutpattern)</pre>
1120 <p>
1121 Assert that the stdout output of the last forked test matches
1122 <em class="parameter"><code>soutpattern</code></em>. See <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>.
1123 </p>
1124 <div class="variablelist"><table border="0">
1125 <col align="left" valign="top">
1126 <tbody><tr>
1127 <td><p><span class="term"><em class="parameter"><code>soutpattern</code></em> :</span></p></td>
1128 <td>a glob-style
1129 <a class="link" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching">pattern</a>
1130 </td>
1131 </tr></tbody>
1132 </table></div>
1133 <p class="since">Since 2.16</p>
1134 </div>
1135 <hr>
1136 <div class="refsect2">
1137 <a name="g-test-trap-assert-stdout-unmatched"></a><h3>g_test_trap_assert_stdout_unmatched()</h3>
1138 <pre class="programlisting">#define             g_test_trap_assert_stdout_unmatched(soutpattern)</pre>
1139 <p>
1140 Assert that the stdout output of the last forked test
1141 does not match <em class="parameter"><code>soutpattern</code></em>. See <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>.
1142 </p>
1143 <div class="variablelist"><table border="0">
1144 <col align="left" valign="top">
1145 <tbody><tr>
1146 <td><p><span class="term"><em class="parameter"><code>soutpattern</code></em> :</span></p></td>
1147 <td>a glob-style
1148 <a class="link" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching">pattern</a>
1149 </td>
1150 </tr></tbody>
1151 </table></div>
1152 <p class="since">Since 2.16</p>
1153 </div>
1154 <hr>
1155 <div class="refsect2">
1156 <a name="g-test-trap-assert-stderr"></a><h3>g_test_trap_assert_stderr()</h3>
1157 <pre class="programlisting">#define             g_test_trap_assert_stderr(serrpattern)</pre>
1158 <p>
1159 Assert that the stderr output of the last forked test
1160 matches <em class="parameter"><code>serrpattern</code></em>. See  <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>.
1161 </p>
1162 <p>
1163 This is sometimes used to test situations that are formally considered to
1164 be undefined behaviour, like inputs that fail a <a class="link" href="glib-Warnings-and-Assertions.html#g-return-if-fail" title="g_return_if_fail()"><code class="function">g_return_if_fail()</code></a>
1165 check. In these situations you should skip the entire test, including the
1166 call to <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>, unless <a class="link" href="glib-Testing.html#g-test-undefined" title="g_test_undefined"><code class="function">g_test_undefined()</code></a> returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>
1167 to indicate that undefined behaviour may be tested.
1168 </p>
1169 <div class="variablelist"><table border="0">
1170 <col align="left" valign="top">
1171 <tbody><tr>
1172 <td><p><span class="term"><em class="parameter"><code>serrpattern</code></em> :</span></p></td>
1173 <td>a glob-style
1174 <a class="link" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching">pattern</a>
1175 </td>
1176 </tr></tbody>
1177 </table></div>
1178 <p class="since">Since 2.16</p>
1179 </div>
1180 <hr>
1181 <div class="refsect2">
1182 <a name="g-test-trap-assert-stderr-unmatched"></a><h3>g_test_trap_assert_stderr_unmatched()</h3>
1183 <pre class="programlisting">#define             g_test_trap_assert_stderr_unmatched(serrpattern)</pre>
1184 <p>
1185 Assert that the stderr output of the last forked test
1186 does not match <em class="parameter"><code>serrpattern</code></em>. See <a class="link" href="glib-Testing.html#g-test-trap-fork" title="g_test_trap_fork ()"><code class="function">g_test_trap_fork()</code></a>.
1187 </p>
1188 <div class="variablelist"><table border="0">
1189 <col align="left" valign="top">
1190 <tbody><tr>
1191 <td><p><span class="term"><em class="parameter"><code>serrpattern</code></em> :</span></p></td>
1192 <td>a glob-style
1193 <a class="link" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching">pattern</a>
1194 </td>
1195 </tr></tbody>
1196 </table></div>
1197 <p class="since">Since 2.16</p>
1198 </div>
1199 <hr>
1200 <div class="refsect2">
1201 <a name="g-test-rand-bit"></a><h3>g_test_rand_bit</h3>
1202 <pre class="programlisting">#define             g_test_rand_bit()</pre>
1203 <p>
1204 Get a reproducible random bit (0 or 1), see <a class="link" href="glib-Testing.html#g-test-rand-int" title="g_test_rand_int ()"><code class="function">g_test_rand_int()</code></a>
1205 for details on test case random numbers.
1206 </p>
1207 <p class="since">Since 2.16</p>
1208 </div>
1209 <hr>
1210 <div class="refsect2">
1211 <a name="g-test-rand-int"></a><h3>g_test_rand_int ()</h3>
1212 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a>              g_test_rand_int                     (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1213 <p>
1214 Get a reproducible random integer number.
1215 </p>
1216 <p>
1217 The random numbers generated by the g_test_rand_*() family of functions
1218 change with every new test program start, unless the --seed option is
1219 given when starting test programs.
1220 </p>
1221 <p>
1222 For individual test cases however, the random number generator is
1223 reseeded, to avoid dependencies between tests and to make --seed
1224 effective for all test cases.
1225 </p>
1226 <div class="variablelist"><table border="0">
1227 <col align="left" valign="top">
1228 <tbody><tr>
1229 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1230 <td>a random number from the seeded random number generator.</td>
1231 </tr></tbody>
1232 </table></div>
1233 <p class="since">Since 2.16</p>
1234 </div>
1235 <hr>
1236 <div class="refsect2">
1237 <a name="g-test-rand-int-range"></a><h3>g_test_rand_int_range ()</h3>
1238 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a>              g_test_rand_int_range               (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="type">gint32</span></a> begin</code></em>,
1239                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="type">gint32</span></a> end</code></em>);</pre>
1240 <p>
1241 Get a reproducible random integer number out of a specified range,
1242 see <a class="link" href="glib-Testing.html#g-test-rand-int" title="g_test_rand_int ()"><code class="function">g_test_rand_int()</code></a> for details on test case random numbers.
1243 </p>
1244 <div class="variablelist"><table border="0">
1245 <col align="left" valign="top">
1246 <tbody>
1247 <tr>
1248 <td><p><span class="term"><em class="parameter"><code>begin</code></em> :</span></p></td>
1249 <td>the minimum value returned by this function</td>
1250 </tr>
1251 <tr>
1252 <td><p><span class="term"><em class="parameter"><code>end</code></em> :</span></p></td>
1253 <td>the smallest value not to be returned by this function</td>
1254 </tr>
1255 <tr>
1256 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1257 <td>a number with <em class="parameter"><code>begin</code></em> &lt;= number &lt; <em class="parameter"><code>end</code></em>.</td>
1258 </tr>
1259 </tbody>
1260 </table></div>
1261 <p class="since">Since 2.16</p>
1262 </div>
1263 <hr>
1264 <div class="refsect2">
1265 <a name="g-test-rand-double"></a><h3>g_test_rand_double ()</h3>
1266 <pre class="programlisting"><span class="returnvalue">double</span>              g_test_rand_double                  (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1267 <p>
1268 Get a reproducible random floating point number,
1269 see <a class="link" href="glib-Testing.html#g-test-rand-int" title="g_test_rand_int ()"><code class="function">g_test_rand_int()</code></a> for details on test case random numbers.
1270 </p>
1271 <div class="variablelist"><table border="0">
1272 <col align="left" valign="top">
1273 <tbody><tr>
1274 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1275 <td>a random number from the seeded random number generator.</td>
1276 </tr></tbody>
1277 </table></div>
1278 <p class="since">Since 2.16</p>
1279 </div>
1280 <hr>
1281 <div class="refsect2">
1282 <a name="g-test-rand-double-range"></a><h3>g_test_rand_double_range ()</h3>
1283 <pre class="programlisting"><span class="returnvalue">double</span>              g_test_rand_double_range            (<em class="parameter"><code><span class="type">double</span> range_start</code></em>,
1284                                                          <em class="parameter"><code><span class="type">double</span> range_end</code></em>);</pre>
1285 <p>
1286 Get a reproducible random floating pointer number out of a specified range,
1287 see <a class="link" href="glib-Testing.html#g-test-rand-int" title="g_test_rand_int ()"><code class="function">g_test_rand_int()</code></a> for details on test case random numbers.
1288 </p>
1289 <div class="variablelist"><table border="0">
1290 <col align="left" valign="top">
1291 <tbody>
1292 <tr>
1293 <td><p><span class="term"><em class="parameter"><code>range_start</code></em> :</span></p></td>
1294 <td>the minimum value returned by this function</td>
1295 </tr>
1296 <tr>
1297 <td><p><span class="term"><em class="parameter"><code>range_end</code></em> :</span></p></td>
1298 <td>the minimum value not returned by this function</td>
1299 </tr>
1300 <tr>
1301 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1302 <td>a number with <em class="parameter"><code>range_start</code></em> &lt;= number &lt; <em class="parameter"><code>range_end</code></em>.</td>
1303 </tr>
1304 </tbody>
1305 </table></div>
1306 <p class="since">Since 2.16</p>
1307 </div>
1308 <hr>
1309 <div class="refsect2">
1310 <a name="g-assert"></a><h3>g_assert()</h3>
1311 <pre class="programlisting">#define             g_assert(expr)</pre>
1312 <p>
1313 Debugging macro to terminate the application if the assertion
1314 fails. If the assertion fails (i.e. the expression is not true),
1315 an error message is logged and the application is terminated.
1316 </p>
1317 <p>
1318 The macro can be turned off in final releases of code by defining
1319 <code class="envar">G_DISABLE_ASSERT</code> when compiling the application.
1320 </p>
1321 <div class="variablelist"><table border="0">
1322 <col align="left" valign="top">
1323 <tbody><tr>
1324 <td><p><span class="term"><em class="parameter"><code>expr</code></em> :</span></p></td>
1325 <td>the expression to check</td>
1326 </tr></tbody>
1327 </table></div>
1328 </div>
1329 <hr>
1330 <div class="refsect2">
1331 <a name="g-assert-not-reached"></a><h3>g_assert_not_reached</h3>
1332 <pre class="programlisting">#define             g_assert_not_reached()</pre>
1333 <p>
1334 Debugging macro to terminate the application if it is ever
1335 reached. If it is reached, an error message is logged and the
1336 application is terminated.
1337 </p>
1338 <p>
1339 The macro can be turned off in final releases of code by defining
1340 <code class="envar">G_DISABLE_ASSERT</code> when compiling the application.
1341 </p>
1342 </div>
1343 <hr>
1344 <div class="refsect2">
1345 <a name="g-assert-cmpstr"></a><h3>g_assert_cmpstr()</h3>
1346 <pre class="programlisting">#define             g_assert_cmpstr(s1, cmp, s2)</pre>
1347 <p>
1348 Debugging macro to terminate the application with a warning
1349 message if a string comparison fails. The strings are compared
1350 using <a class="link" href="glib-String-Utility-Functions.html#g-strcmp0" title="g_strcmp0 ()"><code class="function">g_strcmp0()</code></a>.
1351 </p>
1352 <p>
1353 The effect of <code class="literal">g_assert_cmpstr (s1, op, s2)</code> is
1354 the same as <code class="literal">g_assert (g_strcmp0 (s1, s2) op 0)</code>.
1355 The advantage of this macro is that it can produce a message that
1356 includes the actual values of <em class="parameter"><code>s1</code></em> and <em class="parameter"><code>s2</code></em>.
1357 </p>
1358 <p>
1359 </p>
1360 <div class="informalexample"><pre class="programlisting">
1361   g_assert_cmpstr (mystring, ==, "fubar");
1362 </pre></div>
1363 <p>
1364 </p>
1365 <div class="variablelist"><table border="0">
1366 <col align="left" valign="top">
1367 <tbody>
1368 <tr>
1369 <td><p><span class="term"><em class="parameter"><code>s1</code></em> :</span></p></td>
1370 <td>a string (may be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>)</td>
1371 </tr>
1372 <tr>
1373 <td><p><span class="term"><em class="parameter"><code>cmp</code></em> :</span></p></td>
1374 <td>The comparison operator to use.
1375 One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.</td>
1376 </tr>
1377 <tr>
1378 <td><p><span class="term"><em class="parameter"><code>s2</code></em> :</span></p></td>
1379 <td>another string (may be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>)</td>
1380 </tr>
1381 </tbody>
1382 </table></div>
1383 <p class="since">Since 2.16</p>
1384 </div>
1385 <hr>
1386 <div class="refsect2">
1387 <a name="g-assert-cmpint"></a><h3>g_assert_cmpint()</h3>
1388 <pre class="programlisting">#define             g_assert_cmpint(n1, cmp, n2)</pre>
1389 <p>
1390 Debugging macro to terminate the application with a warning
1391 message if an integer comparison fails.
1392 </p>
1393 <p>
1394 The effect of <code class="literal">g_assert_cmpint (n1, op, n2)</code> is
1395 the same as <code class="literal">g_assert (n1 op n2)</code>. The advantage
1396 of this macro is that it can produce a message that includes the
1397 actual values of <em class="parameter"><code>n1</code></em> and <em class="parameter"><code>n2</code></em>.
1398 </p>
1399 <div class="variablelist"><table border="0">
1400 <col align="left" valign="top">
1401 <tbody>
1402 <tr>
1403 <td><p><span class="term"><em class="parameter"><code>n1</code></em> :</span></p></td>
1404 <td>an integer</td>
1405 </tr>
1406 <tr>
1407 <td><p><span class="term"><em class="parameter"><code>cmp</code></em> :</span></p></td>
1408 <td>The comparison operator to use.
1409 One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.</td>
1410 </tr>
1411 <tr>
1412 <td><p><span class="term"><em class="parameter"><code>n2</code></em> :</span></p></td>
1413 <td>another integer</td>
1414 </tr>
1415 </tbody>
1416 </table></div>
1417 <p class="since">Since 2.16</p>
1418 </div>
1419 <hr>
1420 <div class="refsect2">
1421 <a name="g-assert-cmpuint"></a><h3>g_assert_cmpuint()</h3>
1422 <pre class="programlisting">#define             g_assert_cmpuint(n1, cmp, n2)</pre>
1423 <p>
1424 Debugging macro to terminate the application with a warning
1425 message if an unsigned integer comparison fails.
1426 </p>
1427 <p>
1428 The effect of <code class="literal">g_assert_cmpuint (n1, op, n2)</code> is
1429 the same as <code class="literal">g_assert (n1 op n2)</code>. The advantage
1430 of this macro is that it can produce a message that includes the
1431 actual values of <em class="parameter"><code>n1</code></em> and <em class="parameter"><code>n2</code></em>.
1432 </p>
1433 <div class="variablelist"><table border="0">
1434 <col align="left" valign="top">
1435 <tbody>
1436 <tr>
1437 <td><p><span class="term"><em class="parameter"><code>n1</code></em> :</span></p></td>
1438 <td>an unsigned integer</td>
1439 </tr>
1440 <tr>
1441 <td><p><span class="term"><em class="parameter"><code>cmp</code></em> :</span></p></td>
1442 <td>The comparison operator to use.
1443 One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.</td>
1444 </tr>
1445 <tr>
1446 <td><p><span class="term"><em class="parameter"><code>n2</code></em> :</span></p></td>
1447 <td>another unsigned integer</td>
1448 </tr>
1449 </tbody>
1450 </table></div>
1451 <p class="since">Since 2.16</p>
1452 </div>
1453 <hr>
1454 <div class="refsect2">
1455 <a name="g-assert-cmphex"></a><h3>g_assert_cmphex()</h3>
1456 <pre class="programlisting">#define             g_assert_cmphex(n1, cmp, n2)</pre>
1457 <p>
1458 Debugging macro to terminate the application with a warning
1459 message if an unsigned integer comparison fails.
1460 </p>
1461 <p>
1462 This is a variant of <a class="link" href="glib-Testing.html#g-assert-cmpuint" title="g_assert_cmpuint()"><code class="function">g_assert_cmpuint()</code></a> that displays the numbers
1463 in hexadecimal notation in the message.
1464 </p>
1465 <div class="variablelist"><table border="0">
1466 <col align="left" valign="top">
1467 <tbody>
1468 <tr>
1469 <td><p><span class="term"><em class="parameter"><code>n1</code></em> :</span></p></td>
1470 <td>an unsigned integer</td>
1471 </tr>
1472 <tr>
1473 <td><p><span class="term"><em class="parameter"><code>cmp</code></em> :</span></p></td>
1474 <td>The comparison operator to use.
1475 One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.</td>
1476 </tr>
1477 <tr>
1478 <td><p><span class="term"><em class="parameter"><code>n2</code></em> :</span></p></td>
1479 <td>another unsigned integer</td>
1480 </tr>
1481 </tbody>
1482 </table></div>
1483 <p class="since">Since 2.16</p>
1484 </div>
1485 <hr>
1486 <div class="refsect2">
1487 <a name="g-assert-cmpfloat"></a><h3>g_assert_cmpfloat()</h3>
1488 <pre class="programlisting">#define             g_assert_cmpfloat(n1,cmp,n2)</pre>
1489 <p>
1490 Debugging macro to terminate the application with a warning
1491 message if a floating point number comparison fails.
1492 </p>
1493 <p>
1494 The effect of <code class="literal">g_assert_cmpfloat (n1, op, n2)</code> is
1495 the same as <code class="literal">g_assert (n1 op n2)</code>. The advantage
1496 of this macro is that it can produce a message that includes the
1497 actual values of <em class="parameter"><code>n1</code></em> and <em class="parameter"><code>n2</code></em>.
1498 </p>
1499 <div class="variablelist"><table border="0">
1500 <col align="left" valign="top">
1501 <tbody>
1502 <tr>
1503 <td><p><span class="term"><em class="parameter"><code>n1</code></em> :</span></p></td>
1504 <td>an floating point number</td>
1505 </tr>
1506 <tr>
1507 <td><p><span class="term"><em class="parameter"><code>cmp</code></em> :</span></p></td>
1508 <td>The comparison operator to use.
1509 One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.</td>
1510 </tr>
1511 <tr>
1512 <td><p><span class="term"><em class="parameter"><code>n2</code></em> :</span></p></td>
1513 <td>another floating point number</td>
1514 </tr>
1515 </tbody>
1516 </table></div>
1517 <p class="since">Since 2.16</p>
1518 </div>
1519 <hr>
1520 <div class="refsect2">
1521 <a name="g-assert-no-error"></a><h3>g_assert_no_error()</h3>
1522 <pre class="programlisting">#define             g_assert_no_error(err)</pre>
1523 <p>
1524 Debugging macro to terminate the application with a warning
1525 message if a method has returned a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>.
1526 </p>
1527 <p>
1528 The effect of <code class="literal">g_assert_no_error (err)</code> is
1529 the same as <code class="literal">g_assert (err == NULL)</code>. The advantage
1530 of this macro is that it can produce a message that includes
1531 the error message and code.
1532 </p>
1533 <div class="variablelist"><table border="0">
1534 <col align="left" valign="top">
1535 <tbody><tr>
1536 <td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
1537 <td>a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>, possibly <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1538 </td>
1539 </tr></tbody>
1540 </table></div>
1541 <p class="since">Since 2.20</p>
1542 </div>
1543 <hr>
1544 <div class="refsect2">
1545 <a name="g-assert-error"></a><h3>g_assert_error()</h3>
1546 <pre class="programlisting">#define             g_assert_error(err, dom, c)</pre>
1547 <p>
1548 Debugging macro to terminate the application with a warning
1549 message if a method has not returned the correct <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>.
1550 </p>
1551 <p>
1552 The effect of <code class="literal">g_assert_error (err, dom, c)</code> is
1553 the same as <code class="literal">g_assert (err != NULL &amp;&amp; err-&gt;domain
1554 == dom &amp;&amp; err-&gt;code == c)</code>. The advantage of this
1555 macro is that it can produce a message that includes the incorrect
1556 error message and code.
1557 </p>
1558 <p>
1559 This can only be used to test for a specific error. If you want to
1560 test that <em class="parameter"><code>err</code></em> is set, but don't care what it's set to, just use
1561 <code class="literal">g_assert (err != NULL)</code>
1562 </p>
1563 <div class="variablelist"><table border="0">
1564 <col align="left" valign="top">
1565 <tbody>
1566 <tr>
1567 <td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
1568 <td>a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>, possibly <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1569 </td>
1570 </tr>
1571 <tr>
1572 <td><p><span class="term"><em class="parameter"><code>dom</code></em> :</span></p></td>
1573 <td>the expected error domain (a <a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a>)</td>
1574 </tr>
1575 <tr>
1576 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1577 <td>the expected error code</td>
1578 </tr>
1579 </tbody>
1580 </table></div>
1581 <p class="since">Since 2.20</p>
1582 </div>
1583 <hr>
1584 <div class="refsect2">
1585 <a name="GTestCase"></a><h3>GTestCase</h3>
1586 <pre class="programlisting">typedef struct GTestCase  GTestCase;
1587 </pre>
1588 <p>
1589 An opaque structure representing a test case.
1590 </p>
1591 </div>
1592 <hr>
1593 <div class="refsect2">
1594 <a name="GTestSuite"></a><h3>GTestSuite</h3>
1595 <pre class="programlisting">typedef struct GTestSuite GTestSuite;
1596 </pre>
1597 <p>
1598 An opaque structure representing a test suite.
1599 </p>
1600 </div>
1601 <hr>
1602 <div class="refsect2">
1603 <a name="GTestFixtureFunc"></a><h3>GTestFixtureFunc ()</h3>
1604 <pre class="programlisting"><span class="returnvalue">void</span>                (*GTestFixtureFunc)                 (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> fixture</code></em>,
1605                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> user_data</code></em>);</pre>
1606 <p>
1607 The type used for functions that operate on test fixtures.  This is
1608 used for the fixture setup and teardown functions as well as for the
1609 testcases themselves.
1610 </p>
1611 <p>
1612 <em class="parameter"><code>user_data</code></em> is a pointer to the data that was given when registering
1613 the test case.
1614 </p>
1615 <p>
1616 <em class="parameter"><code>fixture</code></em> will be a pointer to the area of memory allocated by the
1617 test framework, of the size requested.  If the requested size was
1618 zero then <em class="parameter"><code>fixture</code></em> will be equal to <em class="parameter"><code>user_data</code></em>.
1619 </p>
1620 <div class="variablelist"><table border="0">
1621 <col align="left" valign="top">
1622 <tbody>
1623 <tr>
1624 <td><p><span class="term"><em class="parameter"><code>fixture</code></em> :</span></p></td>
1625 <td>the test fixture</td>
1626 </tr>
1627 <tr>
1628 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
1629 <td>the data provided when registering the test</td>
1630 </tr>
1631 </tbody>
1632 </table></div>
1633 <p class="since">Since 2.28</p>
1634 </div>
1635 <hr>
1636 <div class="refsect2">
1637 <a name="g-test-create-case"></a><h3>g_test_create_case ()</h3>
1638 <pre class="programlisting"><a class="link" href="glib-Testing.html#GTestCase" title="GTestCase"><span class="returnvalue">GTestCase</span></a> *         g_test_create_case                  (<em class="parameter"><code>const <span class="type">char</span> *test_name</code></em>,
1639                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> data_size</code></em>,
1640                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> test_data</code></em>,
1641                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestFixtureFunc" title="GTestFixtureFunc ()"><span class="type">GTestFixtureFunc</span></a> data_setup</code></em>,
1642                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestFixtureFunc" title="GTestFixtureFunc ()"><span class="type">GTestFixtureFunc</span></a> data_test</code></em>,
1643                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestFixtureFunc" title="GTestFixtureFunc ()"><span class="type">GTestFixtureFunc</span></a> data_teardown</code></em>);</pre>
1644 <p>
1645 Create a new <a class="link" href="glib-Testing.html#GTestCase" title="GTestCase"><span class="type">GTestCase</span></a>, named <em class="parameter"><code>test_name</code></em>, this API is fairly
1646 low level, calling <a class="link" href="glib-Testing.html#g-test-add" title="g_test_add()"><code class="function">g_test_add()</code></a> or <a class="link" href="glib-Testing.html#g-test-add-func" title="g_test_add_func ()"><code class="function">g_test_add_func()</code></a> is preferable.
1647 When this test is executed, a fixture structure of size <em class="parameter"><code>data_size</code></em>
1648 will be allocated and filled with 0s. Then <em class="parameter"><code>data_setup</code></em> is called
1649 to initialize the fixture. After fixture setup, the actual test
1650 function <em class="parameter"><code>data_test</code></em> is called. Once the test run completed, the
1651 fixture structure is torn down  by calling <em class="parameter"><code>data_teardown</code></em> and
1652 after that the memory is released.
1653 </p>
1654 <p>
1655 Splitting up a test run into fixture setup, test function and
1656 fixture teardown is most usful if the same fixture is used for
1657 multiple tests. In this cases, <a class="link" href="glib-Testing.html#g-test-create-case" title="g_test_create_case ()"><code class="function">g_test_create_case()</code></a> will be
1658 called with the same fixture, but varying <em class="parameter"><code>test_name</code></em> and
1659 <em class="parameter"><code>data_test</code></em> arguments.
1660 </p>
1661 <div class="variablelist"><table border="0">
1662 <col align="left" valign="top">
1663 <tbody>
1664 <tr>
1665 <td><p><span class="term"><em class="parameter"><code>test_name</code></em> :</span></p></td>
1666 <td>the name for the test case</td>
1667 </tr>
1668 <tr>
1669 <td><p><span class="term"><em class="parameter"><code>data_size</code></em> :</span></p></td>
1670 <td>the size of the fixture data structure</td>
1671 </tr>
1672 <tr>
1673 <td><p><span class="term"><em class="parameter"><code>test_data</code></em> :</span></p></td>
1674 <td>test data argument for the test functions</td>
1675 </tr>
1676 <tr>
1677 <td><p><span class="term"><em class="parameter"><code>data_setup</code></em> :</span></p></td>
1678 <td>the function to set up the fixture data</td>
1679 </tr>
1680 <tr>
1681 <td><p><span class="term"><em class="parameter"><code>data_test</code></em> :</span></p></td>
1682 <td>the actual test function</td>
1683 </tr>
1684 <tr>
1685 <td><p><span class="term"><em class="parameter"><code>data_teardown</code></em> :</span></p></td>
1686 <td>the function to teardown the fixture data</td>
1687 </tr>
1688 <tr>
1689 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1690 <td>a newly allocated <a class="link" href="glib-Testing.html#GTestCase" title="GTestCase"><span class="type">GTestCase</span></a>.</td>
1691 </tr>
1692 </tbody>
1693 </table></div>
1694 <p class="since">Since 2.16</p>
1695 </div>
1696 <hr>
1697 <div class="refsect2">
1698 <a name="g-test-create-suite"></a><h3>g_test_create_suite ()</h3>
1699 <pre class="programlisting"><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="returnvalue">GTestSuite</span></a> *        g_test_create_suite                 (<em class="parameter"><code>const <span class="type">char</span> *suite_name</code></em>);</pre>
1700 <p>
1701 Create a new test suite with the name <em class="parameter"><code>suite_name</code></em>.
1702 </p>
1703 <div class="variablelist"><table border="0">
1704 <col align="left" valign="top">
1705 <tbody>
1706 <tr>
1707 <td><p><span class="term"><em class="parameter"><code>suite_name</code></em> :</span></p></td>
1708 <td>a name for the suite</td>
1709 </tr>
1710 <tr>
1711 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1712 <td>A newly allocated <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> instance.</td>
1713 </tr>
1714 </tbody>
1715 </table></div>
1716 <p class="since">Since 2.16</p>
1717 </div>
1718 <hr>
1719 <div class="refsect2">
1720 <a name="g-test-get-root"></a><h3>g_test_get_root ()</h3>
1721 <pre class="programlisting"><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="returnvalue">GTestSuite</span></a> *        g_test_get_root                     (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1722 <p>
1723 Get the toplevel test suite for the test path API.
1724 </p>
1725 <div class="variablelist"><table border="0">
1726 <col align="left" valign="top">
1727 <tbody><tr>
1728 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1729 <td>the toplevel <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a>
1730 </td>
1731 </tr></tbody>
1732 </table></div>
1733 <p class="since">Since 2.16</p>
1734 </div>
1735 <hr>
1736 <div class="refsect2">
1737 <a name="g-test-suite-add"></a><h3>g_test_suite_add ()</h3>
1738 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_suite_add                    (<em class="parameter"><code><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> *suite</code></em>,
1739                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestCase" title="GTestCase"><span class="type">GTestCase</span></a> *test_case</code></em>);</pre>
1740 <p>
1741 Adds <em class="parameter"><code>test_case</code></em> to <em class="parameter"><code>suite</code></em>.
1742 </p>
1743 <div class="variablelist"><table border="0">
1744 <col align="left" valign="top">
1745 <tbody>
1746 <tr>
1747 <td><p><span class="term"><em class="parameter"><code>suite</code></em> :</span></p></td>
1748 <td>a <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a>
1749 </td>
1750 </tr>
1751 <tr>
1752 <td><p><span class="term"><em class="parameter"><code>test_case</code></em> :</span></p></td>
1753 <td>a <a class="link" href="glib-Testing.html#GTestCase" title="GTestCase"><span class="type">GTestCase</span></a>
1754 </td>
1755 </tr>
1756 </tbody>
1757 </table></div>
1758 <p class="since">Since 2.16</p>
1759 </div>
1760 <hr>
1761 <div class="refsect2">
1762 <a name="g-test-suite-add-suite"></a><h3>g_test_suite_add_suite ()</h3>
1763 <pre class="programlisting"><span class="returnvalue">void</span>                g_test_suite_add_suite              (<em class="parameter"><code><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> *suite</code></em>,
1764                                                          <em class="parameter"><code><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> *nestedsuite</code></em>);</pre>
1765 <p>
1766 Adds <em class="parameter"><code>nestedsuite</code></em> to <em class="parameter"><code>suite</code></em>.
1767 </p>
1768 <div class="variablelist"><table border="0">
1769 <col align="left" valign="top">
1770 <tbody>
1771 <tr>
1772 <td><p><span class="term"><em class="parameter"><code>suite</code></em> :</span></p></td>
1773 <td>a <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a>
1774 </td>
1775 </tr>
1776 <tr>
1777 <td><p><span class="term"><em class="parameter"><code>nestedsuite</code></em> :</span></p></td>
1778 <td>another <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a>
1779 </td>
1780 </tr>
1781 </tbody>
1782 </table></div>
1783 <p class="since">Since 2.16</p>
1784 </div>
1785 <hr>
1786 <div class="refsect2">
1787 <a name="g-test-run-suite"></a><h3>g_test_run_suite ()</h3>
1788 <pre class="programlisting"><span class="returnvalue">int</span>                 g_test_run_suite                    (<em class="parameter"><code><a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a> *suite</code></em>);</pre>
1789 <p>
1790 Execute the tests within <em class="parameter"><code>suite</code></em> and all nested <a href="glib-Testing.html#GTestSuite"><span class="type">GTestSuites</span></a>.
1791 The test suites to be executed are filtered according to
1792 test path arguments (-p <em class="replaceable"><code>testpath</code></em>)
1793 as parsed by <a class="link" href="glib-Testing.html#g-test-init" title="g_test_init ()"><code class="function">g_test_init()</code></a>.
1794 <a class="link" href="glib-Testing.html#g-test-run-suite" title="g_test_run_suite ()"><code class="function">g_test_run_suite()</code></a> or <a class="link" href="glib-Testing.html#g-test-run" title="g_test_run ()"><code class="function">g_test_run()</code></a> may only be called once
1795 in a program.
1796 </p>
1797 <div class="variablelist"><table border="0">
1798 <col align="left" valign="top">
1799 <tbody>
1800 <tr>
1801 <td><p><span class="term"><em class="parameter"><code>suite</code></em> :</span></p></td>
1802 <td>a <a class="link" href="glib-Testing.html#GTestSuite" title="GTestSuite"><span class="type">GTestSuite</span></a>
1803 </td>
1804 </tr>
1805 <tr>
1806 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1807 <td>0 on success</td>
1808 </tr>
1809 </tbody>
1810 </table></div>
1811 <p class="since">Since 2.16</p>
1812 </div>
1813 </div>
1814 <div class="refsect1">
1815 <a name="glib-Testing.see-also"></a><h2>See Also</h2>
1816 <a href="gtester.html">gtester</a>,
1817            <a href="gtester-report.html">gtester-report</a>
1818 </div>
1819 </div>
1820 <div class="footer">
1821 <hr>
1822           Generated by GTK-Doc V1.18</div>
1823 </body>
1824 </html>