glib/gtestutils.h

   1 /* GLib testing utilities
   2  * Copyright (C) 2007 Imendio AB
   3  * Authors: Tim Janik
   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.1 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, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef __G_TEST_UTILS_H__
  20 #define __G_TEST_UTILS_H__
  21
  22 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  23 #error "Only <glib.h> can be included directly."
  24 #endif
  25
  26 #include <glib/gmessages.h>
  27 #include <glib/gstring.h>
  28 #include <glib/gerror.h>
  29 #include <glib/gslist.h>
  30 #include <errno.h>
  31 #include <string.h>
  32
  33 G_BEGIN_DECLS
  34
  35 typedef struct GTestCase  GTestCase;
  36 typedef struct GTestSuite GTestSuite;
  37 typedef void (*GTestFunc)        (void);
  38 typedef void (*GTestDataFunc)    (gconstpointer user_data);
  39 typedef void (*GTestFixtureFunc) (gpointer      fixture,
  40                                   gconstpointer user_data);
  41
  42 /* assertion API */
  43 #define g_assert_cmpstr(s1, cmp, s2)    G_STMT_START { \
  44                                              const char *__s1 = (s1), *__s2 = (s2); \
  45                                              if (g_strcmp0 (__s1, __s2) cmp 0) ; else \
  46                                                g_assertion_message_cmpstr (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  47                                                  #s1 " " #cmp " " #s2, __s1, #cmp, __s2); \
  48                                         } G_STMT_END
  49 #define g_assert_cmpint(n1, cmp, n2)    G_STMT_START { \
  50                                              gint64 __n1 = (n1), __n2 = (n2); \
  51                                              if (__n1 cmp __n2) ; else \
  52                                                g_assertion_message_cmpnum (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  53                                                  #n1 " " #cmp " " #n2, (long double) __n1, #cmp, (long double) __n2, 'i'); \
  54                                         } G_STMT_END
  55 #define g_assert_cmpuint(n1, cmp, n2)   G_STMT_START { \
  56                                              guint64 __n1 = (n1), __n2 = (n2); \
  57                                              if (__n1 cmp __n2) ; else \
  58                                                g_assertion_message_cmpnum (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  59                                                  #n1 " " #cmp " " #n2, (long double) __n1, #cmp, (long double) __n2, 'i'); \
  60                                         } G_STMT_END
  61 #define g_assert_cmphex(n1, cmp, n2)    G_STMT_START {\
  62                                              guint64 __n1 = (n1), __n2 = (n2); \
  63                                              if (__n1 cmp __n2) ; else \
  64                                                g_assertion_message_cmpnum (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  65                                                  #n1 " " #cmp " " #n2, (long double) __n1, #cmp, (long double) __n2, 'x'); \
  66                                         } G_STMT_END
  67 #define g_assert_cmpfloat(n1,cmp,n2)    G_STMT_START { \
  68                                              long double __n1 = (long double) (n1), __n2 = (long double) (n2); \
  69                                              if (__n1 cmp __n2) ; else \
  70                                                g_assertion_message_cmpnum (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  71                                                  #n1 " " #cmp " " #n2, (long double) __n1, #cmp, (long double) __n2, 'f'); \
  72                                         } G_STMT_END
  73 #define g_assert_cmpfloat_with_epsilon(n1,n2,epsilon) \
  74                                         G_STMT_START { \
  75                                              double __n1 = (n1), __n2 = (n2), __epsilon = (epsilon); \
  76                                              if (G_APPROX_VALUE (__n1,  __n2, __epsilon)) ; else \
  77                                                g_assertion_message_cmpnum (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  78                                                  #n1 " == " #n2 " (+/- " #epsilon ")", __n1, "==", __n2, 'f'); \
  79                                         } G_STMT_END
  80 #define g_assert_cmpmem(m1, l1, m2, l2) G_STMT_START {\
  81                                              gconstpointer __m1 = m1, __m2 = m2; \
  82                                              int __l1 = l1, __l2 = l2; \
  83                                              if (__l1 != 0 && __m1 == NULL) \
  84                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  85                                                                     "assertion failed (" #l1 " == 0 || " #m1 " != NULL)"); \
  86                                              else if (__l2 != 0 && __m2 == NULL) \
  87                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  88                                                                     "assertion failed (" #l2 " == 0 || " #m2 " != NULL)"); \
  89                                              else if (__l1 != __l2) \
  90                                                g_assertion_message_cmpnum (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  91                                                                            #l1 " (len(" #m1 ")) == " #l2 " (len(" #m2 "))", \
  92                                                                            (long double) __l1, "==", (long double) __l2, 'i'); \
  93                                              else if (__l1 != 0 && __m2 != NULL && memcmp (__m1, __m2, __l1) != 0) \
  94                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
  95                                                                     "assertion failed (" #m1 " == " #m2 ")"); \
  96                                         } G_STMT_END
  97 #define g_assert_cmpvariant(v1, v2) \
  98   G_STMT_START \
  99   { \
 100     GVariant *__v1 = (v1), *__v2 = (v2); \
 101     if (!g_variant_equal (__v1, __v2)) \
 102       { \
 103         gchar *__s1, *__s2, *__msg; \
 104         __s1 = g_variant_print (__v1, TRUE); \
 105         __s2 = g_variant_print (__v2, TRUE); \
 106         __msg = g_strdup_printf ("assertion failed (" #v1 " == " #v2 "): %s does not equal %s", __s1, __s2); \
 107         g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, __msg); \
 108         g_free (__s1); \
 109         g_free (__s2); \
 110         g_free (__msg); \
 111       } \
 112   } \
 113   G_STMT_END
 114 #define g_assert_cmpstrv(strv1, strv2) \
 115   G_STMT_START \
 116   { \
 117     const char * const *__strv1 = (const char * const *) (strv1); \
 118     const char * const *__strv2 = (const char * const *) (strv2); \
 119     if (!__strv1 || !__strv2) \
 120       { \
 121         if (__strv1) \
 122           { \
 123             g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 124                                  "assertion failed (" #strv1 " == " #strv2 "): " #strv2 " is NULL, but " #strv1 " is not"); \
 125           } \
 126         else if (__strv2) \
 127           { \
 128             g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 129                                  "assertion failed (" #strv1 " == " #strv2 "): " #strv1 " is NULL, but " #strv2 " is not"); \
 130           } \
 131       } \
 132     else \
 133       { \
 134         guint __l1 = g_strv_length ((char **) __strv1); \
 135         guint __l2 = g_strv_length ((char **) __strv2); \
 136         if (__l1 != __l2) \
 137           { \
 138             char *__msg; \
 139             __msg = g_strdup_printf ("assertion failed (" #strv1 " == " #strv2 "): length %u does not equal length %u", __l1, __l2); \
 140             g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, __msg); \
 141             g_free (__msg); \
 142           } \
 143         else \
 144           { \
 145             guint __i; \
 146             for (__i = 0; __i < __l1; __i++) \
 147               { \
 148                 if (g_strcmp0 (__strv1[__i], __strv2[__i]) != 0) \
 149                   { \
 150                     g_assertion_message_cmpstrv (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 151                                                  #strv1 " == " #strv2, \
 152                                                  __strv1, __strv2, __i); \
 153                   } \
 154               } \
 155           } \
 156       } \
 157   } \
 158   G_STMT_END
 159 #define g_assert_no_errno(expr)         G_STMT_START { \
 160                                              int __ret, __errsv; \
 161                                              errno = 0; \
 162                                              __ret = expr; \
 163                                              __errsv = errno; \
 164                                              if (__ret < 0) \
 165                                                { \
 166                                                  gchar *__msg; \
 167                                                  __msg = g_strdup_printf ("assertion failed (" #expr " >= 0): errno %i: %s", __errsv, g_strerror (__errsv)); \
 168                                                  g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, __msg); \
 169                                                  g_free (__msg); \
 170                                                } \
 171                                         } G_STMT_END \
 172                                         GLIB_AVAILABLE_MACRO_IN_2_66
 173 #define g_assert_no_error(err)          G_STMT_START { \
 174                                              if (err) \
 175                                                g_assertion_message_error (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 176                                                  #err, err, 0, 0); \
 177                                         } G_STMT_END
 178 #define g_assert_error(err, dom, c)     G_STMT_START { \
 179                                                if (!err || (err)->domain != dom || (err)->code != c) \
 180                                                g_assertion_message_error (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 181                                                  #err, err, dom, c); \
 182                                         } G_STMT_END
 183 #define g_assert_true(expr)             G_STMT_START { \
 184                                              if G_LIKELY (expr) ; else \
 185                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 186                                                                     "'" #expr "' should be TRUE"); \
 187                                         } G_STMT_END
 188 #define g_assert_false(expr)            G_STMT_START { \
 189                                              if G_LIKELY (!(expr)) ; else \
 190                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 191                                                                     "'" #expr "' should be FALSE"); \
 192                                         } G_STMT_END
 193
 194 /* Use nullptr in C++ to catch misuse of these macros. */
 195 #if defined(__cplusplus) && __cplusplus >= 201100L
 196 #define g_assert_null(expr)             G_STMT_START { if G_LIKELY ((expr) == nullptr) ; else \
 197                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 198                                                                     "'" #expr "' should be nullptr"); \
 199                                         } G_STMT_END
 200 #define g_assert_nonnull(expr)          G_STMT_START { \
 201                                              if G_LIKELY ((expr) != nullptr) ; else \
 202                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 203                                                                     "'" #expr "' should not be nullptr"); \
 204                                         } G_STMT_END
 205 #else /* not C++ */
 206 #define g_assert_null(expr)             G_STMT_START { if G_LIKELY ((expr) == NULL) ; else \
 207                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 208                                                                     "'" #expr "' should be NULL"); \
 209                                         } G_STMT_END
 210 #define g_assert_nonnull(expr)          G_STMT_START { \
 211                                              if G_LIKELY ((expr) != NULL) ; else \
 212                                                g_assertion_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 213                                                                     "'" #expr "' should not be NULL"); \
 214                                         } G_STMT_END
 215 #endif
 216
 217 #ifdef G_DISABLE_ASSERT
 218 /* https://gcc.gnu.org/onlinedocs/gcc-8.3.0/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005funreachable
 219  * GCC 5 is not a strict lower bound for versions of GCC which provide __builtin_unreachable(). */
 220 #if __GNUC__ >= 5 || g_macro__has_builtin(__builtin_unreachable)
 221 #define g_assert_not_reached()          G_STMT_START { (void) 0; __builtin_unreachable (); } G_STMT_END
 222 #elif defined (_MSC_VER)
 223 #define g_assert_not_reached()          G_STMT_START { (void) 0; __assume (0); } G_STMT_END
 224 #else  /* if __builtin_unreachable() is not supported: */
 225 #define g_assert_not_reached()          G_STMT_START { (void) 0; } G_STMT_END
 226 #endif
 227
 228 #define g_assert(expr)                  G_STMT_START { (void) 0; } G_STMT_END
 229 #define g_assert_se(expr)               ((void) (expr))
 230 #else /* !G_DISABLE_ASSERT */
 231 #define g_assert_not_reached()          G_STMT_START { g_assertion_message_expr (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); } G_STMT_END
 232 #define g_assert(expr)                  G_STMT_START { \
 233                                              if G_LIKELY (expr) ; else \
 234                                                g_assertion_message_expr (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, \
 235                                                                          #expr); \
 236                                         } G_STMT_END
 237 #define g_assert_se(expr)               g_assert((expr))
 238 #endif /* !G_DISABLE_ASSERT */
 239
 240 GLIB_AVAILABLE_IN_ALL
 241 int     g_strcmp0                       (const char     *str1,
 242                                          const char     *str2);
 243
 244 /* report performance results */
 245 GLIB_AVAILABLE_IN_ALL
 246 void    g_test_minimized_result         (double          minimized_quantity,
 247                                          const char     *format,
 248                                          ...) G_GNUC_PRINTF (2, 3);
 249 GLIB_AVAILABLE_IN_ALL
 250 void    g_test_maximized_result         (double          maximized_quantity,
 251                                          const char     *format,
 252                                          ...) G_GNUC_PRINTF (2, 3);
 253
 254 /* initialize testing framework */
 255 GLIB_AVAILABLE_IN_ALL
 256 void    g_test_init                     (int            *argc,
 257                                          char         ***argv,
 258                                          ...) G_GNUC_NULL_TERMINATED;
 259
 260 /**
 261  * G_TEST_OPTION_ISOLATE_DIRS:
 262  *
 263  * Creates a unique temporary directory for each unit test and uses
 264  * g_set_user_dirs() to set XDG directories to point into subdirectories of it
 265  * for the duration of the unit test. The directory tree is cleaned up after the
 266  * test finishes successfully. Note that this doesn’t take effect until
 267  * g_test_run() is called, so calls to (for example) g_get_user_home_dir() will
 268  * return the system-wide value when made in a test program’s main() function.
 269  *
 270  * The following functions will return subdirectories of the temporary directory
 271  * when this option is used. The specific subdirectory paths in use are not
 272  * guaranteed to be stable API — always use a getter function to retrieve them.
 273  *
 274  *  - g_get_home_dir()
 275  *  - g_get_user_cache_dir()
 276  *  - g_get_system_config_dirs()
 277  *  - g_get_user_config_dir()
 278  *  - g_get_system_data_dirs()
 279  *  - g_get_user_data_dir()
 280  *  - g_get_user_runtime_dir()
 281  *
 282  * The subdirectories may not be created by the test harness; as with normal
 283  * calls to functions like g_get_user_cache_dir(), the caller must be prepared
 284  * to create the directory if it doesn’t exist.
 285  *
 286  * Since: 2.60
 287  */
 288 #define G_TEST_OPTION_ISOLATE_DIRS "isolate_dirs"
 289
 290 /* While we discourage its use, g_assert() is often used in unit tests
 291  * (especially in legacy code). g_assert_*() should really be used instead.
 292  * g_assert() can be disabled at client program compile time, which can render
 293  * tests useless. Highlight that to the user. */
 294 #ifdef G_DISABLE_ASSERT
 295 #if defined(G_HAVE_ISO_VARARGS)
 296 #define g_test_init(argc, argv, ...) \
 297   G_STMT_START { \
 298     g_printerr ("Tests were compiled with G_DISABLE_ASSERT and are likely no-ops. Aborting.\n"); \
 299     exit (1); \
 300   } G_STMT_END
 301 #elif defined(G_HAVE_GNUC_VARARGS)
 302 #define g_test_init(argc, argv...) \
 303   G_STMT_START { \
 304     g_printerr ("Tests were compiled with G_DISABLE_ASSERT and are likely no-ops. Aborting.\n"); \
 305     exit (1); \
 306   } G_STMT_END
 307 #else  /* no varargs */
 308   /* do nothing */
 309 #endif  /* varargs support */
 310 #endif  /* G_DISABLE_ASSERT */
 311
 312 /* query testing framework config */
 313 #define g_test_initialized()            (g_test_config_vars->test_initialized)
 314 #define g_test_quick()                  (g_test_config_vars->test_quick)
 315 #define g_test_slow()                   (!g_test_config_vars->test_quick)
 316 #define g_test_thorough()               (!g_test_config_vars->test_quick)
 317 #define g_test_perf()                   (g_test_config_vars->test_perf)
 318 #define g_test_verbose()                (g_test_config_vars->test_verbose)
 319 #define g_test_quiet()                  (g_test_config_vars->test_quiet)
 320 #define g_test_undefined()              (g_test_config_vars->test_undefined)
 321 GLIB_AVAILABLE_IN_2_38
 322 gboolean g_test_subprocess (void);
 323
 324 /* run all tests under toplevel suite (path: /) */
 325 GLIB_AVAILABLE_IN_ALL
 326 int     g_test_run                      (void);
 327 /* hook up a test functions under test path */
 328 GLIB_AVAILABLE_IN_ALL
 329 void    g_test_add_func                 (const char     *testpath,
 330                                          GTestFunc       test_func);
 331
 332 GLIB_AVAILABLE_IN_ALL
 333 void    g_test_add_data_func            (const char     *testpath,
 334                                          gconstpointer   test_data,
 335                                          GTestDataFunc   test_func);
 336
 337 GLIB_AVAILABLE_IN_2_34
 338 void    g_test_add_data_func_full       (const char     *testpath,
 339                                          gpointer        test_data,
 340                                          GTestDataFunc   test_func,
 341                                          GDestroyNotify  data_free_func);
 342
 343 /* tell about currently run test */
 344 GLIB_AVAILABLE_IN_2_68
 345 const char * g_test_get_path            (void);
 346
 347 /* tell about failure */
 348 GLIB_AVAILABLE_IN_2_30
 349 void    g_test_fail                     (void);
 350 GLIB_AVAILABLE_IN_2_70
 351 void    g_test_fail_printf              (const char *format,
 352                                          ...) G_GNUC_PRINTF (1, 2);
 353 GLIB_AVAILABLE_IN_2_38
 354 void    g_test_incomplete               (const gchar *msg);
 355 GLIB_AVAILABLE_IN_2_70
 356 void    g_test_incomplete_printf        (const char *format,
 357                                          ...) G_GNUC_PRINTF (1, 2);
 358 GLIB_AVAILABLE_IN_2_38
 359 void    g_test_skip                     (const gchar *msg);
 360 GLIB_AVAILABLE_IN_2_70
 361 void    g_test_skip_printf              (const char *format,
 362                                          ...) G_GNUC_PRINTF (1, 2);
 363 GLIB_AVAILABLE_IN_2_38
 364 gboolean g_test_failed                  (void);
 365 GLIB_AVAILABLE_IN_2_38
 366 void    g_test_set_nonfatal_assertions  (void);
 367
 368 /**
 369  * g_test_add:
 370  * @testpath:  The test path for a new test case.
 371  * @Fixture:   The type of a fixture data structure.
 372  * @tdata:     Data argument for the test functions.
 373  * @fsetup:    The function to set up the fixture data.
 374  * @ftest:     The actual test function.
 375  * @fteardown: The function to tear down the fixture data.
 376  *
 377  * Hook up a new test case at @testpath, similar to g_test_add_func().
 378  * A fixture data structure with setup and teardown functions may be provided,
 379  * similar to g_test_create_case().
 380  *
 381  * g_test_add() is implemented as a macro, so that the fsetup(), ftest() and
 382  * fteardown() callbacks can expect a @Fixture pointer as their first argument
 383  * in a type safe manner. They otherwise have type #GTestFixtureFunc.
 384  *
 385  * Since: 2.16
 386  */
 387 #define g_test_add(testpath, Fixture, tdata, fsetup, ftest, fteardown) \
 388                                         G_STMT_START {                  \
 389                                          void (*add_vtable) (const char*,       \
 390                                                     gsize,             \
 391                                                     gconstpointer,     \
 392                                                     void (*) (Fixture*, gconstpointer),   \
 393                                                     void (*) (Fixture*, gconstpointer),   \
 394                                                     void (*) (Fixture*, gconstpointer)) =  (void (*) (const gchar *, gsize, gconstpointer, void (*) (Fixture*, gconstpointer), void (*) (Fixture*, gconstpointer), void (*) (Fixture*, gconstpointer))) g_test_add_vtable; \
 395                                          add_vtable \
 396                                           (testpath, sizeof (Fixture), tdata, fsetup, ftest, fteardown); \
 397                                         } G_STMT_END
 398
 399 /* add test messages to the test report */
 400 GLIB_AVAILABLE_IN_ALL
 401 void    g_test_message                  (const char *format,
 402                                          ...) G_GNUC_PRINTF (1, 2);
 403 GLIB_AVAILABLE_IN_ALL
 404 void    g_test_bug_base                 (const char *uri_pattern);
 405 GLIB_AVAILABLE_IN_ALL
 406 void    g_test_bug                      (const char *bug_uri_snippet);
 407 GLIB_AVAILABLE_IN_2_62
 408 void    g_test_summary                  (const char *summary);
 409 /* measure test timings */
 410 GLIB_AVAILABLE_IN_ALL
 411 void    g_test_timer_start              (void);
 412 GLIB_AVAILABLE_IN_ALL
 413 double  g_test_timer_elapsed            (void); /* elapsed seconds */
 414 GLIB_AVAILABLE_IN_ALL
 415 double  g_test_timer_last               (void); /* repeat last elapsed() result */
 416
 417 /* automatically g_free or g_object_unref upon teardown */
 418 GLIB_AVAILABLE_IN_ALL
 419 void    g_test_queue_free               (gpointer gfree_pointer);
 420 GLIB_AVAILABLE_IN_ALL
 421 void    g_test_queue_destroy            (GDestroyNotify destroy_func,
 422                                          gpointer       destroy_data);
 423 #define g_test_queue_unref(gobject)     g_test_queue_destroy (g_object_unref, gobject)
 424
 425 /**
 426  * GTestTrapFlags:
 427  * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
 428  *     `/dev/null` so it cannot be observed on the console during test
 429  *     runs. The actual output is still captured though to allow later
 430  *     tests with g_test_trap_assert_stdout().
 431  * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
 432  *     `/dev/null` so it cannot be observed on the console during test
 433  *     runs. The actual output is still captured though to allow later
 434  *     tests with g_test_trap_assert_stderr().
 435  * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the
 436  *     child process is shared with stdin of its parent process.
 437  *     It is redirected to `/dev/null` otherwise.
 438  *
 439  * Test traps are guards around forked tests.
 440  * These flags determine what traps to set.
 441  *
 442  * Deprecated: 2.38: #GTestTrapFlags is used only with g_test_trap_fork(),
 443  * which is deprecated. g_test_trap_subprocess() uses
 444  * #GTestSubprocessFlags.
 445  */
 446 typedef enum {
 447   G_TEST_TRAP_SILENCE_STDOUT    = 1 << 7,
 448   G_TEST_TRAP_SILENCE_STDERR    = 1 << 8,
 449   G_TEST_TRAP_INHERIT_STDIN     = 1 << 9
 450 } GTestTrapFlags GLIB_DEPRECATED_TYPE_IN_2_38_FOR(GTestSubprocessFlags);
 451
 452 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 453
 454 GLIB_DEPRECATED_IN_2_38_FOR (g_test_trap_subprocess)
 455 gboolean g_test_trap_fork               (guint64              usec_timeout,
 456                                          GTestTrapFlags       test_trap_flags);
 457
 458 G_GNUC_END_IGNORE_DEPRECATIONS
 459
 460 typedef enum {
 461   G_TEST_SUBPROCESS_INHERIT_STDIN  = 1 << 0,
 462   G_TEST_SUBPROCESS_INHERIT_STDOUT = 1 << 1,
 463   G_TEST_SUBPROCESS_INHERIT_STDERR = 1 << 2
 464 } GTestSubprocessFlags;
 465
 466 GLIB_AVAILABLE_IN_2_38
 467 void     g_test_trap_subprocess         (const char           *test_path,
 468                                          guint64               usec_timeout,
 469                                          GTestSubprocessFlags  test_flags);
 470
 471 GLIB_AVAILABLE_IN_ALL
 472 gboolean g_test_trap_has_passed         (void);
 473 GLIB_AVAILABLE_IN_ALL
 474 gboolean g_test_trap_reached_timeout    (void);
 475 #define  g_test_trap_assert_passed()                      g_test_trap_assertions (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, 0, 0)
 476 #define  g_test_trap_assert_failed()                      g_test_trap_assertions (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, 1, 0)
 477 #define  g_test_trap_assert_stdout(soutpattern)           g_test_trap_assertions (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, 2, soutpattern)
 478 #define  g_test_trap_assert_stdout_unmatched(soutpattern) g_test_trap_assertions (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, 3, soutpattern)
 479 #define  g_test_trap_assert_stderr(serrpattern)           g_test_trap_assertions (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, 4, serrpattern)
 480 #define  g_test_trap_assert_stderr_unmatched(serrpattern) g_test_trap_assertions (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, 5, serrpattern)
 481
 482 /* provide seed-able random numbers for tests */
 483 #define  g_test_rand_bit()              (0 != (g_test_rand_int() & (1 << 15)))
 484 GLIB_AVAILABLE_IN_ALL
 485 gint32   g_test_rand_int                (void);
 486 GLIB_AVAILABLE_IN_ALL
 487 gint32   g_test_rand_int_range          (gint32          begin,
 488                                          gint32          end);
 489 GLIB_AVAILABLE_IN_ALL
 490 double   g_test_rand_double             (void);
 491 GLIB_AVAILABLE_IN_ALL
 492 double   g_test_rand_double_range       (double          range_start,
 493                                          double          range_end);
 494
 495 /*
 496  * semi-internal API: non-documented symbols with stable ABI. You
 497  * should use the non-internal helper macros instead. However, for
 498  * compatibility reason, you may use this semi-internal API.
 499  */
 500 GLIB_AVAILABLE_IN_ALL
 501 GTestCase*    g_test_create_case        (const char       *test_name,
 502                                          gsize             data_size,
 503                                          gconstpointer     test_data,
 504                                          GTestFixtureFunc  data_setup,
 505                                          GTestFixtureFunc  data_test,
 506                                          GTestFixtureFunc  data_teardown);
 507 GLIB_AVAILABLE_IN_ALL
 508 GTestSuite*   g_test_create_suite       (const char       *suite_name);
 509 GLIB_AVAILABLE_IN_ALL
 510 GTestSuite*   g_test_get_root           (void);
 511 GLIB_AVAILABLE_IN_ALL
 512 void          g_test_suite_add          (GTestSuite     *suite,
 513                                          GTestCase      *test_case);
 514 GLIB_AVAILABLE_IN_ALL
 515 void          g_test_suite_add_suite    (GTestSuite     *suite,
 516                                          GTestSuite     *nestedsuite);
 517 GLIB_AVAILABLE_IN_ALL
 518 int           g_test_run_suite          (GTestSuite     *suite);
 519
 520 GLIB_AVAILABLE_IN_2_70
 521 void          g_test_case_free          (GTestCase *test_case);
 522
 523 GLIB_AVAILABLE_IN_2_70
 524 void          g_test_suite_free         (GTestSuite     *suite);
 525
 526 GLIB_AVAILABLE_IN_ALL
 527 void    g_test_trap_assertions          (const char     *domain,
 528                                          const char     *file,
 529                                          int             line,
 530                                          const char     *func,
 531                                          guint64         assertion_flags, /* 0-pass, 1-fail, 2-outpattern, 4-errpattern */
 532                                          const char     *pattern);
 533 GLIB_AVAILABLE_IN_ALL
 534 void    g_assertion_message             (const char     *domain,
 535                                          const char     *file,
 536                                          int             line,
 537                                          const char     *func,
 538                                          const char     *message) G_ANALYZER_NORETURN;
 539 GLIB_AVAILABLE_IN_ALL
 540 G_NORETURN
 541 void    g_assertion_message_expr        (const char     *domain,
 542                                          const char     *file,
 543                                          int             line,
 544                                          const char     *func,
 545                                          const char     *expr);
 546 GLIB_AVAILABLE_IN_ALL
 547 void    g_assertion_message_cmpstr      (const char     *domain,
 548                                          const char     *file,
 549                                          int             line,
 550                                          const char     *func,
 551                                          const char     *expr,
 552                                          const char     *arg1,
 553                                          const char     *cmp,
 554                                          const char     *arg2) G_ANALYZER_NORETURN;
 555
 556 GLIB_AVAILABLE_IN_2_68
 557 void    g_assertion_message_cmpstrv     (const char         *domain,
 558                                          const char         *file,
 559                                          int                 line,
 560                                          const char         *func,
 561                                          const char         *expr,
 562                                          const char * const *arg1,
 563                                          const char * const *arg2,
 564                                          gsize               first_wrong_idx) G_ANALYZER_NORETURN;
 565 GLIB_AVAILABLE_IN_ALL
 566 void    g_assertion_message_cmpnum      (const char     *domain,
 567                                          const char     *file,
 568                                          int             line,
 569                                          const char     *func,
 570                                          const char     *expr,
 571                                          long double     arg1,
 572                                          const char     *cmp,
 573                                          long double     arg2,
 574                                          char            numtype) G_ANALYZER_NORETURN;
 575 GLIB_AVAILABLE_IN_ALL
 576 void    g_assertion_message_error       (const char     *domain,
 577                                          const char     *file,
 578                                          int             line,
 579                                          const char     *func,
 580                                          const char     *expr,
 581                                          const GError   *error,
 582                                          GQuark          error_domain,
 583                                          int             error_code) G_ANALYZER_NORETURN;
 584 GLIB_AVAILABLE_IN_ALL
 585 void    g_test_add_vtable               (const char     *testpath,
 586                                          gsize           data_size,
 587                                          gconstpointer   test_data,
 588                                          GTestFixtureFunc  data_setup,
 589                                          GTestFixtureFunc  data_test,
 590                                          GTestFixtureFunc  data_teardown);
 591 typedef struct {
 592   gboolean      test_initialized;
 593   gboolean      test_quick;     /* disable thorough tests */
 594   gboolean      test_perf;      /* run performance tests */
 595   gboolean      test_verbose;   /* extra info */
 596   gboolean      test_quiet;     /* reduce output */
 597   gboolean      test_undefined; /* run tests that are meant to assert */
 598 } GTestConfig;
 599 GLIB_VAR const GTestConfig * const g_test_config_vars;
 600
 601 /* internal logging API */
 602 typedef enum {
 603   G_TEST_RUN_SUCCESS,
 604   G_TEST_RUN_SKIPPED,
 605   G_TEST_RUN_FAILURE,
 606   G_TEST_RUN_INCOMPLETE
 607 } GTestResult;
 608
 609 typedef enum {
 610   G_TEST_LOG_NONE,
 611   G_TEST_LOG_ERROR,             /* s:msg */
 612   G_TEST_LOG_START_BINARY,      /* s:binaryname s:seed */
 613   G_TEST_LOG_LIST_CASE,         /* s:testpath */
 614   G_TEST_LOG_SKIP_CASE,         /* s:testpath */
 615   G_TEST_LOG_START_CASE,        /* s:testpath */
 616   G_TEST_LOG_STOP_CASE,         /* d:status d:nforks d:elapsed */
 617   G_TEST_LOG_MIN_RESULT,        /* s:blurb d:result */
 618   G_TEST_LOG_MAX_RESULT,        /* s:blurb d:result */
 619   G_TEST_LOG_MESSAGE,           /* s:blurb */
 620   G_TEST_LOG_START_SUITE,
 621   G_TEST_LOG_STOP_SUITE
 622 } GTestLogType;
 623
 624 typedef struct {
 625   GTestLogType  log_type;
 626   guint         n_strings;
 627   gchar       **strings; /* NULL terminated */
 628   guint         n_nums;
 629   long double  *nums;
 630 } GTestLogMsg;
 631 typedef struct {
 632   /*< private >*/
 633   GString     *data;
 634   GSList      *msgs;
 635 } GTestLogBuffer;
 636
 637 GLIB_AVAILABLE_IN_ALL
 638 const char*     g_test_log_type_name    (GTestLogType    log_type);
 639 GLIB_AVAILABLE_IN_ALL
 640 GTestLogBuffer* g_test_log_buffer_new   (void);
 641 GLIB_AVAILABLE_IN_ALL
 642 void            g_test_log_buffer_free  (GTestLogBuffer *tbuffer);
 643 GLIB_AVAILABLE_IN_ALL
 644 void            g_test_log_buffer_push  (GTestLogBuffer *tbuffer,
 645                                          guint           n_bytes,
 646                                          const guint8   *bytes);
 647 GLIB_AVAILABLE_IN_ALL
 648 GTestLogMsg*    g_test_log_buffer_pop   (GTestLogBuffer *tbuffer);
 649 GLIB_AVAILABLE_IN_ALL
 650 void            g_test_log_msg_free     (GTestLogMsg    *tmsg);
 651
 652 /**
 653  * GTestLogFatalFunc:
 654  * @log_domain: the log domain of the message
 655  * @log_level: the log level of the message (including the fatal and recursion flags)
 656  * @message: the message to process
 657  * @user_data: user data, set in g_test_log_set_fatal_handler()
 658  *
 659  * Specifies the prototype of fatal log handler functions.
 660  *
 661  * Returns: %TRUE if the program should abort, %FALSE otherwise
 662  *
 663  * Since: 2.22
 664  */
 665 typedef gboolean        (*GTestLogFatalFunc)    (const gchar    *log_domain,
 666                                                  GLogLevelFlags  log_level,
 667                                                  const gchar    *message,
 668                                                  gpointer        user_data);
 669 GLIB_AVAILABLE_IN_ALL
 670 void
 671 g_test_log_set_fatal_handler            (GTestLogFatalFunc log_func,
 672                                          gpointer          user_data);
 673
 674 GLIB_AVAILABLE_IN_2_34
 675 void    g_test_expect_message                    (const gchar    *log_domain,
 676                                                   GLogLevelFlags  log_level,
 677                                                   const gchar    *pattern);
 678 GLIB_AVAILABLE_IN_2_34
 679 void    g_test_assert_expected_messages_internal (const char     *domain,
 680                                                   const char     *file,
 681                                                   int             line,
 682                                                   const char     *func);
 683
 684 typedef enum
 685 {
 686   G_TEST_DIST,
 687   G_TEST_BUILT
 688 } GTestFileType;
 689
 690 GLIB_AVAILABLE_IN_2_38
 691 gchar * g_test_build_filename                    (GTestFileType   file_type,
 692                                                   const gchar    *first_path,
 693                                                   ...) G_GNUC_NULL_TERMINATED;
 694 GLIB_AVAILABLE_IN_2_38
 695 const gchar *g_test_get_dir                      (GTestFileType   file_type);
 696 GLIB_AVAILABLE_IN_2_38
 697 const gchar *g_test_get_filename                 (GTestFileType   file_type,
 698                                                   const gchar    *first_path,
 699                                                   ...) G_GNUC_NULL_TERMINATED;
 700
 701 #define g_test_assert_expected_messages() g_test_assert_expected_messages_internal (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC)
 702
 703 G_END_DECLS
 704
 705 #endif /* __G_TEST_UTILS_H__ */