diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 736b1d856..0f5d88142 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -3162,6 +3162,7 @@ g_test_failed g_test_message g_test_bug_base g_test_bug +g_test_summary GTestLogFatalFunc g_test_log_set_fatal_handler diff --git a/glib/gtestutils.c b/glib/gtestutils.c index 2ec1398ec..abdaaa607 100644 --- a/glib/gtestutils.c +++ b/glib/gtestutils.c @@ -1906,6 +1906,7 @@ g_test_bug_base (const char *uri_pattern) * and @bug_uri_snippet. * * Since: 2.16 + * See also: g_test_summary() */ void g_test_bug (const char *bug_uri_snippet) @@ -1928,6 +1929,31 @@ g_test_bug (const char *bug_uri_snippet) g_test_message ("Bug Reference: %s%s", test_uri_base, bug_uri_snippet); } +/** + * g_test_summary: + * @summary: One or two sentences summarising what the test checks, and how it + * checks it. + * + * Set the summary for a test, which describes what the test checks, and how it + * goes about checking it. This may be included in test report output, and is + * useful documentation for anyone reading the source code or modifying a test + * in future. It must be a single line. + * + * This should be called at the top of a test function. + * + * Since: 2.62 + * See also: g_test_bug() + */ +void +g_test_summary (const char *summary) +{ + g_return_if_fail (summary != NULL); + g_return_if_fail (strchr (summary, '\n') == NULL); + g_return_if_fail (strchr (summary, '\r') == NULL); + + g_test_message ("%s summary: %s", test_run_name, summary); +} + /** * g_test_get_root: * diff --git a/glib/gtestutils.h b/glib/gtestutils.h index 237b0dd10..7a0715c82 100644 --- a/glib/gtestutils.h +++ b/glib/gtestutils.h @@ -321,6 +321,8 @@ GLIB_AVAILABLE_IN_ALL void g_test_bug_base (const char *uri_pattern); GLIB_AVAILABLE_IN_ALL void g_test_bug (const char *bug_uri_snippet); +GLIB_AVAILABLE_IN_2_62 +void g_test_summary (const char *summary); /* measure test timings */ GLIB_AVAILABLE_IN_ALL void g_test_timer_start (void); diff --git a/glib/tests/testing-helper.c b/glib/tests/testing-helper.c index bc5c873fa..07820f6e7 100644 --- a/glib/tests/testing-helper.c +++ b/glib/tests/testing-helper.c @@ -47,6 +47,14 @@ test_incomplete (void) g_test_incomplete ("mind reading not implemented yet"); } +static void +test_summary (void) +{ + g_test_summary ("Tests that g_test_summary() works with TAP, by outputting a " + "known summary message in testing-helper, and checking for " + "it in the TAP output later."); +} + int main (int argc, char *argv[]) @@ -114,6 +122,10 @@ main (int argc, g_test_add_func ("/c/a", test_pass); g_test_add_func ("/d/a", test_pass); } + else if (g_strcmp0 (argv1, "summary") == 0) + { + g_test_add_func ("/summary", test_summary); + } else { g_assert_not_reached (); diff --git a/glib/tests/testing.c b/glib/tests/testing.c index f2f86cdb8..98fe66fba 100644 --- a/glib/tests/testing.c +++ b/glib/tests/testing.c @@ -1209,6 +1209,43 @@ test_tap (void) g_ptr_array_unref (argv); } +static void +test_tap_summary (void) +{ + const char *testing_helper; + GPtrArray *argv; + GError *error = NULL; + int status; + gchar *output; + + g_test_summary ("Test the output of g_test_summary() from the TAP output of a test."); + + testing_helper = g_test_get_filename (G_TEST_BUILT, "testing-helper" EXEEXT, NULL); + + argv = g_ptr_array_new (); + g_ptr_array_add (argv, (char *) testing_helper); + g_ptr_array_add (argv, "summary"); + g_ptr_array_add (argv, "--tap"); + g_ptr_array_add (argv, NULL); + + g_spawn_sync (NULL, (char **) argv->pdata, NULL, + G_SPAWN_STDERR_TO_DEV_NULL, + NULL, NULL, &output, NULL, &status, + &error); + g_assert_no_error (error); + + g_spawn_check_exit_status (status, &error); + g_assert_no_error (error); + /* Note: The test path in the output is not `/tap/summary` because it’s the + * test path from testing-helper, not from this function. */ + g_assert_nonnull (strstr (output, "\n# /summary summary: Tests that g_test_summary() " + "works with TAP, by outputting a known " + "summary message in testing-helper, and " + "checking for it in the TAP output later.\n")); + g_free (output); + g_ptr_array_unref (argv); +} + int main (int argc, char *argv[]) @@ -1288,6 +1325,7 @@ main (int argc, g_test_add_func ("/misc/timeout", test_subprocess_timed_out); g_test_add_func ("/tap", test_tap); + g_test_add_func ("/tap/summary", test_tap_summary); return g_test_run(); }