gtestutils: Add an example of using test fixtures

Add a simple example of a test suite with two unit tests both using the
same fixture.

https://bugzilla.gnome.org/show_bug.cgi?id=743014

diff --git a/glib/gtestutils.c b/glib/gtestutils.c
index 3ac3660..edb731a 100644 (file)
--- a/glib/gtestutils.c
+++ b/glib/gtestutils.c
@@ -97,6 +97,70 @@
  * GLib ships with two utilities called [gtester][gtester] and
  * [gtester-report][gtester-report] to facilitate running tests and producing
  * nicely formatted test reports.
+ *
+ * A full example of creating a test suite with two tests using fixtures:
+ * |[<!-- language="C" -->
+ * #include <glib.h>
+ * #include <locale.h>
+ *
+ * typedef struct {
+ *   MyObject *obj;
+ *   OtherObject *helper;
+ * } MyObjectFixture;
+ *
+ * static void
+ * my_object_fixture_set_up (MyObjectFixture *fixture,
+ *                           gconstpointer user_data)
+ * {
+ *   fixture->obj = my_object_new ();
+ *   my_object_set_prop1 (fixture->obj, "some-value");
+ *   my_object_do_some_complex_setup (fixture->obj, user_data);
+ *
+ *   fixture->helper = other_object_new ();
+ * }
+ *
+ * static void
+ * my_object_fixture_tear_down (MyObjectFixture *fixture,
+ *                              gconstpointer user_data)
+ * {
+ *   g_clear_object (&fixture->helper);
+ *   g_clear_object (&fixture->obj);
+ * }
+ *
+ * static void
+ * test_my_object_test1 (MyObjectFixture *fixture,
+ *                       gconstpointer user_data)
+ * {
+ *   g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value");
+ * }
+ *
+ * static void
+ * test_my_object_test2 (MyObjectFixture *fixture,
+ *                       gconstpointer user_data)
+ * {
+ *   my_object_do_some_work_using_helper (fixture->obj, fixture->helper);
+ *   g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value");
+ * }
+ *
+ * int
+ * main (int argc, char *argv[])
+ * {
+ *   setlocale (LC_ALL, "");
+ *
+ *   g_test_init (&argc, &argv, NULL);
+ *   g_test_bug_base ("http://bugzilla.gnome.org/show_bug.cgi?id=");
+ *
+ *   // Define the tests.
+ *   g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data",
+ *               my_object_fixture_set_up, test_my_object_test1,
+ *               my_object_fixture_tear_down);
+ *   g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data",
+ *               my_object_fixture_set_up, test_my_object_test2,
+ *               my_object_fixture_tear_down);
+ *
+ *   return g_test_run ();
+ * }
+ * ]|
  */
 
 /**