4
4
<!-- ##### SECTION Short_Description ##### -->
7
7
<!-- ##### SECTION Long_Description ##### -->
9
GLib provides a framework for writing and maintaining unit tests
10
in parallel to the code they are testing. The API is designed according
11
to established concepts found in the other test frameworks (JUnit, NUnit,
12
RUnit), which in turn is based on smalltalk unit testing concepts.
15
<term>Test case</term>
17
Tests (test methods) are grouped together with their
18
fixture into test cases.
24
A test fixture consists of fixture data and setup and teardown methods
25
to establish the environment for the test functions. We use fresh
26
fixtures, i.e. fixtures are newly set up and torn down around each test
27
invokation to avoid dependencies between tests.
31
<term>Test suite</term>
33
Test cases can be grouped into test suites, to allow subsets of the
34
available tests to be run. Test suites can be grouped into other test
39
The API is designed to handle creation and registration of test suites and
40
test cases implicitly. A simple call like
41
<informalexample><programlisting>
42
g_test_add_func ("/misc/assertions", test_assertions);
43
</programlisting></informalexample>
44
creates a test suite called "misc" with a single test case named "assertions",
45
which consists of running the test_assertions function.
48
In addition to the traditional g_assert(), the test framework provides
49
an extended set of assertions for string and numerical comparisons:
50
g_assert_cmpfloat(), g_assert_cmpint(), g_assert_cmpuint(), g_assert_cmphex(),
51
g_assert_cmpstr(). The advantage of these variants over plain g_assert()
52
is that the assertion messages can be more elaborate, and include the
53
values of the compared entities.
56
GLib ships with two utilites called gtester and gtester-report to
57
facilitate running tests and producing nicely formatted test reports.
13
60
<!-- ##### SECTION See_Also ##### -->
62
<link linkend="gtester">gtester</link>,
63
<link linkend="gtester-report">gtester-report</link>
19
66
<!-- ##### SECTION Stability_Level ##### -->
22
<!-- ##### TYPEDEF GTestCase ##### -->
28
<!-- ##### TYPEDEF GTestSuite ##### -->
34
69
<!-- ##### FUNCTION g_test_minimized_result ##### -->
211
246
<!-- ##### MACRO g_test_queue_unref ##### -->
248
Enqueue an object to be released with g_object_unref() during
249
the next teardown phase. This is equivalent to calling g_test_queue_destroy()
250
with a destroy callback of g_object_unref().
253
@gobject: the object to unref
219
257
<!-- ##### ENUM GTestTrapFlags ##### -->
259
Test traps are guards around forked tests. These flags
260
determine what traps to set.
224
@G_TEST_TRAP_SILENCE_STDOUT:
225
@G_TEST_TRAP_SILENCE_STDERR:
226
@G_TEST_TRAP_INHERIT_STDIN:
263
@G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
264
<filename>/dev/null</filename> so it cannot be observed on the
265
console during test runs. The actual output is still captured
266
though to allow later tests with g_test_trap_assert_stdout().
267
@G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
268
<filename>/dev/null</filename> so it cannot be observed on the
269
console during test runs. The actual output is still captured
270
though to allow later tests with g_test_trap_assert_stderr().
271
@G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the forked
272
child process is shared with stdin of its parent process. It is
273
redirected to <filename>/dev/null</filename> otherwise.
228
275
<!-- ##### FUNCTION g_test_trap_fork ##### -->
254
301
<!-- ##### MACRO g_test_trap_assert_passed ##### -->
303
Assert that the last forked test passed. See g_test_trap_fork().
261
309
<!-- ##### MACRO g_test_trap_assert_failed ##### -->
311
Assert that the last forked test failed. See g_test_trap_fork().
268
317
<!-- ##### MACRO g_test_trap_assert_stdout ##### -->
319
Assert that the stdout output of the last forked test matches @soutpattern.
320
See g_test_trap_fork().
323
@soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
276
327
<!-- ##### MACRO g_test_trap_assert_stdout_unmatched ##### -->
329
Assert that the stdout output of the last forked test does not match
330
@soutpattern. See g_test_trap_fork().
333
@soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
284
337
<!-- ##### MACRO g_test_trap_assert_stderr ##### -->
339
Assert that the stderr output of the last forked test matches @serrpattern.
340
See g_test_trap_fork().
343
@serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
292
347
<!-- ##### MACRO g_test_trap_assert_stderr_unmatched ##### -->
349
Assert that the stderr output of the last forked test does not match
350
@serrpattern. See g_test_trap_fork().
353
@serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
300
357
<!-- ##### MACRO g_test_rand_bit ##### -->
359
Get a reproducible random bit (0 or 1),
360
see g_test_rand_int() for details on test case random numbers.
307
366
<!-- ##### FUNCTION g_test_rand_int ##### -->
343
402
<!-- ##### MACRO g_assert ##### -->
404
Debugging macro to terminate the application if the assertion fails.
405
If the assertion fails (i.e. the expression is not true), an error message
406
is logged and the application is terminated.
409
The macro can be turned off in final releases of code by defining
410
#G_DISABLE_ASSERT when compiling the application.
413
@expr: the expression to check.
351
416
<!-- ##### MACRO g_assert_not_reached ##### -->
418
Debugging macro to terminate the application if it is ever reached.
419
If it is reached, an error message is logged and the application is terminated.
422
The macro can be turned off in final releases of code by defining
423
#G_DISABLE_ASSERT when compiling the application.
358
428
<!-- ##### MACRO g_assert_cmpstr ##### -->
430
Debugging macro to terminate the application with a warning message
431
if a string comparison fails.
432
The strings are compared using g_strcmp0().
435
The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is the same
436
as <literal>g_assert (s1 op s2)</literal>. The advantage of this macro
437
is that it can produce a message that includes the actual values of @s1
440
<informalexample><programlisting>
441
g_assert_cmpstr (mystring, ==, "fubar");
442
</programlisting></informalexample>
444
@s1: a string (may be %NULL)
445
@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
446
@s2: another string (may be %NULL)
368
450
<!-- ##### MACRO g_assert_cmpint ##### -->
452
Debugging macro to terminate the application with a warning message
453
if an integer comparison fails.
456
The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is the same
457
as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
458
is that it can produce a message that includes the actual values of @n1
463
@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
378
468
<!-- ##### MACRO g_assert_cmpuint ##### -->
470
Debugging macro to terminate the application with a warning message
471
if an unsigned integer comparison fails.
474
The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is the same
475
as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
476
is that it can produce a message that includes the actual values of @n1
480
@n1: an unsigned integer
481
@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
482
@n2: another unsigned integer
388
486
<!-- ##### MACRO g_assert_cmphex ##### -->
488
Debugging macro to terminate the application with a warning message
489
if an unsigned integer comparison fails. This is a variant of
490
g_assert_cmpuint() that displays the numbers in hexadecimal notation
494
@n1: an unsigned integer
495
@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
496
@n2: another unsigned integer
398
500
<!-- ##### MACRO g_assert_cmpfloat ##### -->
408
<!-- ##### FUNCTION g_strcmp0 ##### -->
502
Debugging macro to terminate the application with a warning message
503
if a floating point number comparison fails.
506
The effect of <literal>g_assert_cmpflott (n1, op, n2)</literal> is the same
507
as <literal>g_assert (n1 op n2)</literal>. The advantage of this function
508
is that it can produce a message that includes the actual values of @n1
512
@n1: an floating point number
513
@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
514
@n2: another floating point number
518
<!-- ##### TYPEDEF GTestCase ##### -->
520
An opaque structure representing a test case.
524
<!-- ##### TYPEDEF GTestSuite ##### -->
526
An opaque structure representing a test suite.
530
<!-- ##### FUNCTION g_test_create_case ##### -->
544
<!-- ##### FUNCTION g_test_create_suite ##### -->
553
<!-- ##### FUNCTION g_test_get_root ##### -->
561
<!-- ##### FUNCTION g_test_suite_add ##### -->
570
<!-- ##### FUNCTION g_test_suite_add_suite ##### -->
579
<!-- ##### FUNCTION g_test_run_suite ##### -->
added
removed
docs/reference/glib/tmpl/testing.sgml
