Merge branch '1450-test-summaries' into 'master'

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

Closes #1450

See merge request GNOME/glib!847

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

@@ -17,6 +17,7 @@
  */
 
 #include <glib.h>
+#include <locale.h>
 #ifdef G_OS_WIN32
 #include <fcntl.h>
 #include <io.h>
@@ -46,12 +47,22 @@ 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[])
 {
   char *argv1;
 
+  setlocale (LC_ALL, "");
+
 #ifdef G_OS_WIN32
   /* Windows opens std streams in text mode, with \r\n EOLs.
    * Sometimes it's easier to force a switch to binary mode than
@@ -111,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

@@ -29,7 +29,7 @@
 #define G_LOG_DOMAIN "testing"
 
 #include <glib.h>
-
+#include <locale.h>
 #include <stdlib.h>
 #include <string.h>
 
@@ -1209,12 +1209,51 @@ 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[])
 {
   argv0 = argv[0];
 
+  setlocale (LC_ALL, "");
+
   g_test_init (&argc, &argv, NULL);
 
   g_test_add_func ("/random-generator/rand-1", test_rand1);
@@ -1286,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();
 }