From 4da8b7b35acbbc887f74655ee3cd61b0e3d1fb97 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 15 May 2019 13:33:52 +0100 Subject: [PATCH] gtestutils: Add g_test_summary() to add summary metadata to unit tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is a new function along the same lines as g_test_bug(): to allow developers to annotate unit tests with information about the test (what it tests, how it tests it) for future developers to read and learn from. It will also output this summary as a comment in the test’s TAP output, which might clarify test results. Includes a unit test. Signed-off-by: Philip Withnall Fixes: #1450 --- docs/reference/glib/glib-sections.txt | 1 + glib/gtestutils.c | 26 ++++++++++++++++++ glib/gtestutils.h | 2 ++ glib/tests/testing-helper.c | 12 +++++++++ glib/tests/testing.c | 38 +++++++++++++++++++++++++++ 5 files changed, 79 insertions(+) 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(); }