mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-04-09 17:23:08 +02:00
1ae3a4aec1
* glib/tmpl/testing.sgml: Fix lots of typos, document g_assert_error() and g_assert_no_error() svn path=/trunk/; revision=7557
626 lines
13 KiB
Plaintext
626 lines
13 KiB
Plaintext
<!-- ##### 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 ##### -->
|
|
|
|
|
|
<!-- ##### 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>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_add_func ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@testpath:
|
|
@test_func:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_add_data_func ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@testpath:
|
|
@test_data:
|
|
@test_func:
|
|
|
|
|
|
<!-- ##### 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:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_timer_start ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_timer_elapsed ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_timer_last ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@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>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_trap_reached_timeout ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@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>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_rand_int_range ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@begin:
|
|
@end:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_rand_double ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@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:
|
|
@data_setup:
|
|
@data_test:
|
|
@data_teardown:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_create_suite ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@suite_name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_test_get_root ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@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:
|
|
|
|
|