diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index 1be29429b..93145813c 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -23,6 +23,7 @@ gvariant.sgml gwakeup.sgml hash_tables.sgml iochannels.sgml +keyfile.sgml linked_lists_double.sgml linked_lists_single.sgml main.sgml @@ -40,6 +41,7 @@ sequence.sgml shell.sgml spawn.sgml string_chunks.sgml +testing.sgml thread_pools.sgml threads.sgml trees-binary.sgml diff --git a/docs/reference/glib/tmpl/testing.sgml b/docs/reference/glib/tmpl/testing.sgml deleted file mode 100644 index 966c8fe25..000000000 --- a/docs/reference/glib/tmpl/testing.sgml +++ /dev/null @@ -1,691 +0,0 @@ - -Testing - - -a test framework - - - -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. - - - Test case - - Tests (test methods) are grouped together with their - fixture into test cases. - - - - Fixture - - 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. - - - - Test suite - - 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. - - - -The API is designed to handle creation and registration of test suites and -test cases implicitly. A simple call like - - g_test_add_func ("/misc/assertions", test_assertions); - -creates a test suite called "misc" with a single test case named "assertions", -which consists of running the test_assertions function. - - -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. - - -GLib ships with two utilities called gtester and gtester-report to -facilitate running tests and producing nicely formatted test reports. - - - - -gtester, -gtester-report - - - - - - - - - - - - - -@minimized_quantity: -@format: -@Varargs: - - - - - - - -@maximized_quantity: -@format: -@Varargs: - - - - - - - -@argc: -@argv: -@Varargs: - - - - -Returns %TRUE if tests are run in quick mode. - - - - - - -Returns %TRUE if tests are run in slow mode. - - - - - - -Returns %TRUE if tests are run in thorough mode. - - - - - - -Returns %TRUE if tests are run in performance mode. - - - - - - -Returns %TRUE if tests are run in verbose mode. - - - - - - -Returns %TRUE if tests are run in quiet mode. - - - - - - - - - -@void: -@Returns: - - - - - - - -@void: - - - - - - - -@testpath: -@test_func: - - - - - - - -@user_data: - - - - - - - -@testpath: -@test_data: -@test_func: - - - - - - - -@testpath: -@Fixture: -@tdata: -@fsetup: -@ftest: -@fteardown: - - - - - - - -@void: - - - - - - - -@format: -@Varargs: - - - - - - - -@uri_pattern: - - - - - - - -@bug_uri_snippet: - - - - - - - -@log_domain: -@log_level: -@message: -@user_data: -@Returns: - - - - - - - -@log_func: -@user_data: - - - - - - - -@void: - - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@gfree_pointer: - - - - - - - -@destroy_func: -@destroy_data: - - - - -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(). - - -@gobject: the object to unref -@Since: 2.16 - - - - -Test traps are guards around forked tests. These flags -determine what traps to set. - - -@G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to - /dev/null 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 - /dev/null 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 /dev/null otherwise. - - - - - - -@usec_timeout: -@test_trap_flags: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - -Assert that the last forked test passed. See g_test_trap_fork(). - - -@Since: 2.16 - - - - -Assert that the last forked test failed. See g_test_trap_fork(). - - -@Since: 2.16 - - - - -Assert that the stdout output of the last forked test matches @soutpattern. -See g_test_trap_fork(). - - -@soutpattern: a glob-style pattern -@Since: 2.16 - - - - -Assert that the stdout output of the last forked test does not match -@soutpattern. See g_test_trap_fork(). - - -@soutpattern: a glob-style pattern -@Since: 2.16 - - - - -Assert that the stderr output of the last forked test matches @serrpattern. -See g_test_trap_fork(). - - -@serrpattern: a glob-style pattern -@Since: 2.16 - - - - -Assert that the stderr output of the last forked test does not match -@serrpattern. See g_test_trap_fork(). - - -@serrpattern: a glob-style pattern -@Since: 2.16 - - - - -Get a reproducible random bit (0 or 1), -see g_test_rand_int() for details on test case random numbers. - - -@Since: 2.16 - - - - - - - -@void: -@Returns: - - - - - - - -@begin: -@end: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@range_start: -@range_end: -@Returns: - - - - -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. - - -The macro can be turned off in final releases of code by defining -#G_DISABLE_ASSERT when compiling the application. - - -@expr: the expression to check. - - - - -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. - - -The macro can be turned off in final releases of code by defining -#G_DISABLE_ASSERT when compiling the application. - - - - - - -Debugging macro to terminate the application with a warning message -if a string comparison fails. -The strings are compared using g_strcmp0(). - - -The effect of g_assert_cmpstr (s1, op, s2) is the same -as g_assert (g_strcmp0 (s1, s2) op 0). The advantage of this macro -is that it can produce a message that includes the actual values of @s1 -and @s2. - - - g_assert_cmpstr (mystring, ==, "fubar"); - - -@s1: a string (may be %NULL) -@cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. -@s2: another string (may be %NULL) -@Since: 2.16 - - - - -Debugging macro to terminate the application with a warning message -if an integer comparison fails. - - -The effect of g_assert_cmpint (n1, op, n2) is the same -as g_assert (n1 op n2). The advantage of this macro -is that it can produce a message that includes the actual values of @n1 -and @n2. - - -@n1: an integer -@cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. -@n2: another integer -@Since: 2.16 - - - - -Debugging macro to terminate the application with a warning message -if an unsigned integer comparison fails. - - -The effect of g_assert_cmpuint (n1, op, n2) is the same -as g_assert (n1 op n2). The advantage of this macro -is that it can produce a message that includes the actual values of @n1 -and @n2. - - -@n1: an unsigned integer -@cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. -@n2: another unsigned integer -@Since: 2.16 - - - - -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. - - -@n1: an unsigned integer -@cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. -@n2: another unsigned integer -@Since: 2.16 - - - - -Debugging macro to terminate the application with a warning message -if a floating point number comparison fails. - - -The effect of g_assert_cmpfloat (n1, op, n2) is the same -as g_assert (n1 op n2). The advantage of this function -is that it can produce a message that includes the actual values of @n1 -and @n2. - - -@n1: an floating point number -@cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. -@n2: another floating point number -@Since: 2.16 - - - - -Debugging macro to terminate the application with a warning message -if a method has returned a #GError. - - -The effect of g_assert_no_error (err) is the same -as g_assert (err == NULL). The advantage of this macro -is that it can produce a message that includes the error message and code. - - -@err: a #GError, possibly %NULL -@Since: 2.20 - - - - -Debugging macro to terminate the application with a warning message -if a method has not returned the correct #GError. - - -The effect of g_assert_error (err, dom, c) is the same -as g_assert (err != NULL && err->domain == dom && err->code == c). -The advantage of this macro is that it can produce a message that -includes the incorrect error message and code. - - -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 -g_assert (err != NULL) - - -@err: a #GError, possibly %NULL -@dom: the expected error domain (a #GQuark) -@c: the expected error code -@Since: 2.20 - - - - -An opaque structure representing a test case. - - - - - -An opaque structure representing a test suite. - - - - - - - - -@fixture: -@user_data: - - - - - - - -@test_name: -@data_size: -@test_data: -@data_setup: -@data_test: -@data_teardown: -@Returns: - - - - - - - -@suite_name: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@suite: -@test_case: - - - - - - - -@suite: -@nestedsuite: - - - - - - - -@suite: -@Returns: - - diff --git a/glib/gtestutils.c b/glib/gtestutils.c index 1abd9dfda..d75198dde 100644 --- a/glib/gtestutils.c +++ b/glib/gtestutils.c @@ -51,10 +51,377 @@ #include "gslice.h" +/** + * SECTION:testing + * @title: Testing + * @short_description: a test framework + * @see_also: gtester, + * gtester-report + * + * 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. + * + * + * + * Test case + * Tests (test methods) are grouped together with their + * fixture into test cases. + * + * + * Fixture + * 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. + * + * + * Test suite + * 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. + * + * + * The API is designed to handle creation and registration of test suites + * and test cases implicitly. A simple call like + * |[ + * g_test_add_func ("/misc/assertions", test_assertions); + * ]| + * creates a test suite called "misc" with a single test case named + * "assertions", which consists of running the test_assertions function. + * + * 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. + * + * GLib ships with two utilities called gtester and gtester-report to + * facilitate running tests and producing nicely formatted test reports. + */ + +/** + * g_test_quick: + * + * Returns %TRUE if tests are run in quick mode. + * + * Returns: %TRUE if in quick mode + */ + +/** + * g_test_slow: + * + * Returns %TRUE if tests are run in slow mode. + * + * Returns: %TRUE if in slow mode + */ + +/** + * g_test_thorough: + * + * Returns %TRUE if tests are run in thorough mode. + * + * Returns: %TRUE if in thorough mode + */ + +/** + * g_test_perf: + * + * Returns %TRUE if tests are run in performance mode. + * + * Returns: %TRUE if in performance mode + */ + +/** + * g_test_verbose: + * + * Returns %TRUE if tests are run in verbose mode. + * + * Returns: %TRUE if in verbose mode + */ + +/** + * g_test_quiet: + * + * Returns %TRUE if tests are run in quiet mode. + * + * Returns: %TRUE if in quied mode + */ + +/** + * g_test_queue_unref: + * @gobject: the object to unref + * + * 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(). + * + * Since: 2.16 + */ + +/** + * GTestTrapFlags: + * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to + * /dev/null 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 + * /dev/null 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 /dev/null otherwise. + * + * Test traps are guards around forked tests. + * These flags determine what traps to set. + */ + +/** + * g_test_trap_assert_passed: + * + * Assert that the last forked test passed. + * See g_test_trap_fork(). + * + * Since: 2.16 + */ + +/** + * g_test_trap_assert_failed: + * + * Assert that the last forked test failed. + * See g_test_trap_fork(). + * + * Since: 2.16 + */ + +/** + * g_test_trap_assert_stdout: + * @soutpattern: a glob-style + * pattern + * + * Assert that the stdout output of the last forked test matches + * @soutpattern. See g_test_trap_fork(). + * + * Since: 2.16 + */ + +/** + * g_test_trap_assert_stdout_unmatched: + * @soutpattern: a glob-style + * pattern + * + * Assert that the stdout output of the last forked test + * does not match @soutpattern. See g_test_trap_fork(). + * + * Since: 2.16 + */ + +/** + * g_test_trap_assert_stderr: + * @serrpattern: a glob-style + * pattern + * + * Assert that the stderr output of the last forked test + * matches @serrpattern. See g_test_trap_fork(). + * + * Since: 2.16 + */ + +/** + * g_test_trap_assert_stderr_unmatched: + * @serrpattern: a glob-style + * pattern + * + * Assert that the stderr output of the last forked test + * does not match @serrpattern. See g_test_trap_fork(). + * + * Since: 2.16 + */ + +/** + * g_test_rand_bit: + * + * Get a reproducible random bit (0 or 1), see g_test_rand_int() + * for details on test case random numbers. + * + * Since: 2.16 + */ + +/** + * g_assert: + * @expr: the expression to check + * + * 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. + * + * The macro can be turned off in final releases of code by defining + * #G_DISABLE_ASSERT when compiling the application. + */ + +/** + * g_assert_not_reached: + * + * 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. + * + * The macro can be turned off in final releases of code by defining + * #G_DISABLE_ASSERT when compiling the application. + */ + +/** + * g_assert_cmpstr: + * @s1: a string (may be %NULL) + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. + * @s2: another string (may be %NULL) + * + * Debugging macro to terminate the application with a warning + * message if a string comparison fails. The strings are compared + * using g_strcmp0(). + * + * The effect of g_assert_cmpstr (s1, op, s2) is + * the same as g_assert (g_strcmp0 (s1, s2) op 0). + * The advantage of this macro is that it can produce a message that + * includes the actual values of @s1 and @s2. + * + * |[ + * g_assert_cmpstr (mystring, ==, "fubar"); + * ]| + * + * Since: 2.16 + */ + +/** + * g_assert_cmpint: + * @n1: an integer + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. + * @n2: another integer + * + * Debugging macro to terminate the application with a warning + * message if an integer comparison fails. + * + * The effect of g_assert_cmpint (n1, op, n2) is + * the same as g_assert (n1 op n2). The advantage + * of this macro is that it can produce a message that includes the + * actual values of @n1 and @n2. + * + * Since: 2.16 + */ + +/** + * g_assert_cmpuint: + * @n1: an unsigned integer + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. + * @n2: another unsigned integer + * + * Debugging macro to terminate the application with a warning + * message if an unsigned integer comparison fails. + * + * The effect of g_assert_cmpuint (n1, op, n2) is + * the same as g_assert (n1 op n2). The advantage + * of this macro is that it can produce a message that includes the + * actual values of @n1 and @n2. + * + * Since: 2.16 + */ + +/** + * g_assert_cmphex: + * @n1: an unsigned integer + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. + * @n2: another unsigned integer + * + * 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. + * + * Since: 2.16 + */ + +/** + * g_assert_cmpfloat: + * @n1: an floating point number + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. + * @n2: another floating point number + * + * Debugging macro to terminate the application with a warning + * message if a floating point number comparison fails. + * + * The effect of g_assert_cmpfloat (n1, op, n2) is + * the same as g_assert (n1 op n2). The advantage + * of this macro is that it can produce a message that includes the + * actual values of @n1 and @n2. + * + * Since: 2.16 + */ + +/** + * g_assert_no_error: + * @err: a #GError, possibly %NULL + * + * Debugging macro to terminate the application with a warning + * message if a method has returned a #GError. + * + * The effect of g_assert_no_error (err) is + * the same as g_assert (err == NULL). The advantage + * of this macro is that it can produce a message that includes + * the error message and code. + * + * Since: 2.20 + */ + +/** + * g_assert_error: + * @err: a #GError, possibly %NULL + * @dom: the expected error domain (a #GQuark) + * @c: the expected error code + * + * Debugging macro to terminate the application with a warning + * message if a method has not returned the correct #GError. + * + * The effect of g_assert_error (err, dom, c) is + * the same as g_assert (err != NULL && err->domain + * == dom && err->code == c). The advantage of this + * macro is that it can produce a message that includes the incorrect + * error message and code. + * + * 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 + * g_assert (err != NULL) + * + * Since: 2.20 + */ + +/** + * GTestCase: + * + * An opaque structure representing a test case. + */ + +/** + * GTestSuite: + * + * An opaque structure representing a test suite. + */ + + /* Global variable for storing assertion messages; this is the counterpart to * glibc's (private) __abort_msg variable, and allows developers and crash * analysis systems like Apport and ABRT to fish out assertion messages from - * core dumps, instead of having to catch them on screen output. */ + * core dumps, instead of having to catch them on screen output. + */ char *__glib_assert_msg = NULL; /* --- structures --- */