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