glib/gtestutils.c

   1 /* GLib testing utilities
   2  * Copyright (C) 2007 Imendio AB
   3  * Authors: Tim Janik, Sven Herzberg
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20 #include "config.h"
  21 #include "gtestutils.h"
  22 #include "galias.h"
  23 #include <sys/types.h>
  24 #include <sys/wait.h>
  25 #include <fcntl.h>
  26 #include <string.h>
  27 #include <stdlib.h>
  28 #include <unistd.h>
  29 #include <errno.h>
  30 #include <signal.h>
  31 #ifdef HAVE_SYS_SELECT_H
  32 #include <sys/select.h>
  33 #endif /* HAVE_SYS_SELECT_H */
  34
  35 /* --- structures --- */
  36 struct GTestCase
  37 {
  38   gchar  *name;
  39   guint   fixture_size;
  40   void (*fixture_setup) (void*);
  41   void (*fixture_test) (void*);
  42   void (*fixture_teardown) (void*);
  43 };
  44 struct GTestSuite
  45 {
  46   gchar  *name;
  47   GSList *suites;
  48   GSList *cases;
  49 };
  50 typedef struct DestroyEntry DestroyEntry;
  51 struct DestroyEntry
  52 {
  53   DestroyEntry *next;
  54   GDestroyNotify destroy_func;
  55   gpointer       destroy_data;
  56 };
  57
  58 /* --- prototypes --- */
  59 static void                     test_run_seed           (const gchar *rseed);
  60 static void                     test_trap_clear         (void);
  61 static guint8*                  g_test_log_dump         (GTestLogMsg *msg,
  62                                                          guint       *len);
  63
  64 /* --- variables --- */
  65 static int         test_log_fd = -1;
  66 static gboolean    test_mode_fatal = TRUE;
  67 static gboolean    g_test_run_once = TRUE;
  68 static gboolean    test_run_list = FALSE;
  69 static gchar      *test_run_seedstr = NULL;
  70 static GRand      *test_run_rand = NULL;
  71 static gchar      *test_run_name = "";
  72 static guint       test_run_forks = 0;
  73 static guint       test_run_count = 0;
  74 static guint       test_skip_count = 0;
  75 static GTimer     *test_user_timer = NULL;
  76 static double      test_user_stamp = 0;
  77 static GSList     *test_paths = NULL;
  78 static GTestSuite *test_suite_root = NULL;
  79 static int         test_trap_last_status = 0;
  80 static int         test_trap_last_pid = 0;
  81 static char       *test_trap_last_stdout = NULL;
  82 static char       *test_trap_last_stderr = NULL;
  83 static char       *test_uri_base = NULL;
  84 static gboolean    test_debug_log = FALSE;
  85 static DestroyEntry *test_destroy_queue = NULL;
  86 const GTestConfig *g_test_config_vars = NULL;
  87 static GTestConfig mutable_test_config_vars = {
  88   TRUE,         /* test_quick */
  89   FALSE,        /* test_perf */
  90   FALSE,        /* test_verbose */
  91   FALSE,        /* test_quiet */
  92 };
  93
  94 /* --- functions --- */
  95 const char*
  96 g_test_log_type_name (GTestLogType log_type)
  97 {
  98   switch (log_type)
  99     {
 100     case G_TEST_LOG_NONE:               return "none";
 101     case G_TEST_LOG_ERROR:              return "error";
 102     case G_TEST_LOG_START_BINARY:       return "binary";
 103     case G_TEST_LOG_LIST_CASE:          return "list";
 104     case G_TEST_LOG_SKIP_CASE:          return "skip";
 105     case G_TEST_LOG_START_CASE:         return "start";
 106     case G_TEST_LOG_STOP_CASE:          return "stop";
 107     case G_TEST_LOG_MIN_RESULT:         return "minperf";
 108     case G_TEST_LOG_MAX_RESULT:         return "maxperf";
 109     case G_TEST_LOG_MESSAGE:            return "message";
 110     }
 111   return "???";
 112 }
 113
 114 static void
 115 g_test_log_send (guint         n_bytes,
 116                  const guint8 *buffer)
 117 {
 118   if (test_log_fd >= 0)
 119     {
 120       int r;
 121       do
 122         r = write (test_log_fd, buffer, n_bytes);
 123       while (r < 0 && errno == EINTR);
 124     }
 125   if (test_debug_log)
 126     {
 127       GTestLogBuffer *lbuffer = g_test_log_buffer_new();
 128       GTestLogMsg *msg;
 129       guint ui;
 130       g_test_log_buffer_push (lbuffer, n_bytes, buffer);
 131       msg = g_test_log_buffer_pop (lbuffer);
 132       g_assert (msg != NULL); // FIXME: should be g_awrn_if_fail
 133       g_assert (lbuffer->data->len == 0); // FIXME: should be g_awrn_if_fail
 134       g_test_log_buffer_free (lbuffer);
 135       /* print message */
 136       g_printerr ("{*LOG(%s)", g_test_log_type_name (msg->log_type));
 137       for (ui = 0; ui < msg->n_strings; ui++)
 138         g_printerr (":{%s}", msg->strings[ui]);
 139       if (msg->n_nums)
 140         {
 141           g_printerr (":(");
 142           for (ui = 0; ui < msg->n_nums; ui++)
 143             g_printerr ("%s%.16Lg", ui ? ";" : "", msg->nums[ui]);
 144           g_printerr (")");
 145         }
 146       g_printerr (":LOG*}\n");
 147       g_test_log_msg_free (msg);
 148     }
 149 }
 150
 151 static void
 152 g_test_log (GTestLogType lbit,
 153             const gchar *string1,
 154             const gchar *string2,
 155             guint        n_args,
 156             long double *largs)
 157 {
 158   gboolean fail = lbit == G_TEST_LOG_STOP_CASE && largs[0] != 0;
 159   GTestLogMsg msg;
 160   gchar *astrings[3] = { NULL, NULL, NULL };
 161   guint8 *dbuffer;
 162   guint32 dbufferlen;
 163
 164   switch (lbit)
 165     {
 166     case G_TEST_LOG_STOP_CASE:
 167       if (!g_test_quiet())
 168         g_print ("%s\n", fail ? "FAIL" : "OK");
 169       if (fail && test_mode_fatal)
 170         abort();
 171       break;
 172     case G_TEST_LOG_MIN_RESULT:
 173       if (g_test_verbose())
 174         g_print ("(MINPERF:%s)\n", string1);
 175       break;
 176     case G_TEST_LOG_MAX_RESULT:
 177       if (g_test_verbose())
 178         g_print ("(MAXPERF:%s)\n", string1);
 179       break;
 180     case G_TEST_LOG_MESSAGE:
 181       if (g_test_verbose())
 182         g_print ("(MSG: %s)\n", string1);
 183       break;
 184     default: ;
 185     }
 186
 187   msg.log_type = lbit;
 188   msg.n_strings = (string1 != NULL) + (string1 && string2);
 189   msg.strings = astrings;
 190   astrings[0] = (gchar*) string1;
 191   astrings[1] = astrings[0] ? (gchar*) string2 : NULL;
 192   msg.n_nums = n_args;
 193   msg.nums = largs;
 194   dbuffer = g_test_log_dump (&msg, &dbufferlen);
 195   g_test_log_send (dbufferlen, dbuffer);
 196   g_free (dbuffer);
 197
 198   switch (lbit)
 199     {
 200     case G_TEST_LOG_START_CASE:
 201       if (!g_test_quiet())
 202         g_print ("%s: ", string1);
 203       break;
 204     default: ;
 205     }
 206 }
 207
 208 static void
 209 parse_args (gint    *argc_p,
 210             gchar ***argv_p)
 211 {
 212   guint argc = *argc_p;
 213   gchar **argv = *argv_p;
 214   guint i, e;
 215   /* parse known args */
 216   for (i = 1; i < argc; i++)
 217     {
 218       if (strcmp (argv[i], "--g-fatal-warnings") == 0)
 219         {
 220           GLogLevelFlags fatal_mask = (GLogLevelFlags) g_log_set_always_fatal ((GLogLevelFlags) G_LOG_FATAL_MASK);
 221           fatal_mask = (GLogLevelFlags) (fatal_mask | G_LOG_LEVEL_WARNING | G_LOG_LEVEL_CRITICAL);
 222           g_log_set_always_fatal (fatal_mask);
 223           argv[i] = NULL;
 224         }
 225       else if (strcmp (argv[i], "--keep-going") == 0 ||
 226                strcmp (argv[i], "-k") == 0)
 227         {
 228           test_mode_fatal = FALSE;
 229           argv[i] = NULL;
 230         }
 231       else if (strcmp (argv[i], "--debug-log") == 0)
 232         {
 233           test_debug_log = TRUE;
 234           argv[i] = NULL;
 235         }
 236       else if (strcmp ("--GTestLogFD", argv[i]) == 0 || strncmp ("--GTestLogFD=", argv[i], 13) == 0)
 237         {
 238           gchar *equal = argv[i] + 12;
 239           if (*equal == '=')
 240             test_log_fd = g_ascii_strtoull (equal + 1, NULL, 0);
 241           else if (i + 1 < argc)
 242             {
 243               argv[i++] = NULL;
 244               test_log_fd = g_ascii_strtoull (argv[i], NULL, 0);
 245             }
 246           argv[i] = NULL;
 247         }
 248       else if (strcmp ("--GTestSkipCount", argv[i]) == 0 || strncmp ("--GTestSkipCount=", argv[i], 17) == 0)
 249         {
 250           gchar *equal = argv[i] + 16;
 251           if (*equal == '=')
 252             test_skip_count = g_ascii_strtoull (equal + 1, NULL, 0);
 253           else if (i + 1 < argc)
 254             {
 255               argv[i++] = NULL;
 256               test_skip_count = g_ascii_strtoull (argv[i], NULL, 0);
 257             }
 258           argv[i] = NULL;
 259         }
 260       else if (strcmp ("-p", argv[i]) == 0 || strncmp ("-p=", argv[i], 3) == 0)
 261         {
 262           gchar *equal = argv[i] + 2;
 263           if (*equal == '=')
 264             test_paths = g_slist_prepend (test_paths, equal + 1);
 265           else if (i + 1 < argc)
 266             {
 267               argv[i++] = NULL;
 268               test_paths = g_slist_prepend (test_paths, argv[i]);
 269             }
 270           argv[i] = NULL;
 271         }
 272       else if (strcmp ("-m", argv[i]) == 0 || strncmp ("-m=", argv[i], 3) == 0)
 273         {
 274           gchar *equal = argv[i] + 2;
 275           const gchar *mode = "";
 276           if (*equal == '=')
 277             mode = equal + 1;
 278           else if (i + 1 < argc)
 279             {
 280               argv[i++] = NULL;
 281               mode = argv[i];
 282             }
 283           if (strcmp (mode, "perf") == 0)
 284             mutable_test_config_vars.test_perf = TRUE;
 285           else if (strcmp (mode, "slow") == 0)
 286             mutable_test_config_vars.test_quick = FALSE;
 287           else if (strcmp (mode, "quick") == 0)
 288             {
 289               mutable_test_config_vars.test_quick = TRUE;
 290               mutable_test_config_vars.test_perf = FALSE;
 291             }
 292           else
 293             g_error ("unknown test mode: -m %s", mode);
 294           argv[i] = NULL;
 295         }
 296       else if (strcmp ("-q", argv[i]) == 0 || strcmp ("--quiet", argv[i]) == 0)
 297         {
 298           mutable_test_config_vars.test_quiet = TRUE;
 299           mutable_test_config_vars.test_verbose = FALSE;
 300           argv[i] = NULL;
 301         }
 302       else if (strcmp ("--verbose", argv[i]) == 0)
 303         {
 304           mutable_test_config_vars.test_quiet = FALSE;
 305           mutable_test_config_vars.test_verbose = TRUE;
 306           argv[i] = NULL;
 307         }
 308       else if (strcmp ("-l", argv[i]) == 0)
 309         {
 310           test_run_list = TRUE;
 311           argv[i] = NULL;
 312         }
 313       else if (strcmp ("--seed", argv[i]) == 0 || strncmp ("--seed=", argv[i], 7) == 0)
 314         {
 315           gchar *equal = argv[i] + 6;
 316           if (*equal == '=')
 317             test_run_seedstr = equal + 1;
 318           else if (i + 1 < argc)
 319             {
 320               argv[i++] = NULL;
 321               test_run_seedstr = argv[i];
 322             }
 323           argv[i] = NULL;
 324         }
 325     }
 326   /* collapse argv */
 327   e = 1;
 328   for (i = 1; i < argc; i++)
 329     if (argv[i])
 330       {
 331         argv[e++] = argv[i];
 332         if (i >= e)
 333           argv[i] = NULL;
 334       }
 335   *argc_p = e;
 336 }
 337
 338 /**
 339  * g_test_init:
 340  * @argc: Address of the @argc parameter of the main() function.
 341  *        Changed if any arguments were handled.
 342  * @argv: Address of the @argv parameter of main().
 343  *        Any parameters understood by g_test_init() stripped before return.
 344  *
 345  * Initialize the GLib testing framework, e.g. by seeding the
 346  * test random number generator, the name for g_get_prgname()
 347  * and parsing test related command line args.
 348  * So far, the following arguments are understood:
 349  * <informalexample>
 350  * -l                   list test cases available in a test executable.
 351  * --seed RANDOMSEED    provide a random seed to reproduce test runs using random numbers.
 352  * --verbose            run tests verbosely.
 353  * -q, --quiet          run tests quietly.
 354  * -p TESTPATH          execute all tests matching TESTPATH.
 355  * -m {perf|slow|quick} execute tests according to this test modes:
 356  *                      perf - performance tests, may take long and report results.
 357  *                      slow - slow and thorough tests, may take quite long and maximize coverage.
 358  *                      quick - quick tests, should run really quickly and give good coverage.
 359  * --debug-log          debug test logging output.
 360  * -k, --keep-going     gtester specific argument.
 361  * --GTestLogFD N       gtester specific argument.
 362  * --GTestSkipCount N   gtester specific argument.
 363  * </informalexample>
 364  */
 365 void
 366 g_test_init (int    *argc,
 367              char ***argv,
 368              ...)
 369 {
 370   static char seedstr[4 + 4 * 8 + 1];
 371   va_list args;
 372   gpointer vararg1;
 373   /* make warnings and criticals fatal for all test programs */
 374   GLogLevelFlags fatal_mask = (GLogLevelFlags) g_log_set_always_fatal ((GLogLevelFlags) G_LOG_FATAL_MASK);
 375   fatal_mask = (GLogLevelFlags) (fatal_mask | G_LOG_LEVEL_WARNING | G_LOG_LEVEL_CRITICAL);
 376   /* check caller args */
 377   g_return_if_fail (argc != NULL);
 378   g_return_if_fail (argv != NULL);
 379   g_return_if_fail (g_test_config_vars == NULL);
 380   g_test_config_vars = &mutable_test_config_vars;
 381
 382   va_start (args, argv);
 383   vararg1 = va_arg (args, gpointer); /* reserved for future extensions */
 384   va_end (args);
 385   g_return_if_fail (vararg1 == NULL);
 386
 387   /* setup random seed string */
 388   g_snprintf (seedstr, sizeof (seedstr), "R02S%08x%08x%08x%08x", g_random_int(), g_random_int(), g_random_int(), g_random_int());
 389   test_run_seedstr = seedstr;
 390
 391   /* parse args, sets up mode, changes seed, etc. */
 392   parse_args (argc, argv);
 393   if (!g_get_prgname())
 394     g_set_prgname ((*argv)[0]);
 395
 396   /* verify GRand reliability, needed for reliable seeds */
 397   if (1)
 398     {
 399       GRand *rg = g_rand_new_with_seed (0xc8c49fb6);
 400       guint32 t1 = g_rand_int (rg), t2 = g_rand_int (rg), t3 = g_rand_int (rg), t4 = g_rand_int (rg);
 401       // g_print ("GRand-current: 0x%x 0x%x 0x%x 0x%x\n", t1, t2, t3, t4);
 402       if (t1 != 0xfab39f9b || t2 != 0xb948fb0e || t3 != 0x3d31be26 || t4 != 0x43a19d66)
 403         g_warning ("random numbers are not GRand-2.2 compatible, seeds may be broken (check $G_RANDOM_VERSION)");
 404       g_rand_free (rg);
 405     }
 406
 407   /* check rand seed */
 408   test_run_seed (test_run_seedstr);
 409
 410   /* report program start */
 411   g_test_log (G_TEST_LOG_START_BINARY, g_get_prgname(), test_run_seedstr, 0, NULL);
 412 }
 413
 414 static void
 415 test_run_seed (const gchar *rseed)
 416 {
 417   guint seed_failed = 0;
 418   if (test_run_rand)
 419     g_rand_free (test_run_rand);
 420   test_run_rand = NULL;
 421   while (strchr (" \t\v\r\n\f", *rseed))
 422     rseed++;
 423   if (strncmp (rseed, "R02S", 4) == 0)  // seed for random generator 02 (GRand-2.2)
 424     {
 425       const char *s = rseed + 4;
 426       if (strlen (s) >= 32)             // require 4 * 8 chars
 427         {
 428           guint32 seedarray[4];
 429           gchar *p, hexbuf[9] = { 0, };
 430           memcpy (hexbuf, s + 0, 8);
 431           seedarray[0] = g_ascii_strtoull (hexbuf, &p, 16);
 432           seed_failed += p != NULL && *p != 0;
 433           memcpy (hexbuf, s + 8, 8);
 434           seedarray[1] = g_ascii_strtoull (hexbuf, &p, 16);
 435           seed_failed += p != NULL && *p != 0;
 436           memcpy (hexbuf, s + 16, 8);
 437           seedarray[2] = g_ascii_strtoull (hexbuf, &p, 16);
 438           seed_failed += p != NULL && *p != 0;
 439           memcpy (hexbuf, s + 24, 8);
 440           seedarray[3] = g_ascii_strtoull (hexbuf, &p, 16);
 441           seed_failed += p != NULL && *p != 0;
 442           if (!seed_failed)
 443             {
 444               test_run_rand = g_rand_new_with_seed_array (seedarray, 4);
 445               return;
 446             }
 447         }
 448     }
 449   g_error ("Unknown or invalid random seed: %s", rseed);
 450 }
 451
 452 /**
 453  * g_test_rand_int:
 454  *
 455  * Get a reproducable random integer number.
 456  * The random numbers generate by the g_test_rand_*() family of functions
 457  * change with every new test program start, unless the --seed option is
 458  * given when starting test programs.
 459  * For individual test cases however, the random number generator is
 460  * reseeded, to avoid dependencies between tests and to make --seed
 461  * effective for all test cases.
 462  *
 463  * Returns: a random number from the seeded random number generator.
 464  */
 465 gint32
 466 g_test_rand_int (void)
 467 {
 468   return g_rand_int (test_run_rand);
 469 }
 470
 471 /**
 472  * g_test_rand_int_range:
 473  * @begin: the minimum value returned by this function
 474  * @end:   the smallest value not to be returned by this function
 475  *
 476  * Get a reproducable random integer number out of a specified range,
 477  * see g_test_rand_int() for details on test case random numbers.
 478  *
 479  * Returns a number with @begin <= number < @end.
 480  */
 481 gint32
 482 g_test_rand_int_range (gint32          begin,
 483                        gint32          end)
 484 {
 485   return g_rand_int_range (test_run_rand, begin, end);
 486 }
 487
 488 /**
 489  * g_test_rand_double:
 490  *
 491  * Get a reproducable random floating point number,
 492  * see g_test_rand_int() for details on test case random numbers.
 493  *
 494  * Return a random number from the seeded random number generator.
 495  */
 496 double
 497 g_test_rand_double (void)
 498 {
 499   return g_rand_double (test_run_rand);
 500 }
 501
 502 /**
 503  * g_test_rand_double_range:
 504  * @range_start: the minimum value returned by this function
 505  * @range_end: the minimum value not returned by this function
 506  *
 507  * Get a reproducable random floating pointer number out of a specified range,
 508  * see g_test_rand_int() for details on test case random numbers.
 509  *
 510  * Returns a number with @range_start <= number < @range_end.
 511  */
 512 double
 513 g_test_rand_double_range (double          range_start,
 514                           double          range_end)
 515 {
 516   return g_rand_double_range (test_run_rand, range_start, range_end);
 517 }
 518
 519 /**
 520  * g_test_timer_start:
 521  *
 522  * Start a timing test. Call g_test_timer_elapsed() when the task is supposed
 523  * to be done. Call this function again to restart the timer.
 524  */
 525 void
 526 g_test_timer_start (void)
 527 {
 528   if (!test_user_timer)
 529     test_user_timer = g_timer_new();
 530   test_user_stamp = 0;
 531   g_timer_start (test_user_timer);
 532 }
 533
 534 /**
 535  * g_test_timer_elapsed:
 536  *
 537  * Get the time since the last start of the timer with g_test_timer_start().
 538  */
 539 double
 540 g_test_timer_elapsed (void)
 541 {
 542   test_user_stamp = test_user_timer ? g_timer_elapsed (test_user_timer, NULL) : 0;
 543   return test_user_stamp;
 544 }
 545
 546 /**
 547  * g_test_timer_last:
 548  *
 549  * Report the last result of g_test_timer_elapsed().
 550  */
 551 double
 552 g_test_timer_last (void)
 553 {
 554   return test_user_stamp;
 555 }
 556
 557 /**
 558  * g_test_minimized_result:
 559  * @minimized_quantity: the reported value
 560  * @format: the format string of the report message
 561  *
 562  * Report the result of a performance or measurement test.
 563  * The test should generally strive to minimize the reported
 564  * quantities (smaller values are better than larger ones),
 565  * this and @minimized_quantity can determine sorting
 566  * order for test result reports.
 567  */
 568 void
 569 g_test_minimized_result (double          minimized_quantity,
 570                          const char     *format,
 571                          ...)
 572 {
 573   long double largs = minimized_quantity;
 574   gchar *buffer;
 575   va_list args;
 576   va_start (args, format);
 577   buffer = g_strdup_vprintf (format, args);
 578   va_end (args);
 579   g_test_log (G_TEST_LOG_MIN_RESULT, buffer, NULL, 1, &largs);
 580   g_free (buffer);
 581 }
 582
 583 /**
 584  * g_test_minimized_result:
 585  * @maximized_quantity: the reported value
 586  * @format: the format string of the report message
 587  *
 588  * Report the result of a performance or measurement test.
 589  * The test should generally strive to maximize the reported
 590  * quantities (larger values are better than smaller ones),
 591  * this and @maximized_quantity can determine sorting
 592  * order for test result reports.
 593  */
 594 void
 595 g_test_maximized_result (double          maximized_quantity,
 596                          const char     *format,
 597                          ...)
 598 {
 599   long double largs = maximized_quantity;
 600   gchar *buffer;
 601   va_list args;
 602   va_start (args, format);
 603   buffer = g_strdup_vprintf (format, args);
 604   va_end (args);
 605   g_test_log (G_TEST_LOG_MAX_RESULT, buffer, NULL, 1, &largs);
 606   g_free (buffer);
 607 }
 608
 609 /**
 610  * g_test_message:
 611  * @format: the format string
 612  * @...:    printf-like arguments to @format
 613  *
 614  * Add a message to the test report.
 615  */
 616 void
 617 g_test_message (const char *format,
 618                 ...)
 619 {
 620   gchar *buffer;
 621   va_list args;
 622   va_start (args, format);
 623   buffer = g_strdup_vprintf (format, args);
 624   va_end (args);
 625   g_test_log (G_TEST_LOG_MESSAGE, buffer, NULL, 0, NULL);
 626   g_free (buffer);
 627 }
 628
 629 /**
 630  * g_test_bug_base:
 631  * @uri_pattern: the base pattern for bug URIs
 632  *
 633  * Specify the base URI for bug reports.
 634  * The base URI is used to construct bug report messages for
 635  * g_test_message() when g_test_bug() is called.
 636  * Calling this function outside of a test case sets the
 637  * default base URI for all test cases. Calling it from within
 638  * a test case changes the base URI for the scope of the test
 639  * case only.
 640  * Bug URIs are constructed by appending a bug specific URI
 641  * portion to @uri_pattern, or by replacing the special string
 642  * '%s' within @uri_pattern if that is present.
 643  */
 644 void
 645 g_test_bug_base (const char *uri_pattern)
 646 {
 647   g_free (test_uri_base);
 648   test_uri_base = g_strdup (uri_pattern);
 649 }
 650
 651 /**
 652  * g_test_bug:
 653  * @bug_uri_snippet: Bug specific bug tracker URI portion.
 654  *
 655  * This function adds a message to test reports that
 656  * associates a bug URI with a test case.
 657  * Bug URIs are constructed from a base URI set with g_test_bug_base()
 658  * and @bug_uri_snippet.
 659  */
 660 void
 661 g_test_bug (const char *bug_uri_snippet)
 662 {
 663   char *c;
 664   g_return_if_fail (test_uri_base != NULL);
 665   g_return_if_fail (bug_uri_snippet != NULL);
 666   c = strstr (test_uri_base, "%s");
 667   if (c)
 668     {
 669       char *b = g_strndup (test_uri_base, c - test_uri_base);
 670       char *s = g_strconcat (b, bug_uri_snippet, c + 2, NULL);
 671       g_free (b);
 672       g_test_message ("Bug Reference: %s", s);
 673       g_free (s);
 674     }
 675   else
 676     g_test_message ("Bug Reference: %s%s", test_uri_base, bug_uri_snippet);
 677 }
 678
 679 /**
 680  * g_test_get_root:
 681  *
 682  * Get the toplevel test suite for the test path API.
 683  *
 684  * Returns: the toplevel #GTestSuite
 685  */
 686 GTestSuite*
 687 g_test_get_root (void)
 688 {
 689   if (!test_suite_root)
 690     {
 691       test_suite_root = g_test_create_suite ("root");
 692       g_free (test_suite_root->name);
 693       test_suite_root->name = g_strdup ("");
 694     }
 695   return test_suite_root;
 696 }
 697
 698 /**
 699  * g_test_run:
 700  *
 701  * Runs all tests under the toplevel suite which can be retrieved
 702  * with g_test_get_root(). Similar to g_test_run_suite(), the test
 703  * cases to be run are filtered according to
 704  * test path arguments (-p <testpath>) as parsed by g_test_init().
 705  * g_test_run_suite() or g_test_run() may only be called once
 706  * in a program.
 707  */
 708 int
 709 g_test_run (void)
 710 {
 711   return g_test_run_suite (g_test_get_root());
 712 }
 713
 714 /**
 715  * g_test_create_case:
 716  * @test_name:     the name for the test case
 717  * @data_size:     the size of the fixture data structure
 718  * @data_setup:    the function to set up the fixture data
 719  * @data_test:     the actual test function
 720  * @data_teardown: the function to teardown the fixture data
 721  *
 722  * Create a new #GTestCase, named @test_name, this API is fairly
 723  * low level, calling g_test_add() or g_test_add_func() is preferable.
 724  * When this test is executed, a fixture structure of size @data_size
 725  * will be allocated and filled with 0s. Then data_setup() is called
 726  * to initialize the fixture. After fixture setup, the actual test
 727  * function data_test() is called. Once the test run completed, the
 728  * fixture structure is torn down  by calling data_teardown() and
 729  * after that the memory is released.
 730  * Splitting up a test run into fixture setup, test function and
 731  * fixture teardown is most usful if the same fixture is used for
 732  * multiple tests. In this cases, g_test_create_case() will be
 733  * called with the same fixture, but varying @test_name and
 734  * @data_test arguments.
 735  *
 736  * Returns a newly allocated #GTestCase.
 737  */
 738 GTestCase*
 739 g_test_create_case (const char     *test_name,
 740                     gsize           data_size,
 741                     void          (*data_setup) (void),
 742                     void          (*data_test) (void),
 743                     void          (*data_teardown) (void))
 744 {
 745   g_return_val_if_fail (test_name != NULL, NULL);
 746   g_return_val_if_fail (strchr (test_name, '/') == NULL, NULL);
 747   g_return_val_if_fail (test_name[0] != 0, NULL);
 748   g_return_val_if_fail (data_test != NULL, NULL);
 749   GTestCase *tc = g_slice_new0 (GTestCase);
 750   tc->name = g_strdup (test_name);
 751   tc->fixture_size = data_size;
 752   tc->fixture_setup = (void*) data_setup;
 753   tc->fixture_test = (void*) data_test;
 754   tc->fixture_teardown = (void*) data_teardown;
 755   return tc;
 756 }
 757
 758 void
 759 g_test_add_vtable (const char     *testpath,
 760                    gsize           data_size,
 761                    void          (*data_setup)    (void),
 762                    void          (*fixture_test_func) (void),
 763                    void          (*data_teardown) (void))
 764 {
 765   gchar **segments;
 766   guint ui;
 767   GTestSuite *suite;
 768
 769   g_return_if_fail (testpath != NULL);
 770   g_return_if_fail (testpath[0] == '/');
 771   g_return_if_fail (fixture_test_func != NULL);
 772
 773   suite = g_test_get_root();
 774   segments = g_strsplit (testpath, "/", -1);
 775   for (ui = 0; segments[ui] != NULL; ui++)
 776     {
 777       const char *seg = segments[ui];
 778       gboolean islast = segments[ui + 1] == NULL;
 779       if (islast && !seg[0])
 780         g_error ("invalid test case path: %s", testpath);
 781       else if (!seg[0])
 782         continue;       // initial or duplicate slash
 783       else if (!islast)
 784         {
 785           GTestSuite *csuite = g_test_create_suite (seg);
 786           g_test_suite_add_suite (suite, csuite);
 787           suite = csuite;
 788         }
 789       else /* islast */
 790         {
 791           GTestCase *tc = g_test_create_case (seg, data_size, data_setup, fixture_test_func, data_teardown);
 792           g_test_suite_add (suite, tc);
 793         }
 794     }
 795   g_strfreev (segments);
 796 }
 797
 798 /**
 799  * g_test_add_func:
 800  * @testpath:   Slash seperated test case path name for the test.
 801  * @test_func:  The test function to invoke for this test.
 802  *
 803  * Create a new test case, similar to g_test_create_case(). However
 804  * the test is assumed to use no fixture, and test suites are automatically
 805  * created on the fly and added to the root fixture, based on the
 806  * slash seperated portions of @testpath.
 807  */
 808 void
 809 g_test_add_func (const char     *testpath,
 810                  void          (*test_func) (void))
 811 {
 812   g_return_if_fail (testpath != NULL);
 813   g_return_if_fail (testpath[0] == '/');
 814   g_return_if_fail (test_func != NULL);
 815   g_test_add_vtable (testpath, 0, NULL, test_func, NULL);
 816 }
 817
 818 /**
 819  * g_test_create_suite:
 820  * @suite_name: a name for the suite
 821  *
 822  * Create a new test suite with the name @suite_name.
 823  *
 824  * Returns: A newly allocated #GTestSuite instance.
 825  */
 826 GTestSuite*
 827 g_test_create_suite (const char *suite_name)
 828 {
 829   g_return_val_if_fail (suite_name != NULL, NULL);
 830   g_return_val_if_fail (strchr (suite_name, '/') == NULL, NULL);
 831   g_return_val_if_fail (suite_name[0] != 0, NULL);
 832   GTestSuite *ts = g_slice_new0 (GTestSuite);
 833   ts->name = g_strdup (suite_name);
 834   return ts;
 835 }
 836
 837 /**
 838  * g_test_suite_add:
 839  * @suite: a #GTestSuite
 840  * @test_case: a #GTestCase
 841  *
 842  * Adds @test_case to @suite.
 843  */
 844 void
 845 g_test_suite_add (GTestSuite     *suite,
 846                   GTestCase      *test_case)
 847 {
 848   g_return_if_fail (suite != NULL);
 849   g_return_if_fail (test_case != NULL);
 850   suite->cases = g_slist_prepend (suite->cases, test_case);
 851 }
 852
 853 /**
 854  * g_test_suite_add_suite:
 855  * @suite:       a #GTestSuite
 856  * @nestedsuite: another #GTestSuite
 857  *
 858  * Adds @nestedsuite to @suite.
 859  */
 860 void
 861 g_test_suite_add_suite (GTestSuite     *suite,
 862                         GTestSuite     *nestedsuite)
 863 {
 864   g_return_if_fail (suite != NULL);
 865   g_return_if_fail (nestedsuite != NULL);
 866   suite->suites = g_slist_prepend (suite->suites, nestedsuite);
 867 }
 868
 869 /**
 870  * g_test_queue_free:
 871  * @gfree_pointer: the pointer to be stored.
 872  *
 873  * Enqueue a pointer to be released with g_free() during the next
 874  * teardown phase. This is equivalent to calling g_test_queue_destroy()
 875  * with a destroy callback of g_free().
 876  */
 877 void
 878 g_test_queue_free (gpointer gfree_pointer)
 879 {
 880   if (gfree_pointer)
 881     g_test_queue_destroy (g_free, gfree_pointer);
 882 }
 883
 884 /**
 885  * g_test_queue_destroy:
 886  * @destroy_func:       Destroy callback for teardown phase.
 887  * @destroy_data:       Destroy callback data.
 888  *
 889  * This function enqueus a callback @destroy_func() to be executed
 890  * during the next test case teardown phase. This is most useful
 891  * to auto destruct allocted test resources at the end of a test run.
 892  * Resources are released in reverse queue order, that means enqueueing
 893  * callback A before callback B will cause B() to be called before
 894  * A() during teardown.
 895  */
 896 void
 897 g_test_queue_destroy (GDestroyNotify destroy_func,
 898                       gpointer       destroy_data)
 899 {
 900   DestroyEntry *dentry;
 901   g_return_if_fail (destroy_func != NULL);
 902   dentry = g_slice_new0 (DestroyEntry);
 903   dentry->destroy_func = destroy_func;
 904   dentry->destroy_data = destroy_data;
 905   dentry->next = test_destroy_queue;
 906   test_destroy_queue = dentry;
 907 }
 908
 909 static int
 910 test_case_run (GTestCase *tc)
 911 {
 912   gchar *old_name = test_run_name, *old_base = g_strdup (test_uri_base);
 913   test_run_name = g_strconcat (old_name, "/", tc->name, NULL);
 914   if (++test_run_count <= test_skip_count)
 915     g_test_log (G_TEST_LOG_SKIP_CASE, test_run_name, NULL, 0, NULL);
 916   else if (test_run_list)
 917     {
 918       g_print ("%s\n", test_run_name);
 919       g_test_log (G_TEST_LOG_LIST_CASE, test_run_name, NULL, 0, NULL);
 920     }
 921   else
 922     {
 923       GTimer *test_run_timer = g_timer_new();
 924       long double largs[3];
 925       g_test_log (G_TEST_LOG_START_CASE, test_run_name, NULL, 0, NULL);
 926       test_run_forks = 0;
 927       g_timer_start (test_run_timer);
 928       void *fixture = g_malloc0 (tc->fixture_size);
 929       test_run_seed (test_run_seedstr);
 930       if (tc->fixture_setup)
 931         tc->fixture_setup (fixture);
 932       tc->fixture_test (fixture);
 933       test_trap_clear();
 934       while (test_destroy_queue)
 935         {
 936           DestroyEntry *dentry = test_destroy_queue;
 937           test_destroy_queue = dentry->next;
 938           dentry->destroy_func (dentry->destroy_data);
 939           g_slice_free (DestroyEntry, dentry);
 940         }
 941       if (tc->fixture_teardown)
 942         tc->fixture_teardown (fixture);
 943       g_free (fixture);
 944       g_timer_stop (test_run_timer);
 945       largs[0] = 0; // OK
 946       largs[1] = test_run_forks;
 947       largs[2] = g_timer_elapsed (test_run_timer, NULL);
 948       g_test_log (G_TEST_LOG_STOP_CASE, NULL, NULL, G_N_ELEMENTS (largs), largs);
 949       g_timer_destroy (test_run_timer);
 950     }
 951   g_free (test_run_name);
 952   test_run_name = old_name;
 953   g_free (test_uri_base);
 954   test_uri_base = old_base;
 955   return 0;
 956 }
 957
 958 static int
 959 g_test_run_suite_internal (GTestSuite *suite,
 960                            const char *path)
 961 {
 962   guint n_bad = 0, n_good = 0, bad_suite = 0, l;
 963   gchar *rest, *old_name = test_run_name;
 964   GSList *slist, *reversed;
 965   g_return_val_if_fail (suite != NULL, -1);
 966   while (path[0] == '/')
 967     path++;
 968   l = strlen (path);
 969   rest = strchr (path, '/');
 970   l = rest ? MIN (l, rest - path) : l;
 971   test_run_name = suite->name[0] == 0 ? g_strdup (test_run_name) : g_strconcat (old_name, "/", suite->name, NULL);
 972   reversed = g_slist_reverse (g_slist_copy (suite->cases));
 973   for (slist = reversed; slist; slist = slist->next)
 974     {
 975       GTestCase *tc = slist->data;
 976       guint n = l ? strlen (tc->name) : 0;
 977       if (l == n && strncmp (path, tc->name, n) == 0)
 978         {
 979           n_good++;
 980           n_bad += test_case_run (tc) != 0;
 981         }
 982     }
 983   g_slist_free (reversed);
 984   reversed = g_slist_reverse (g_slist_copy (suite->suites));
 985   for (slist = reversed; slist; slist = slist->next)
 986     {
 987       GTestSuite *ts = slist->data;
 988       guint n = l ? strlen (ts->name) : 0;
 989       if (l == n && strncmp (path, ts->name, n) == 0)
 990         bad_suite += g_test_run_suite_internal (ts, rest ? rest : "") != 0;
 991     }
 992   g_slist_free (reversed);
 993   g_free (test_run_name);
 994   test_run_name = old_name;
 995   return n_bad || bad_suite;
 996 }
 997
 998 /**
 999  * g_test_run_suite:
1000  * @suite: a #GTestSuite
1001  *
1002  * Execute the tests within @suite and all nested #GTestSuites.
1003  * The test suites to be executed are filtered according to
1004  * test path arguments (-p <testpath>) as parsed by g_test_init().
1005  * g_test_run_suite() or g_test_run() may only be called once
1006  * in a program.
1007  */
1008 int
1009 g_test_run_suite (GTestSuite *suite)
1010 {
1011   guint n_bad = 0;
1012   g_return_val_if_fail (g_test_config_vars != NULL, -1);
1013   g_return_val_if_fail (g_test_run_once == TRUE, -1);
1014   g_test_run_once = FALSE;
1015   if (!test_paths)
1016     test_paths = g_slist_prepend (test_paths, "");
1017   while (test_paths)
1018     {
1019       const char *rest, *path = test_paths->data;
1020       guint l, n = strlen (suite->name);
1021       test_paths = g_slist_delete_link (test_paths, test_paths);
1022       while (path[0] == '/')
1023         path++;
1024       if (!n) /* root suite, run unconditionally */
1025         {
1026           n_bad += 0 != g_test_run_suite_internal (suite, path);
1027           continue;
1028         }
1029       /* regular suite, match path */
1030       rest = strchr (path, '/');
1031       l = strlen (path);
1032       l = rest ? MIN (l, rest - path) : l;
1033       if ((!l || l == n) && strncmp (path, suite->name, n) == 0)
1034         n_bad += 0 != g_test_run_suite_internal (suite, rest ? rest : "");
1035     }
1036   return n_bad;
1037 }
1038
1039 void
1040 g_assertion_message (const char     *domain,
1041                      const char     *file,
1042                      int             line,
1043                      const char     *func,
1044                      const char     *message)
1045 {
1046   char lstr[32];
1047   g_snprintf (lstr, 32, "%d", line);
1048   char *s = g_strconcat (domain ? domain : "", domain && domain[0] ? ":" : "",
1049                          file, ":", lstr, ":",
1050                          func, func[0] ? ":" : "",
1051                          " ", message, NULL);
1052   g_printerr ("**\n** %s\n", s);
1053   g_free (s);
1054   abort();
1055 }
1056
1057 void
1058 g_assertion_message_expr (const char     *domain,
1059                           const char     *file,
1060                           int             line,
1061                           const char     *func,
1062                           const char     *expr)
1063 {
1064   char *s = g_strconcat ("assertion failed: (", expr, ")", NULL);
1065   g_assertion_message (domain, file, line, func, s);
1066   g_free (s);
1067 }
1068
1069 void
1070 g_assertion_message_cmpnum (const char     *domain,
1071                             const char     *file,
1072                             int             line,
1073                             const char     *func,
1074                             const char     *expr,
1075                             long double     arg1,
1076                             const char     *cmp,
1077                             long double     arg2,
1078                             char            numtype)
1079 {
1080   char *s = NULL;
1081   switch (numtype)
1082     {
1083     case 'i':   s = g_strdup_printf ("assertion failed (%s): (%.0Lf %s %.0Lf)", expr, arg1, cmp, arg2); break;
1084     case 'x':   s = g_strdup_printf ("assertion failed (%s): (0x%08Lx %s 0x%08Lx)", expr, (guint64) arg1, cmp, (guint64) arg2); break;
1085     case 'f':   s = g_strdup_printf ("assertion failed (%s): (%.9Lg %s %.9Lg)", expr, arg1, cmp, arg2); break;
1086       /* ideally use: floats=%.7g double=%.17g */
1087     }
1088   g_assertion_message (domain, file, line, func, s);
1089   g_free (s);
1090 }
1091
1092 void
1093 g_assertion_message_cmpstr (const char     *domain,
1094                             const char     *file,
1095                             int             line,
1096                             const char     *func,
1097                             const char     *expr,
1098                             const char     *arg1,
1099                             const char     *cmp,
1100                             const char     *arg2)
1101 {
1102   char *a1, *a2, *s, *t1 = NULL, *t2 = NULL;
1103   a1 = arg1 ? g_strconcat ("\"", t1 = g_strescape (arg1, NULL), "\"", NULL) : g_strdup ("NULL");
1104   a2 = arg2 ? g_strconcat ("\"", t2 = g_strescape (arg2, NULL), "\"", NULL) : g_strdup ("NULL");
1105   g_free (t1);
1106   g_free (t2);
1107   s = g_strdup_printf ("assertion failed (%s): (%s %s %s)", expr, a1, cmp, a2);
1108   g_free (a1);
1109   g_free (a2);
1110   g_assertion_message (domain, file, line, func, s);
1111   g_free (s);
1112 }
1113
1114 /**
1115  * g_strcmp0:
1116  * @str1: a C string or %NULL
1117  * @str2: another C string or %NULL
1118  *
1119  * Compares @str1 and @str2 like strcmp(). Handles %NULL strings gracefully.
1120  */
1121 int
1122 g_strcmp0 (const char     *str1,
1123            const char     *str2)
1124 {
1125   if (!str1)
1126     return -(str1 != str2);
1127   if (!str2)
1128     return str1 != str2;
1129   return strcmp (str1, str2);
1130 }
1131
1132 static int /* 0 on success */
1133 kill_child (int  pid,
1134             int *status,
1135             int  patience)
1136 {
1137   int wr;
1138   if (patience >= 3)    /* try graceful reap */
1139     {
1140       if (waitpid (pid, status, WNOHANG) > 0)
1141         return 0;
1142     }
1143   if (patience >= 2)    /* try SIGHUP */
1144     {
1145       kill (pid, SIGHUP);
1146       if (waitpid (pid, status, WNOHANG) > 0)
1147         return 0;
1148       g_usleep (20 * 1000); /* give it some scheduling/shutdown time */
1149       if (waitpid (pid, status, WNOHANG) > 0)
1150         return 0;
1151       g_usleep (50 * 1000); /* give it some scheduling/shutdown time */
1152       if (waitpid (pid, status, WNOHANG) > 0)
1153         return 0;
1154       g_usleep (100 * 1000); /* give it some scheduling/shutdown time */
1155       if (waitpid (pid, status, WNOHANG) > 0)
1156         return 0;
1157     }
1158   if (patience >= 1)    /* try SIGTERM */
1159     {
1160       kill (pid, SIGTERM);
1161       if (waitpid (pid, status, WNOHANG) > 0)
1162         return 0;
1163       g_usleep (200 * 1000); /* give it some scheduling/shutdown time */
1164       if (waitpid (pid, status, WNOHANG) > 0)
1165         return 0;
1166       g_usleep (400 * 1000); /* give it some scheduling/shutdown time */
1167       if (waitpid (pid, status, WNOHANG) > 0)
1168         return 0;
1169     }
1170   /* finish it off */
1171   kill (pid, SIGKILL);
1172   do
1173     wr = waitpid (pid, status, 0);
1174   while (wr < 0 && errno == EINTR);
1175   return wr;
1176 }
1177
1178 static inline int
1179 g_string_must_read (GString *gstring,
1180                     int      fd)
1181 {
1182 #define STRING_BUFFER_SIZE     4096
1183   char buf[STRING_BUFFER_SIZE];
1184   gssize bytes;
1185  again:
1186   bytes = read (fd, buf, sizeof (buf));
1187   if (bytes == 0)
1188     return 0; /* EOF, calling this function assumes data is available */
1189   else if (bytes > 0)
1190     {
1191       g_string_append_len (gstring, buf, bytes);
1192       return 1;
1193     }
1194   else if (bytes < 0 && errno == EINTR)
1195     goto again;
1196   else /* bytes < 0 */
1197     {
1198       g_warning ("failed to read() from child process (%d): %s", test_trap_last_pid, g_strerror (errno));
1199       return 1; /* ignore error after warning */
1200     }
1201 }
1202
1203 static inline void
1204 g_string_write_out (GString *gstring,
1205                     int      outfd,
1206                     int     *stringpos)
1207 {
1208   if (*stringpos < gstring->len)
1209     {
1210       int r;
1211       do
1212         r = write (outfd, gstring->str + *stringpos, gstring->len - *stringpos);
1213       while (r < 0 && errno == EINTR);
1214       *stringpos += MAX (r, 0);
1215     }
1216 }
1217
1218 static int
1219 sane_dup2 (int fd1,
1220            int fd2)
1221 {
1222   int ret;
1223   do
1224     ret = dup2 (fd1, fd2);
1225   while (ret < 0 && errno == EINTR);
1226   return ret;
1227 }
1228
1229 static void
1230 test_trap_clear (void)
1231 {
1232   test_trap_last_status = 0;
1233   test_trap_last_pid = 0;
1234   g_free (test_trap_last_stdout);
1235   test_trap_last_stdout = NULL;
1236   g_free (test_trap_last_stderr);
1237   test_trap_last_stderr = NULL;
1238 }
1239
1240 static guint64
1241 test_time_stamp (void)
1242 {
1243   GTimeVal tv;
1244   guint64 stamp;
1245   g_get_current_time (&tv);
1246   stamp = tv.tv_sec;
1247   stamp = stamp * 1000000 + tv.tv_usec;
1248   return stamp;
1249 }
1250
1251 /**
1252  * g_test_trap_fork:
1253  * @usec_timeout:    Timeout for the forked test in micro seconds.
1254  * @test_trap_flags: Flags to modify forking behaviour.
1255  *
1256  * Fork the current test program to execute a test case that might
1257  * not return or that might abort. The forked test case is aborted
1258  * and considered failing if its run time exceeds @usec_timeout.
1259  * The forking behavior can be configured with the following flags:
1260  * %G_TEST_TRAP_SILENCE_STDOUT - redirect stdout of the test child
1261  * to /dev/null so it cannot be observed on the console during test
1262  * runs. The actual output is still captured though to allow later
1263  * tests with g_test_trap_assert_stdout().
1264  * %G_TEST_TRAP_SILENCE_STDERR - redirect stderr of the test child
1265  * to /dev/null so it cannot be observed on the console during test
1266  * runs. The actual output is still captured though to allow later
1267  * tests with g_test_trap_assert_stderr().
1268  * %G_TEST_TRAP_INHERIT_STDIN - if this flag is given, stdin of the
1269  * forked child process is shared with stdin of its parent process.
1270  * It is redirected to /dev/null otherwise.
1271  *
1272  * In the following example, the test code forks, the forked child
1273  * process produces some sample output and exits successfully.
1274  * The forking parent process then asserts successfull child program
1275  * termination and validates cihld program outputs.
1276  *
1277  * <informalexample><programlisting>
1278  *   static void
1279  *   test_fork_patterns (void)
1280  *   {
1281  *     if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
1282  *       {
1283  *         g_print ("some stdout text: somagic17\n");
1284  *         g_printerr ("some stderr text: semagic43\n");
1285  *         exit (0); // successful test run
1286  *       }
1287  *     g_test_trap_assert_passed();
1288  *     g_test_trap_assert_stdout ("*somagic17*");
1289  *     g_test_trap_assert_stderr ("*semagic43*");
1290  *   }
1291  * </programlisting></informalexample>
1292  *
1293  * Returns: %TRUE for the forked child and %FALSE for the executing parent process.
1294  */
1295 gboolean
1296 g_test_trap_fork (guint64        usec_timeout,
1297                   GTestTrapFlags test_trap_flags)
1298 {
1299   int stdout_pipe[2] = { -1, -1 };
1300   int stderr_pipe[2] = { -1, -1 };
1301   int stdtst_pipe[2] = { -1, -1 };
1302   test_trap_clear();
1303   if (pipe (stdout_pipe) < 0 || pipe (stderr_pipe) < 0 || pipe (stdtst_pipe) < 0)
1304     g_error ("failed to create pipes to fork test program: %s", g_strerror (errno));
1305   signal (SIGCHLD, SIG_DFL);
1306   test_trap_last_pid = fork ();
1307   if (test_trap_last_pid < 0)
1308     g_error ("failed to fork test program: %s", g_strerror (errno));
1309   if (test_trap_last_pid == 0)  /* child */
1310     {
1311       int fd0 = -1;
1312       close (stdout_pipe[0]);
1313       close (stderr_pipe[0]);
1314       close (stdtst_pipe[0]);
1315       if (!(test_trap_flags & G_TEST_TRAP_INHERIT_STDIN))
1316         fd0 = open ("/dev/null", O_RDONLY);
1317       if (sane_dup2 (stdout_pipe[1], 1) < 0 || sane_dup2 (stderr_pipe[1], 2) < 0 || (fd0 >= 0 && sane_dup2 (fd0, 0) < 0))
1318         g_error ("failed to dup2() in forked test program: %s", g_strerror (errno));
1319       if (fd0 >= 3)
1320         close (fd0);
1321       if (stdout_pipe[1] >= 3)
1322         close (stdout_pipe[1]);
1323       if (stderr_pipe[1] >= 3)
1324         close (stderr_pipe[1]);
1325       test_log_fd = stdtst_pipe[1];
1326       return TRUE;
1327     }
1328   else                          /* parent */
1329     {
1330       GString *sout = g_string_new (NULL);
1331       GString *serr = g_string_new (NULL);
1332       guint64 sstamp;
1333       int soutpos = 0, serrpos = 0, wr, need_wait = TRUE;
1334       test_run_forks++;
1335       close (stdout_pipe[1]);
1336       close (stderr_pipe[1]);
1337       close (stdtst_pipe[1]);
1338       sstamp = test_time_stamp();
1339       /* read data until we get EOF on all pipes */
1340       while (stdout_pipe[0] >= 0 || stderr_pipe[0] >= 0 || stdtst_pipe[0] > 0)
1341         {
1342           fd_set fds;
1343           struct timeval tv;
1344           FD_ZERO (&fds);
1345           if (stdout_pipe[0] >= 0)
1346             FD_SET (stdout_pipe[0], &fds);
1347           if (stderr_pipe[0] >= 0)
1348             FD_SET (stderr_pipe[0], &fds);
1349           if (stdtst_pipe[0] >= 0)
1350             FD_SET (stdtst_pipe[0], &fds);
1351           tv.tv_sec = 0;
1352           tv.tv_usec = MIN (usec_timeout ? usec_timeout : 1000000, 100 * 1000); // sleep at most 0.5 seconds to catch clock skews, etc.
1353           int ret = select (MAX (MAX (stdout_pipe[0], stderr_pipe[0]), stdtst_pipe[0]) + 1, &fds, NULL, NULL, &tv);
1354           if (ret < 0 && errno != EINTR)
1355             {
1356               g_warning ("Unexpected error in select() while reading from child process (%d): %s", test_trap_last_pid, g_strerror (errno));
1357               break;
1358             }
1359           if (stdout_pipe[0] >= 0 && FD_ISSET (stdout_pipe[0], &fds) &&
1360               g_string_must_read (sout, stdout_pipe[0]) == 0)
1361             {
1362               close (stdout_pipe[0]);
1363               stdout_pipe[0] = -1;
1364             }
1365           if (stderr_pipe[0] >= 0 && FD_ISSET (stderr_pipe[0], &fds) &&
1366               g_string_must_read (serr, stderr_pipe[0]) == 0)
1367             {
1368               close (stderr_pipe[0]);
1369               stderr_pipe[0] = -1;
1370             }
1371           if (stdtst_pipe[0] >= 0 && FD_ISSET (stdtst_pipe[0], &fds))
1372             {
1373               guint8 buffer[4096];
1374               gint l, r = read (stdtst_pipe[0], buffer, sizeof (buffer));
1375               if (r > 0 && test_log_fd > 0)
1376                 do
1377                   l = write (test_log_fd, buffer, r);
1378                 while (l < 0 && errno == EINTR);
1379               if (r == 0 || (r < 0 && errno != EINTR && errno != EAGAIN))
1380                 {
1381                   close (stdtst_pipe[0]);
1382                   stdtst_pipe[0] = -1;
1383                 }
1384             }
1385           if (!(test_trap_flags & G_TEST_TRAP_SILENCE_STDOUT))
1386             g_string_write_out (sout, 1, &soutpos);
1387           if (!(test_trap_flags & G_TEST_TRAP_SILENCE_STDERR))
1388             g_string_write_out (serr, 2, &serrpos);
1389           if (usec_timeout)
1390             {
1391               guint64 nstamp = test_time_stamp();
1392               int status = 0;
1393               sstamp = MIN (sstamp, nstamp); // guard against backwards clock skews
1394               if (usec_timeout < nstamp - sstamp)
1395                 {
1396                   /* timeout reached, need to abort the child now */
1397                   kill_child (test_trap_last_pid, &status, 3);
1398                   test_trap_last_status = 1024; /* timeout */
1399                   if (0 && WIFSIGNALED (status))
1400                     g_printerr ("%s: child timed out and received: %s\n", G_STRFUNC, g_strsignal (WTERMSIG (status)));
1401                   need_wait = FALSE;
1402                   break;
1403                 }
1404             }
1405         }
1406       close (stdout_pipe[0]);
1407       close (stderr_pipe[0]);
1408       close (stdtst_pipe[0]);
1409       if (need_wait)
1410         {
1411           int status = 0;
1412           do
1413             wr = waitpid (test_trap_last_pid, &status, 0);
1414           while (wr < 0 && errno == EINTR);
1415           if (WIFEXITED (status)) /* normal exit */
1416             test_trap_last_status = WEXITSTATUS (status); /* 0..255 */
1417           else if (WIFSIGNALED (status))
1418             test_trap_last_status = (WTERMSIG (status) << 12); /* signalled */
1419           else /* WCOREDUMP (status) */
1420             test_trap_last_status = 512; /* coredump */
1421         }
1422       test_trap_last_stdout = g_string_free (sout, FALSE);
1423       test_trap_last_stderr = g_string_free (serr, FALSE);
1424       return FALSE;
1425     }
1426 }
1427
1428 /**
1429  * g_test_trap_has_passed:
1430  *
1431  * Check the reuslt of the last g_test_trap_fork() call.
1432  *
1433  * Returns: %TRUE if the last forked child terminated successfully.
1434  */
1435 gboolean
1436 g_test_trap_has_passed (void)
1437 {
1438   return test_trap_last_status == 0; /* exit_status == 0 && !signal && !coredump */
1439 }
1440
1441 /**
1442  * g_test_trap_reached_timeout:
1443  *
1444  * Check the reuslt of the last g_test_trap_fork() call.
1445  *
1446  * Returns: %TRUE if the last forked child got killed due to a fork timeout.
1447  */
1448 gboolean
1449 g_test_trap_reached_timeout (void)
1450 {
1451   return 0 != (test_trap_last_status & 1024); /* timeout flag */
1452 }
1453
1454 void
1455 g_test_trap_assertions (const char     *domain,
1456                         const char     *file,
1457                         int             line,
1458                         const char     *func,
1459                         gboolean        must_pass,
1460                         gboolean        must_fail,
1461                         const char     *stdout_pattern,
1462                         const char     *stderr_pattern)
1463 {
1464   if (test_trap_last_pid == 0)
1465     g_error ("child process failed to exit after g_test_trap_fork() and before g_test_trap_assert*()");
1466   if (must_pass && !g_test_trap_has_passed())
1467     {
1468       char *msg = g_strdup_printf ("child process (%d) of test trap failed unexpectedly", test_trap_last_pid);
1469       g_assertion_message (domain, file, line, func, msg);
1470       g_free (msg);
1471     }
1472   if (must_fail && g_test_trap_has_passed())
1473     {
1474       char *msg = g_strdup_printf ("child process (%d) did not fail as expected", test_trap_last_pid);
1475       g_assertion_message (domain, file, line, func, msg);
1476       g_free (msg);
1477     }
1478   if (stdout_pattern && !g_pattern_match_simple (stdout_pattern, test_trap_last_stdout))
1479     {
1480       char *msg = g_strdup_printf ("stdout of child process (%d) failed to match: %s", test_trap_last_pid, stdout_pattern);
1481       g_assertion_message (domain, file, line, func, msg);
1482       g_free (msg);
1483     }
1484   if (stderr_pattern && !g_pattern_match_simple (stderr_pattern, test_trap_last_stderr))
1485     {
1486       char *msg = g_strdup_printf ("stderr of child process (%d) failed to match: %s", test_trap_last_pid, stderr_pattern);
1487       g_assertion_message (domain, file, line, func, msg);
1488       g_free (msg);
1489     }
1490 }
1491
1492 static void
1493 gstring_overwrite_int (GString *gstring,
1494                        guint    pos,
1495                        guint32  vuint)
1496 {
1497   vuint = g_htonl (vuint);
1498   g_string_overwrite_len (gstring, pos, (const gchar*) &vuint, 4);
1499 }
1500
1501 static void
1502 gstring_append_int (GString *gstring,
1503                     guint32  vuint)
1504 {
1505   vuint = g_htonl (vuint);
1506   g_string_append_len (gstring, (const gchar*) &vuint, 4);
1507 }
1508
1509 static void
1510 gstring_append_double (GString *gstring,
1511                        double   vdouble)
1512 {
1513   union { double vdouble; guint64 vuint64; } u;
1514   u.vdouble = vdouble;
1515   u.vuint64 = GUINT64_TO_BE (u.vuint64);
1516   g_string_append_len (gstring, (const gchar*) &u.vuint64, 8);
1517 }
1518
1519 static guint8*
1520 g_test_log_dump (GTestLogMsg *msg,
1521                  guint       *len)
1522 {
1523   GString *gstring = g_string_sized_new (1024);
1524   guint ui;
1525   gstring_append_int (gstring, 0);              /* message length */
1526   gstring_append_int (gstring, msg->log_type);
1527   gstring_append_int (gstring, msg->n_strings);
1528   gstring_append_int (gstring, msg->n_nums);
1529   gstring_append_int (gstring, 0);      /* reserved */
1530   for (ui = 0; ui < msg->n_strings; ui++)
1531     {
1532       guint l = strlen (msg->strings[ui]);
1533       gstring_append_int (gstring, l);
1534       g_string_append_len (gstring, msg->strings[ui], l);
1535     }
1536   for (ui = 0; ui < msg->n_nums; ui++)
1537     gstring_append_double (gstring, msg->nums[ui]);
1538   *len = gstring->len;
1539   gstring_overwrite_int (gstring, 0, *len);     /* message length */
1540   return (guint8*) g_string_free (gstring, FALSE);
1541 }
1542
1543 static inline long double
1544 net_double (const gchar **ipointer)
1545 {
1546   union { guint64 vuint64; double vdouble; } u;
1547   guint64 aligned_int64;
1548   memcpy (&aligned_int64, *ipointer, 8);
1549   *ipointer += 8;
1550   u.vuint64 = GUINT64_FROM_BE (aligned_int64);
1551   return u.vdouble;
1552 }
1553
1554 static inline guint32
1555 net_int (const gchar **ipointer)
1556 {
1557   guint32 aligned_int;
1558   memcpy (&aligned_int, *ipointer, 4);
1559   *ipointer += 4;
1560   return g_ntohl (aligned_int);
1561 }
1562
1563 static gboolean
1564 g_test_log_extract (GTestLogBuffer *tbuffer)
1565 {
1566   const gchar *p = tbuffer->data->str;
1567   GTestLogMsg msg;
1568   guint mlength;
1569   if (tbuffer->data->len < 4 * 5)
1570     return FALSE;
1571   mlength = net_int (&p);
1572   if (tbuffer->data->len < mlength)
1573     return FALSE;
1574   msg.log_type = net_int (&p);
1575   msg.n_strings = net_int (&p);
1576   msg.n_nums = net_int (&p);
1577   if (net_int (&p) == 0)
1578     {
1579       guint ui;
1580       msg.strings = g_new0 (gchar*, msg.n_strings + 1);
1581       msg.nums = g_new0 (long double, msg.n_nums);
1582       for (ui = 0; ui < msg.n_strings; ui++)
1583         {
1584           guint sl = net_int (&p);
1585           msg.strings[ui] = g_strndup (p, sl);
1586           p += sl;
1587         }
1588       for (ui = 0; ui < msg.n_nums; ui++)
1589         msg.nums[ui] = net_double (&p);
1590       if (p <= tbuffer->data->str + mlength)
1591         {
1592           g_string_erase (tbuffer->data, 0, mlength);
1593           tbuffer->msgs = g_slist_prepend (tbuffer->msgs, g_memdup (&msg, sizeof (msg)));
1594           return TRUE;
1595         }
1596     }
1597   g_free (msg.nums);
1598   g_strfreev (msg.strings);
1599   g_error ("corrupt log stream from test program");
1600   return FALSE;
1601 }
1602
1603 /**
1604  * g_test_log_buffer_new:
1605  *
1606  * Internal function for gtester to decode test log messages, no ABI guarantees provided.
1607  */
1608 GTestLogBuffer*
1609 g_test_log_buffer_new (void)
1610 {
1611   GTestLogBuffer *tb = g_new0 (GTestLogBuffer, 1);
1612   tb->data = g_string_sized_new (1024);
1613   return tb;
1614 }
1615
1616 /**
1617  * g_test_log_buffer_free
1618  *
1619  * Internal function for gtester to free test log messages, no ABI guarantees provided.
1620  */
1621 void
1622 g_test_log_buffer_free (GTestLogBuffer *tbuffer)
1623 {
1624   g_return_if_fail (tbuffer != NULL);
1625   while (tbuffer->msgs)
1626     g_test_log_msg_free (g_test_log_buffer_pop (tbuffer));
1627   g_string_free (tbuffer->data, TRUE);
1628   g_free (tbuffer);
1629 }
1630
1631 /**
1632  * g_test_log_buffer_push
1633  *
1634  * Internal function for gtester to decode test log messages, no ABI guarantees provided.
1635  */
1636 void
1637 g_test_log_buffer_push (GTestLogBuffer *tbuffer,
1638                         guint           n_bytes,
1639                         const guint8   *bytes)
1640 {
1641   g_return_if_fail (tbuffer != NULL);
1642   if (n_bytes)
1643     {
1644       gboolean more_messages;
1645       g_return_if_fail (bytes != NULL);
1646       g_string_append_len (tbuffer->data, (const gchar*) bytes, n_bytes);
1647       do
1648         more_messages = g_test_log_extract (tbuffer);
1649       while (more_messages);
1650     }
1651 }
1652
1653 /**
1654  * g_test_log_buffer_pop:
1655  *
1656  * Internal function for gtester to retrieve test log messages, no ABI guarantees provided.
1657  */
1658 GTestLogMsg*
1659 g_test_log_buffer_pop (GTestLogBuffer *tbuffer)
1660 {
1661   GTestLogMsg *msg = NULL;
1662   g_return_val_if_fail (tbuffer != NULL, NULL);
1663   if (tbuffer->msgs)
1664     {
1665       GSList *slist = g_slist_last (tbuffer->msgs);
1666       msg = slist->data;
1667       tbuffer->msgs = g_slist_delete_link (tbuffer->msgs, slist);
1668     }
1669   return msg;
1670 }
1671
1672 /**
1673  * g_test_log_msg_free:
1674  *
1675  * Internal function for gtester to free test log messages, no ABI guarantees provided.
1676  */
1677 void
1678 g_test_log_msg_free (GTestLogMsg *tmsg)
1679 {
1680   g_return_if_fail (tmsg != NULL);
1681   g_strfreev (tmsg->strings);
1682   g_free (tmsg->nums);
1683   g_free (tmsg);
1684 }
1685
1686 /* --- macros docs START --- */
1687 /**
1688  * g_test_add:
1689  * @testpath:  The test path for a new test case.
1690  * @Fixture:   The type of a fixture data structure.
1691  * @fsetup:    The function to set up the fixture data.
1692  * @ftest:     The actual test function.
1693  * @fteardown: The function to tear down the fixture data.
1694  *
1695  * Hook up a new test case at @testpath, similar to g_test_add_func().
1696  * A fixture data structure with setup and teardown function may be provided
1697  * though, simmilar to g_test_create_case().
1698  * g_test_add() is implemented as a macro, so that the fsetup(), ftest() and
1699  * fteardown() callbacks can expect a @Fixture pointer as first argument in
1700  * a type safe manner.
1701  **/
1702 /* --- macros docs END --- */
1703
1704 #define __G_TEST_UTILS_C__
1705 #include "galiasdef.c"