| <!-- ##### SECTION Title ##### --> |
| Testing |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| a test framework |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| GLib provides a framework for writing and maintaining unit tests |
| in parallel to the code they are testing. The API is designed according |
| to established concepts found in the other test frameworks (JUnit, NUnit, |
| RUnit), which in turn is based on smalltalk unit testing concepts. |
| <variablelist> |
| <varlistentry> |
| <term>Test case</term> |
| <listitem><para> |
| Tests (test methods) are grouped together with their |
| fixture into test cases. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>Fixture</term> |
| <listitem><para> |
| A test fixture consists of fixture data and setup and teardown methods |
| to establish the environment for the test functions. We use fresh |
| fixtures, i.e. fixtures are newly set up and torn down around each test |
| invocation to avoid dependencies between tests. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>Test suite</term> |
| <listitem><para> |
| Test cases can be grouped into test suites, to allow subsets of the |
| available tests to be run. Test suites can be grouped into other test |
| suites as well. |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| The API is designed to handle creation and registration of test suites and |
| test cases implicitly. A simple call like |
| <informalexample><programlisting> |
| g_test_add_func ("/misc/assertions", test_assertions); |
| </programlisting></informalexample> |
| creates a test suite called "misc" with a single test case named "assertions", |
| which consists of running the test_assertions function. |
| </para> |
| <para> |
| In addition to the traditional g_assert(), the test framework provides |
| an extended set of assertions for string and numerical comparisons: |
| g_assert_cmpfloat(), g_assert_cmpint(), g_assert_cmpuint(), g_assert_cmphex(), |
| g_assert_cmpstr(). The advantage of these variants over plain g_assert() |
| is that the assertion messages can be more elaborate, and include the |
| values of the compared entities. |
| </para> |
| <para> |
| GLib ships with two utilities called gtester and gtester-report to |
| facilitate running tests and producing nicely formatted test reports. |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| <link linkend="gtester">gtester</link>, |
| <link linkend="gtester-report">gtester-report</link> |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### SECTION Image ##### --> |
| |
| |
| <!-- ##### FUNCTION g_test_minimized_result ##### --> |
| <para> |
| |
| </para> |
| |
| @minimized_quantity: |
| @format: |
| @Varargs: |
| |
| |
| <!-- ##### FUNCTION g_test_maximized_result ##### --> |
| <para> |
| |
| </para> |
| |
| @maximized_quantity: |
| @format: |
| @Varargs: |
| |
| |
| <!-- ##### FUNCTION g_test_init ##### --> |
| <para> |
| |
| </para> |
| |
| @argc: |
| @argv: |
| @Varargs: |
| |
| |
| <!-- ##### MACRO g_test_quick ##### --> |
| <para> |
| Returns %TRUE if tests are run in quick mode. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO g_test_slow ##### --> |
| <para> |
| Returns %TRUE if tests are run in slow mode. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO g_test_thorough ##### --> |
| <para> |
| Returns %TRUE if tests are run in thorough mode. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO g_test_perf ##### --> |
| <para> |
| Returns %TRUE if tests are run in performance mode. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO g_test_verbose ##### --> |
| <para> |
| Returns %TRUE if tests are run in verbose mode. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO g_test_quiet ##### --> |
| <para> |
| Returns %TRUE if tests are run in quiet mode. |
| </para> |
| |
| |
| |
| <!-- ##### FUNCTION g_test_run ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_add_func ##### --> |
| <para> |
| |
| </para> |
| |
| @testpath: |
| @void: |
| |
| |
| <!-- ##### FUNCTION g_test_add_data_func ##### --> |
| <para> |
| |
| </para> |
| |
| @testpath: |
| @test_data: |
| @gconstpointer: |
| |
| |
| <!-- ##### MACRO g_test_add ##### --> |
| <para> |
| |
| </para> |
| |
| @testpath: |
| @Fixture: |
| @tdata: |
| @fsetup: |
| @ftest: |
| @fteardown: |
| |
| |
| <!-- ##### FUNCTION g_test_message ##### --> |
| <para> |
| |
| </para> |
| |
| @format: |
| @Varargs: |
| |
| |
| <!-- ##### FUNCTION g_test_bug_base ##### --> |
| <para> |
| |
| </para> |
| |
| @uri_pattern: |
| |
| |
| <!-- ##### FUNCTION g_test_bug ##### --> |
| <para> |
| |
| </para> |
| |
| @bug_uri_snippet: |
| |
| |
| <!-- ##### USER_FUNCTION GTestLogFatalFunc ##### --> |
| <para> |
| |
| </para> |
| |
| @log_domain: |
| @log_level: |
| @message: |
| @user_data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_log_set_fatal_handler ##### --> |
| <para> |
| |
| </para> |
| |
| @log_func: |
| @user_data: |
| |
| |
| <!-- ##### FUNCTION g_test_timer_start ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| |
| |
| <!-- ##### FUNCTION g_test_timer_elapsed ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_timer_last ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_queue_free ##### --> |
| <para> |
| |
| </para> |
| |
| @gfree_pointer: |
| |
| |
| <!-- ##### FUNCTION g_test_queue_destroy ##### --> |
| <para> |
| |
| </para> |
| |
| @destroy_func: |
| @destroy_data: |
| |
| |
| <!-- ##### MACRO g_test_queue_unref ##### --> |
| <para> |
| Enqueue an object to be released with g_object_unref() during |
| the next teardown phase. This is equivalent to calling g_test_queue_destroy() |
| with a destroy callback of g_object_unref(). |
| </para> |
| |
| @gobject: the object to unref |
| @Since: 2.16 |
| |
| |
| <!-- ##### ENUM GTestTrapFlags ##### --> |
| <para> |
| Test traps are guards around forked tests. These flags |
| determine what traps to set. |
| </para> |
| |
| @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to |
| <filename>/dev/null</filename> so it cannot be observed on the |
| console during test runs. The actual output is still captured |
| though to allow later tests with g_test_trap_assert_stdout(). |
| @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to |
| <filename>/dev/null</filename> so it cannot be observed on the |
| console during test runs. The actual output is still captured |
| though to allow later tests with g_test_trap_assert_stderr(). |
| @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the forked |
| child process is shared with stdin of its parent process. It is |
| redirected to <filename>/dev/null</filename> otherwise. |
| |
| <!-- ##### FUNCTION g_test_trap_fork ##### --> |
| <para> |
| |
| </para> |
| |
| @usec_timeout: |
| @test_trap_flags: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_trap_has_passed ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_trap_reached_timeout ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### MACRO g_test_trap_assert_passed ##### --> |
| <para> |
| Assert that the last forked test passed. See g_test_trap_fork(). |
| </para> |
| |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_test_trap_assert_failed ##### --> |
| <para> |
| Assert that the last forked test failed. See g_test_trap_fork(). |
| </para> |
| |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_test_trap_assert_stdout ##### --> |
| <para> |
| Assert that the stdout output of the last forked test matches @soutpattern. |
| See g_test_trap_fork(). |
| </para> |
| |
| @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_test_trap_assert_stdout_unmatched ##### --> |
| <para> |
| Assert that the stdout output of the last forked test does not match |
| @soutpattern. See g_test_trap_fork(). |
| </para> |
| |
| @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_test_trap_assert_stderr ##### --> |
| <para> |
| Assert that the stderr output of the last forked test matches @serrpattern. |
| See g_test_trap_fork(). |
| </para> |
| |
| @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_test_trap_assert_stderr_unmatched ##### --> |
| <para> |
| Assert that the stderr output of the last forked test does not match |
| @serrpattern. See g_test_trap_fork(). |
| </para> |
| |
| @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_test_rand_bit ##### --> |
| <para> |
| Get a reproducible random bit (0 or 1), |
| see g_test_rand_int() for details on test case random numbers. |
| </para> |
| |
| @Since: 2.16 |
| |
| |
| <!-- ##### FUNCTION g_test_rand_int ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_rand_int_range ##### --> |
| <para> |
| |
| </para> |
| |
| @begin: |
| @end: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_rand_double ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_rand_double_range ##### --> |
| <para> |
| |
| </para> |
| |
| @range_start: |
| @range_end: |
| @Returns: |
| |
| |
| <!-- ##### MACRO g_assert ##### --> |
| <para> |
| Debugging macro to terminate the application if the assertion fails. |
| If the assertion fails (i.e. the expression is not true), an error message |
| is logged and the application is terminated. |
| </para> |
| <para> |
| The macro can be turned off in final releases of code by defining |
| #G_DISABLE_ASSERT when compiling the application. |
| </para> |
| |
| @expr: the expression to check. |
| |
| |
| <!-- ##### MACRO g_assert_not_reached ##### --> |
| <para> |
| Debugging macro to terminate the application if it is ever reached. |
| If it is reached, an error message is logged and the application is terminated. |
| </para> |
| <para> |
| The macro can be turned off in final releases of code by defining |
| #G_DISABLE_ASSERT when compiling the application. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO g_assert_cmpstr ##### --> |
| <para> |
| Debugging macro to terminate the application with a warning message |
| if a string comparison fails. |
| The strings are compared using g_strcmp0(). |
| </para> |
| <para> |
| The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is the same |
| as <literal>g_assert (g_strcmp0 (s1, s2) op 0)</literal>. The advantage of this macro |
| is that it can produce a message that includes the actual values of @s1 |
| and @s2. |
| </para> |
| <informalexample><programlisting> |
| g_assert_cmpstr (mystring, ==, "fubar"); |
| </programlisting></informalexample> |
| |
| @s1: a string (may be %NULL) |
| @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. |
| @s2: another string (may be %NULL) |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_assert_cmpint ##### --> |
| <para> |
| Debugging macro to terminate the application with a warning message |
| if an integer comparison fails. |
| </para> |
| <para> |
| The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is the same |
| as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro |
| is that it can produce a message that includes the actual values of @n1 |
| and @n2. |
| </para> |
| |
| @n1: an integer |
| @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. |
| @n2: another integer |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_assert_cmpuint ##### --> |
| <para> |
| Debugging macro to terminate the application with a warning message |
| if an unsigned integer comparison fails. |
| </para> |
| <para> |
| The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is the same |
| as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro |
| is that it can produce a message that includes the actual values of @n1 |
| and @n2. |
| </para> |
| |
| @n1: an unsigned integer |
| @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. |
| @n2: another unsigned integer |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_assert_cmphex ##### --> |
| <para> |
| Debugging macro to terminate the application with a warning message |
| if an unsigned integer comparison fails. This is a variant of |
| g_assert_cmpuint() that displays the numbers in hexadecimal notation |
| in the message. |
| </para> |
| |
| @n1: an unsigned integer |
| @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. |
| @n2: another unsigned integer |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_assert_cmpfloat ##### --> |
| <para> |
| Debugging macro to terminate the application with a warning message |
| if a floating point number comparison fails. |
| </para> |
| <para> |
| The effect of <literal>g_assert_cmpfloat (n1, op, n2)</literal> is the same |
| as <literal>g_assert (n1 op n2)</literal>. The advantage of this function |
| is that it can produce a message that includes the actual values of @n1 |
| and @n2. |
| </para> |
| |
| @n1: an floating point number |
| @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. |
| @n2: another floating point number |
| @Since: 2.16 |
| |
| |
| <!-- ##### MACRO g_assert_no_error ##### --> |
| <para> |
| Debugging macro to terminate the application with a warning message |
| if a method has returned a #GError. |
| </para> |
| <para> |
| The effect of <literal>g_assert_no_error (err)</literal> is the same |
| as <literal>g_assert (err == NULL)</literal>. The advantage of this macro |
| is that it can produce a message that includes the error message and code. |
| </para> |
| |
| @err: a #GError, possibly %NULL |
| @Since: 2.20 |
| |
| |
| <!-- ##### MACRO g_assert_error ##### --> |
| <para> |
| Debugging macro to terminate the application with a warning message |
| if a method has not returned the correct #GError. |
| </para> |
| <para> |
| The effect of <literal>g_assert_error (err, dom, c)</literal> is the same |
| as <literal>g_assert (err != NULL && err->domain == dom && err->code == c)</literal>. |
| The advantage of this macro is that it can produce a message that |
| includes the incorrect error message and code. |
| </para> |
| <para> |
| This can only be used to test for a specific error. If you want to |
| test that @err is set, but don't care what it's set to, just use |
| <literal>g_assert (err != NULL)</literal> |
| </para> |
| |
| @err: a #GError, possibly %NULL |
| @dom: the expected error domain (a #GQuark) |
| @c: the expected error code |
| @Since: 2.20 |
| |
| |
| <!-- ##### TYPEDEF GTestCase ##### --> |
| <para> |
| An opaque structure representing a test case. |
| </para> |
| |
| |
| <!-- ##### TYPEDEF GTestSuite ##### --> |
| <para> |
| An opaque structure representing a test suite. |
| </para> |
| |
| |
| <!-- ##### FUNCTION g_test_create_case ##### --> |
| <para> |
| |
| </para> |
| |
| @test_name: |
| @data_size: |
| @test_data: |
| @void: |
| @void: |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_create_suite ##### --> |
| <para> |
| |
| </para> |
| |
| @suite_name: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_get_root ##### --> |
| <para> |
| |
| </para> |
| |
| @void: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_test_suite_add ##### --> |
| <para> |
| |
| </para> |
| |
| @suite: |
| @test_case: |
| |
| |
| <!-- ##### FUNCTION g_test_suite_add_suite ##### --> |
| <para> |
| |
| </para> |
| |
| @suite: |
| @nestedsuite: |
| |
| |
| <!-- ##### FUNCTION g_test_run_suite ##### --> |
| <para> |
| |
| </para> |
| |
| @suite: |
| @Returns: |
| |
| |