gtestutils: Add g_test_summary() to add summary metadata to unit tests

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 <withnall@endlessm.com>

Fixes: #1450

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
 

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:
  *

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);

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 ();

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();
 }