[glib: 2/3] gtestutils: Add g_test_summary() to add summary metadata to unit tests

[Philip Withnall <pwithnall src gnome org>]

commit 4da8b7b35acbbc887f74655ee3cd61b0e3d1fb97
Author: Philip Withnall <withnall endlessm com>
Date:   Wed May 15 13:33:52 2019 +0100

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