docs/reference/glib/tmpl/testing.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Testing
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 a test framework
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GLib provides a framework for writing and maintaining unit tests
  10 in parallel to the code they are testing. The API is designed according
  11 to established concepts found in the other test frameworks (JUnit, NUnit,
  12 RUnit), which in turn is based on smalltalk unit testing concepts.
  13 <variablelist>
  14   <varlistentry>
  15     <term>Test case</term>
  16     <listitem><para>
  17       Tests (test methods) are grouped together with their
  18       fixture into test cases.
  19     </para></listitem>
  20   </varlistentry>
  21   <varlistentry>
  22     <term>Fixture</term>
  23     <listitem><para>
  24       A test fixture consists of fixture data and setup and teardown methods
  25       to establish the environment for the test functions. We use fresh
  26       fixtures, i.e. fixtures are newly set up and torn down around each test
  27       invocation to avoid dependencies between tests.
  28     </para></listitem>
  29   </varlistentry>
  30   <varlistentry>
  31     <term>Test suite</term>
  32     <listitem><para>
  33       Test cases can be grouped into test suites, to allow subsets of the
  34       available tests to be run. Test suites can be grouped into other test
  35       suites as well.
  36     </para></listitem>
  37   </varlistentry>
  38 </variablelist>
  39 The API is designed to handle creation and registration of test suites and
  40 test cases implicitly. A simple call like
  41 <informalexample><programlisting>
  42   g_test_add_func ("/misc/assertions", test_assertions);
  43 </programlisting></informalexample>
  44 creates a test suite called "misc" with a single test case named "assertions",
  45 which consists of running the test_assertions function.
  46 </para>
  47 <para>
  48 In addition to the traditional g_assert(), the test framework provides
  49 an extended set of assertions for string and numerical comparisons:
  50 g_assert_cmpfloat(), g_assert_cmpint(), g_assert_cmpuint(), g_assert_cmphex(),
  51 g_assert_cmpstr(). The advantage of these variants over plain g_assert()
  52 is that the assertion messages can be more elaborate, and include the
  53 values of the compared entities.
  54 </para>
  55 <para>
  56 GLib ships with two utilities called gtester and gtester-report to
  57 facilitate running tests and producing nicely formatted test reports.
  58 </para>
  59
  60 <!-- ##### SECTION See_Also ##### -->
  61 <para>
  62 <link linkend="gtester">gtester</link>,
  63 <link linkend="gtester-report">gtester-report</link>
  64 </para>
  65
  66 <!-- ##### SECTION Stability_Level ##### -->
  67
  68
  69 <!-- ##### FUNCTION g_test_minimized_result ##### -->
  70 <para>
  71
  72 </para>
  73
  74 @minimized_quantity:
  75 @format:
  76 @Varargs:
  77
  78
  79 <!-- ##### FUNCTION g_test_maximized_result ##### -->
  80 <para>
  81
  82 </para>
  83
  84 @maximized_quantity:
  85 @format:
  86 @Varargs:
  87
  88
  89 <!-- ##### FUNCTION g_test_init ##### -->
  90 <para>
  91
  92 </para>
  93
  94 @argc:
  95 @argv:
  96 @Varargs:
  97
  98
  99 <!-- ##### MACRO g_test_quick ##### -->
 100 <para>
 101 Returns %TRUE if tests are run in quick mode.
 102 </para>
 103
 104
 105
 106 <!-- ##### MACRO g_test_slow ##### -->
 107 <para>
 108 Returns %TRUE if tests are run in slow mode.
 109 </para>
 110
 111
 112
 113 <!-- ##### MACRO g_test_thorough ##### -->
 114 <para>
 115 Returns %TRUE if tests are run in thorough mode.
 116 </para>
 117
 118
 119
 120 <!-- ##### MACRO g_test_perf ##### -->
 121 <para>
 122 Returns %TRUE if tests are run in performance mode.
 123 </para>
 124
 125
 126
 127 <!-- ##### MACRO g_test_verbose ##### -->
 128 <para>
 129 Returns %TRUE if tests are run in verbose mode.
 130 </para>
 131
 132
 133
 134 <!-- ##### MACRO g_test_quiet ##### -->
 135 <para>
 136 Returns %TRUE if tests are run in quiet mode.
 137 </para>
 138
 139
 140
 141 <!-- ##### FUNCTION g_test_run ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @Returns:
 147
 148
 149 <!-- ##### FUNCTION g_test_add_func ##### -->
 150 <para>
 151
 152 </para>
 153
 154 @testpath:
 155 @test_func:
 156
 157
 158 <!-- ##### FUNCTION g_test_add_data_func ##### -->
 159 <para>
 160
 161 </para>
 162
 163 @testpath:
 164 @test_data:
 165 @test_func:
 166
 167
 168 <!-- ##### MACRO g_test_add ##### -->
 169 <para>
 170
 171 </para>
 172
 173 @testpath:
 174 @Fixture:
 175 @tdata:
 176 @fsetup:
 177 @ftest:
 178 @fteardown:
 179
 180
 181 <!-- ##### FUNCTION g_test_message ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @format:
 187 @Varargs:
 188
 189
 190 <!-- ##### FUNCTION g_test_bug_base ##### -->
 191 <para>
 192
 193 </para>
 194
 195 @uri_pattern:
 196
 197
 198 <!-- ##### FUNCTION g_test_bug ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @bug_uri_snippet:
 204
 205
 206 <!-- ##### USER_FUNCTION GTestLogFatalFunc ##### -->
 207 <para>
 208
 209 </para>
 210
 211 @log_domain:
 212 @log_level:
 213 @message:
 214 @user_data:
 215 @Returns:
 216
 217
 218 <!-- ##### FUNCTION g_test_log_set_fatal_handler ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @log_func:
 224 @user_data:
 225
 226
 227 <!-- ##### FUNCTION g_test_timer_start ##### -->
 228 <para>
 229
 230 </para>
 231
 232
 233
 234 <!-- ##### FUNCTION g_test_timer_elapsed ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @Returns:
 240
 241
 242 <!-- ##### FUNCTION g_test_timer_last ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @Returns:
 248
 249
 250 <!-- ##### FUNCTION g_test_queue_free ##### -->
 251 <para>
 252
 253 </para>
 254
 255 @gfree_pointer:
 256
 257
 258 <!-- ##### FUNCTION g_test_queue_destroy ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @destroy_func:
 264 @destroy_data:
 265
 266
 267 <!-- ##### MACRO g_test_queue_unref ##### -->
 268 <para>
 269 Enqueue an object to be released with g_object_unref() during
 270 the next teardown phase. This is equivalent to calling g_test_queue_destroy()
 271 with a destroy callback of g_object_unref().
 272 </para>
 273
 274 @gobject: the object to unref
 275 @Since: 2.16
 276
 277
 278 <!-- ##### ENUM GTestTrapFlags ##### -->
 279 <para>
 280 Test traps are guards around forked tests. These flags
 281 determine what traps to set.
 282 </para>
 283
 284 @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
 285     <filename>/dev/null</filename> so it cannot be observed on the
 286     console during test runs. The actual output is still captured
 287     though to allow later tests with g_test_trap_assert_stdout().
 288 @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
 289     <filename>/dev/null</filename> so it cannot be observed on the
 290     console during test runs. The actual output is still captured
 291     though to allow later tests with g_test_trap_assert_stderr().
 292 @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the forked
 293     child process is shared with stdin of its parent process. It is
 294     redirected to <filename>/dev/null</filename> otherwise.
 295
 296 <!-- ##### FUNCTION g_test_trap_fork ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @usec_timeout:
 302 @test_trap_flags:
 303 @Returns:
 304
 305
 306 <!-- ##### FUNCTION g_test_trap_has_passed ##### -->
 307 <para>
 308
 309 </para>
 310
 311 @Returns:
 312
 313
 314 <!-- ##### FUNCTION g_test_trap_reached_timeout ##### -->
 315 <para>
 316
 317 </para>
 318
 319 @Returns:
 320
 321
 322 <!-- ##### MACRO g_test_trap_assert_passed ##### -->
 323 <para>
 324 Assert that the last forked test passed. See g_test_trap_fork().
 325 </para>
 326
 327 @Since: 2.16
 328
 329
 330 <!-- ##### MACRO g_test_trap_assert_failed ##### -->
 331 <para>
 332 Assert that the last forked test failed. See g_test_trap_fork().
 333 </para>
 334
 335 @Since: 2.16
 336
 337
 338 <!-- ##### MACRO g_test_trap_assert_stdout ##### -->
 339 <para>
 340 Assert that the stdout output of the last forked test matches @soutpattern.
 341 See g_test_trap_fork().
 342 </para>
 343
 344 @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
 345 @Since: 2.16
 346
 347
 348 <!-- ##### MACRO g_test_trap_assert_stdout_unmatched ##### -->
 349 <para>
 350 Assert that the stdout output of the last forked test does not match
 351 @soutpattern.  See g_test_trap_fork().
 352 </para>
 353
 354 @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
 355 @Since: 2.16
 356
 357
 358 <!-- ##### MACRO g_test_trap_assert_stderr ##### -->
 359 <para>
 360 Assert that the stderr output of the last forked test matches @serrpattern.
 361 See g_test_trap_fork().
 362 </para>
 363
 364 @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
 365 @Since: 2.16
 366
 367
 368 <!-- ##### MACRO g_test_trap_assert_stderr_unmatched ##### -->
 369 <para>
 370 Assert that the stderr output of the last forked test does not match
 371 @serrpattern.  See g_test_trap_fork().
 372 </para>
 373
 374 @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link>
 375 @Since: 2.16
 376
 377
 378 <!-- ##### MACRO g_test_rand_bit ##### -->
 379 <para>
 380 Get a reproducible random bit (0 or 1),
 381 see g_test_rand_int() for details on test case random numbers.
 382 </para>
 383
 384 @Since: 2.16
 385
 386
 387 <!-- ##### FUNCTION g_test_rand_int ##### -->
 388 <para>
 389
 390 </para>
 391
 392 @Returns:
 393
 394
 395 <!-- ##### FUNCTION g_test_rand_int_range ##### -->
 396 <para>
 397
 398 </para>
 399
 400 @begin:
 401 @end:
 402 @Returns:
 403
 404
 405 <!-- ##### FUNCTION g_test_rand_double ##### -->
 406 <para>
 407
 408 </para>
 409
 410 @Returns:
 411
 412
 413 <!-- ##### FUNCTION g_test_rand_double_range ##### -->
 414 <para>
 415
 416 </para>
 417
 418 @range_start:
 419 @range_end:
 420 @Returns:
 421
 422
 423 <!-- ##### MACRO g_assert ##### -->
 424 <para>
 425 Debugging macro to terminate the application if the assertion fails.
 426 If the assertion fails (i.e. the expression is not true), an error message
 427 is logged and the application is terminated.
 428 </para>
 429 <para>
 430 The macro can be turned off in final releases of code by defining
 431 #G_DISABLE_ASSERT when compiling the application.
 432 </para>
 433
 434 @expr: the expression to check.
 435
 436
 437 <!-- ##### MACRO g_assert_not_reached ##### -->
 438 <para>
 439 Debugging macro to terminate the application if it is ever reached.
 440 If it is reached, an error message is logged and the application is terminated.
 441 </para>
 442 <para>
 443 The macro can be turned off in final releases of code by defining
 444 #G_DISABLE_ASSERT when compiling the application.
 445 </para>
 446
 447
 448
 449 <!-- ##### MACRO g_assert_cmpstr ##### -->
 450 <para>
 451 Debugging macro to terminate the application with a warning message
 452 if a string comparison fails.
 453 The strings are compared using g_strcmp0().
 454 </para>
 455 <para>
 456 The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is the same
 457 as <literal>g_assert (g_strcmp0 (s1, s2) op 0)</literal>. The advantage of this macro
 458 is that it can produce a message that includes the actual values of @s1
 459 and @s2.
 460 </para>
 461 <informalexample><programlisting>
 462   g_assert_cmpstr (mystring, ==, "fubar");
 463 </programlisting></informalexample>
 464
 465 @s1: a string (may be %NULL)
 466 @cmp: The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 467 @s2: another string (may be %NULL)
 468 @Since: 2.16
 469
 470
 471 <!-- ##### MACRO g_assert_cmpint ##### -->
 472 <para>
 473 Debugging macro to terminate the application with a warning message
 474 if an integer comparison fails.
 475 </para>
 476 <para>
 477 The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is the same
 478 as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
 479 is that it can produce a message that includes the actual values of @n1
 480 and @n2.
 481 </para>
 482
 483 @n1: an integer
 484 @cmp: The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 485 @n2: another integer
 486 @Since: 2.16
 487
 488
 489 <!-- ##### MACRO g_assert_cmpuint ##### -->
 490 <para>
 491 Debugging macro to terminate the application with a warning message
 492 if an unsigned integer comparison fails.
 493 </para>
 494 <para>
 495 The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is the same
 496 as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
 497 is that it can produce a message that includes the actual values of @n1
 498 and @n2.
 499 </para>
 500
 501 @n1: an unsigned integer
 502 @cmp: The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 503 @n2: another unsigned integer
 504 @Since: 2.16
 505
 506
 507 <!-- ##### MACRO g_assert_cmphex ##### -->
 508 <para>
 509 Debugging macro to terminate the application with a warning message
 510 if an unsigned integer comparison fails. This is a variant of
 511 g_assert_cmpuint() that displays the numbers in hexadecimal notation
 512 in the message.
 513 </para>
 514
 515 @n1: an unsigned integer
 516 @cmp: The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 517 @n2: another unsigned integer
 518 @Since: 2.16
 519
 520
 521 <!-- ##### MACRO g_assert_cmpfloat ##### -->
 522 <para>
 523 Debugging macro to terminate the application with a warning message
 524 if a floating point number comparison fails.
 525 </para>
 526 <para>
 527 The effect of <literal>g_assert_cmpfloat (n1, op, n2)</literal> is the same
 528 as <literal>g_assert (n1 op n2)</literal>. The advantage of this function
 529 is that it can produce a message that includes the actual values of @n1
 530 and @n2.
 531 </para>
 532
 533 @n1: an floating point number
 534 @cmp: The comparison operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 535 @n2: another floating point number
 536 @Since: 2.16
 537
 538
 539 <!-- ##### MACRO g_assert_no_error ##### -->
 540 <para>
 541 Debugging macro to terminate the application with a warning message
 542 if a method has returned a #GError.
 543 </para>
 544 <para>
 545 The effect of <literal>g_assert_no_error (err)</literal> is the same
 546 as <literal>g_assert (err == NULL)</literal>. The advantage of this macro
 547 is that it can produce a message that includes the error message and code.
 548 </para>
 549
 550 @err: a #GError, possibly %NULL
 551 @Since: 2.20
 552
 553
 554 <!-- ##### MACRO g_assert_error ##### -->
 555 <para>
 556 Debugging macro to terminate the application with a warning message
 557 if a method has not returned the correct #GError.
 558 </para>
 559 <para>
 560 The effect of <literal>g_assert_error (err, dom, c)</literal> is the same
 561 as <literal>g_assert (err != NULL &amp;&amp; err->domain == dom &amp;&amp; err->code == c)</literal>.
 562 The advantage of this macro is that it can produce a message that
 563 includes the incorrect error message and code.
 564 </para>
 565 <para>
 566 This can only be used to test for a specific error. If you want to
 567 test that @err is set, but don't care what it's set to, just use
 568 <literal>g_assert (err != NULL)</literal>
 569 </para>
 570
 571 @err: a #GError, possibly %NULL
 572 @dom: the expected error domain (a #GQuark)
 573 @c: the expected error code
 574 @Since: 2.20
 575
 576
 577 <!-- ##### TYPEDEF GTestCase ##### -->
 578 <para>
 579 An opaque structure representing a test case.
 580 </para>
 581
 582
 583 <!-- ##### TYPEDEF GTestSuite ##### -->
 584 <para>
 585 An opaque structure representing a test suite.
 586 </para>
 587
 588
 589 <!-- ##### FUNCTION g_test_create_case ##### -->
 590 <para>
 591
 592 </para>
 593
 594 @test_name:
 595 @data_size:
 596 @test_data:
 597 @data_setup:
 598 @data_test:
 599 @data_teardown:
 600 @Returns:
 601
 602
 603 <!-- ##### FUNCTION g_test_create_suite ##### -->
 604 <para>
 605
 606 </para>
 607
 608 @suite_name:
 609 @Returns:
 610
 611
 612 <!-- ##### FUNCTION g_test_get_root ##### -->
 613 <para>
 614
 615 </para>
 616
 617 @Returns:
 618
 619
 620 <!-- ##### FUNCTION g_test_suite_add ##### -->
 621 <para>
 622
 623 </para>
 624
 625 @suite:
 626 @test_case:
 627
 628
 629 <!-- ##### FUNCTION g_test_suite_add_suite ##### -->
 630 <para>
 631
 632 </para>
 633
 634 @suite:
 635 @nestedsuite:
 636
 637
 638 <!-- ##### FUNCTION g_test_run_suite ##### -->
 639 <para>
 640
 641 </para>
 642
 643 @suite:
 644 @Returns:
 645
 646