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       invokation 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 utilites 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 quite 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 <!-- ##### FUNCTION g_test_timer_start ##### -->
 207 <para>
 208
 209 </para>
 210
 211
 212
 213 <!-- ##### FUNCTION g_test_timer_elapsed ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @Returns:
 219
 220
 221 <!-- ##### FUNCTION g_test_timer_last ##### -->
 222 <para>
 223
 224 </para>
 225
 226 @Returns:
 227
 228
 229 <!-- ##### FUNCTION g_test_queue_free ##### -->
 230 <para>
 231
 232 </para>
 233
 234 @gfree_pointer:
 235
 236
 237 <!-- ##### FUNCTION g_test_queue_destroy ##### -->
 238 <para>
 239
 240 </para>
 241
 242 @destroy_func:
 243 @destroy_data:
 244
 245
 246 <!-- ##### MACRO g_test_queue_unref ##### -->
 247 <para>
 248
 249 </para>
 250
 251 @gobject:
 252
 253
 254 <!-- ##### ENUM GTestTrapFlags ##### -->
 255 <para>
 256 Test traps are guards around forked tests. These flags
 257 determine what traps to set.
 258 </para>
 259
 260 @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
 261     <filename>/dev/null</filename> so it cannot be observed on the
 262     console during test runs. The actual output is still captured
 263     though to allow later tests with g_test_trap_assert_stdout().
 264
 265 @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
 266     <filename>/dev/null</filename> so it cannot be observed on the
 267     console during test runs. The actual output is still captured
 268     though to allow later tests with g_test_trap_assert_stderr().
 269
 270 @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the forked
 271     child process is shared with stdin of its parent process. It is
 272     redirected to <filename>/dev/null</filename> otherwise.
 273
 274
 275 <!-- ##### FUNCTION g_test_trap_fork ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @usec_timeout:
 281 @test_trap_flags:
 282 @Returns:
 283
 284
 285 <!-- ##### FUNCTION g_test_trap_has_passed ##### -->
 286 <para>
 287
 288 </para>
 289
 290 @Returns:
 291
 292
 293 <!-- ##### FUNCTION g_test_trap_reached_timeout ##### -->
 294 <para>
 295
 296 </para>
 297
 298 @Returns:
 299
 300
 301 <!-- ##### MACRO g_test_trap_assert_passed ##### -->
 302 <para>
 303
 304 </para>
 305
 306
 307
 308 <!-- ##### MACRO g_test_trap_assert_failed ##### -->
 309 <para>
 310
 311 </para>
 312
 313
 314
 315 <!-- ##### MACRO g_test_trap_assert_stdout ##### -->
 316 <para>
 317
 318 </para>
 319
 320 @soutpattern:
 321
 322
 323 <!-- ##### MACRO g_test_trap_assert_stdout_unmatched ##### -->
 324 <para>
 325
 326 </para>
 327
 328 @soutpattern:
 329
 330
 331 <!-- ##### MACRO g_test_trap_assert_stderr ##### -->
 332 <para>
 333
 334 </para>
 335
 336 @serrpattern:
 337
 338
 339 <!-- ##### MACRO g_test_trap_assert_stderr_unmatched ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @serrpattern:
 345
 346
 347 <!-- ##### MACRO g_test_rand_bit ##### -->
 348 <para>
 349
 350 </para>
 351
 352
 353
 354 <!-- ##### FUNCTION g_test_rand_int ##### -->
 355 <para>
 356
 357 </para>
 358
 359 @Returns:
 360
 361
 362 <!-- ##### FUNCTION g_test_rand_int_range ##### -->
 363 <para>
 364
 365 </para>
 366
 367 @begin:
 368 @end:
 369 @Returns:
 370
 371
 372 <!-- ##### FUNCTION g_test_rand_double ##### -->
 373 <para>
 374
 375 </para>
 376
 377 @Returns:
 378
 379
 380 <!-- ##### FUNCTION g_test_rand_double_range ##### -->
 381 <para>
 382
 383 </para>
 384
 385 @range_start:
 386 @range_end:
 387 @Returns:
 388
 389
 390 <!-- ##### MACRO g_assert ##### -->
 391 <para>
 392 Debugging macro to terminate the application if the assertion fails.
 393 If the assertion fails (i.e. the expression is not true), an error message
 394 is logged and the application is terminated.
 395 </para>
 396 <para>
 397 The macro can be turned off in final releases of code by defining
 398 #G_DISABLE_ASSERT when compiling the application.
 399 </para>
 400
 401 @expr: the expression to check.
 402
 403
 404 <!-- ##### MACRO g_assert_not_reached ##### -->
 405 <para>
 406 Debugging macro to terminate the application if it is ever reached.
 407 If it is reached, an error message is logged and the application is terminated.
 408 </para>
 409 <para>
 410 The macro can be turned off in final releases of code by defining
 411 #G_DISABLE_ASSERT when compiling the application.
 412 </para>
 413
 414
 415
 416 <!-- ##### MACRO g_assert_cmpstr ##### -->
 417 <para>
 418 Debugging macro to terminate the application with a warning message
 419 if a string comparison fails.
 420 The strings are compared using g_strcmp0().
 421 </para>
 422 <para>
 423 The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is the same
 424 as <literal>g_assert (s1 op s2)</literal>. The advantage of this macro
 425 is that it can produce a message that includes the actual values of @s1
 426 and @s2.
 427 </para>
 428 <informalexample><programlisting>
 429   g_assert_cmpstr (mystring, ==, "fubar");
 430 </programlisting></informalexample>
 431
 432 @s1: a string (may be %NULL)
 433 @cmp: The comparsion operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 434 @s2: another string (may be %NULL)
 435 Since: 2.16
 436
 437
 438 <!-- ##### MACRO g_assert_cmpint ##### -->
 439 <para>
 440 Debugging macro to terminate the application with a warning message
 441 if an integer comparison fails.
 442 </para>
 443 <para>
 444 The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is the same
 445 as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
 446 is that it can produce a message that includes the actual values of @n1
 447 and @n2.
 448 </para>
 449
 450 @n1: an integer
 451 @cmp: The comparsion operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 452 @n2: another integer
 453 Since: 2.16
 454
 455
 456 <!-- ##### MACRO g_assert_cmpuint ##### -->
 457 <para>
 458 Debugging macro to terminate the application with a warning message
 459 if an unsigned integer comparison fails.
 460 </para>
 461 <para>
 462 The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is the same
 463 as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
 464 is that it can produce a message that includes the actual values of @n1
 465 and @n2.
 466 </para>
 467
 468 @n1: an unsigned integer
 469 @cmp: The comparsion operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 470 @n2: another unsigned integer
 471 Since: 2.16
 472
 473
 474 <!-- ##### MACRO g_assert_cmphex ##### -->
 475 <para>
 476 Debugging macro to terminate the application with a warning message
 477 if an unsigned integer comparison fails. This is a variant of
 478 g_assert_cmpuint() that displays the numbers in hexadecimal notation
 479 in the message.
 480 </para>
 481
 482 @n1: an unsigned integer
 483 @cmp: The comparsion operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 484 @n2: another unsigned integer
 485 Since: 2.16
 486
 487
 488 <!-- ##### MACRO g_assert_cmpfloat ##### -->
 489 <para>
 490 Debugging macro to terminate the application with a warning message
 491 if a floating point number comparison fails.
 492 </para>
 493 <para>
 494 The effect of <literal>g_assert_cmpflott (n1, op, n2)</literal> is the same
 495 as <literal>g_assert (n1 op n2)</literal>. The advantage of this function
 496 is that it can produce a message that includes the actual values of @n1
 497 and @n2.
 498 </para>
 499
 500 @n1: an floating point number
 501 @cmp: The comparsion operator to use. One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
 502 @n2: another floating point number
 503 Since: 2.16
 504
 505
 506 <!-- ##### FUNCTION g_strcmp0 ##### -->
 507 <para>
 508
 509 </para>
 510
 511 @str1:
 512 @str2:
 513 @Returns:
 514
 515
 516 <!-- ##### TYPEDEF GTestCase ##### -->
 517 <para>
 518 An opaque structure representing a test case.
 519 </para>
 520
 521
 522 <!-- ##### TYPEDEF GTestSuite ##### -->
 523 <para>
 524 An opaque structure representing a test suite.
 525 </para>
 526
 527
 528 <!-- ##### FUNCTION g_test_create_case ##### -->
 529 <para>
 530
 531 </para>
 532
 533 @test_name:
 534 @data_size:
 535 @test_data:
 536 @data_setup:
 537 @data_test:
 538 @data_teardown:
 539 @Returns:
 540
 541
 542 <!-- ##### FUNCTION g_test_create_suite ##### -->
 543 <para>
 544
 545 </para>
 546
 547 @suite_name:
 548 @Returns:
 549
 550
 551 <!-- ##### FUNCTION g_test_get_root ##### -->
 552 <para>
 553
 554 </para>
 555
 556 @Returns:
 557
 558
 559 <!-- ##### FUNCTION g_test_suite_add ##### -->
 560 <para>
 561
 562 </para>
 563
 564 @suite:
 565 @test_case:
 566
 567
 568 <!-- ##### FUNCTION g_test_suite_add_suite ##### -->
 569 <para>
 570
 571 </para>
 572
 573 @suite:
 574 @nestedsuite:
 575
 576
 577 <!-- ##### FUNCTION g_test_run_suite ##### -->
 578 <para>
 579
 580 </para>
 581
 582 @suite:
 583 @Returns:
 584
 585