![]() |
![]() |
![]() |
GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <glib.h> void g_test_minimized_result (double minimized_quantity, const char *format, ...); void g_test_maximized_result (double maximized_quantity, const char *format, ...); void g_test_init (int *argc, char ***argv, ...); #define g_test_quick () #define g_test_slow () #define g_test_thorough () #define g_test_perf () #define g_test_verbose () #define g_test_quiet () int g_test_run (void); void (*GTestFunc) (void); void g_test_add_func (const char *testpath, GTestFunc test_func); void (*GTestDataFunc) (gconstpointer user_data); void g_test_add_data_func (const char *testpath, gconstpointer test_data, GTestDataFunc test_func); #define g_test_add (testpath, Fixture, tdata, fsetup, ftest, fteardown) void g_test_message (const char *format, ...); void g_test_bug_base (const char *uri_pattern); void g_test_bug (const char *bug_uri_snippet); gboolean (*GTestLogFatalFunc) (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer user_data); void g_test_log_set_fatal_handler (GTestLogFatalFunc log_func, gpointer user_data); void g_test_timer_start (void); double g_test_timer_elapsed (void); double g_test_timer_last (void); void g_test_queue_free (gpointer gfree_pointer); void g_test_queue_destroy (GDestroyNotify destroy_func, gpointer destroy_data); #define g_test_queue_unref (gobject) enum GTestTrapFlags; gboolean g_test_trap_fork (guint64 usec_timeout, GTestTrapFlags test_trap_flags); gboolean g_test_trap_has_passed (void); gboolean g_test_trap_reached_timeout (void); #define g_test_trap_assert_passed () #define g_test_trap_assert_failed () #define g_test_trap_assert_stdout (soutpattern) #define g_test_trap_assert_stdout_unmatched (soutpattern) #define g_test_trap_assert_stderr (serrpattern) #define g_test_trap_assert_stderr_unmatched (serrpattern) #define g_test_rand_bit () gint32 g_test_rand_int (void); gint32 g_test_rand_int_range (gint32 begin, gint32 end); double g_test_rand_double (void); double g_test_rand_double_range (double range_start, double range_end); #define g_assert (expr) #define g_assert_not_reached () #define g_assert_cmpstr (s1, cmp, s2) #define g_assert_cmpint (n1, cmp, n2) #define g_assert_cmpuint (n1, cmp, n2) #define g_assert_cmphex (n1, cmp, n2) #define g_assert_cmpfloat (n1,cmp,n2) #define g_assert_no_error (err) #define g_assert_error (err, dom, c) typedef GTestCase; typedef GTestSuite; void (*GTestFixtureFunc) (gpointer fixture, gconstpointer user_data); GTestCase* g_test_create_case (const char *test_name, gsize data_size, gconstpointer test_data, GTestFixtureFunc data_setup, GTestFixtureFunc data_test, GTestFixtureFunc data_teardown); GTestSuite* g_test_create_suite (const char *suite_name); GTestSuite* g_test_get_root (void); void g_test_suite_add (GTestSuite *suite, GTestCase *test_case); void g_test_suite_add_suite (GTestSuite *suite, GTestSuite *nestedsuite); int g_test_run_suite (GTestSuite *suite);
void g_test_minimized_result (double minimized_quantity, const char *format, ...);
Report the result of a performance or measurement test.
The test should generally strive to minimize the reported
quantities (smaller values are better than larger ones),
this and minimized_quantity
can determine sorting
order for test result reports.
|
the reported value |
|
the format string of the report message |
|
arguments to pass to the printf() function
|
Since 2.16
void g_test_maximized_result (double maximized_quantity, const char *format, ...);
Report the result of a performance or measurement test.
The test should generally strive to maximize the reported
quantities (larger values are better than smaller ones),
this and maximized_quantity
can determine sorting
order for test result reports.
|
the reported value |
|
the format string of the report message |
|
arguments to pass to the printf() function
|
Since 2.16
void g_test_init (int *argc, char ***argv, ...);
Initialize the GLib testing framework, e.g. by seeding the
test random number generator, the name for g_get_prgname()
and parsing test related command line args.
So far, the following arguments are understood:
|
list test cases available in a test executable. |
||||||
|
provide a random seed to reproduce test runs using random numbers. |
||||||
|
run tests verbosely. |
||||||
|
run tests quietly. |
||||||
|
execute all tests matching |
||||||
|
execute tests according to these test modes:
|
||||||
|
debug test logging output. |
||||||
|
gtester-specific argument. |
||||||
|
gtester-specific argument. |
||||||
|
gtester-specific argument. |
|
Address of the argc parameter of the main() function.
Changed if any arguments were handled.
|
|
Address of the argv parameter of main() .
Any parameters understood by g_test_init() stripped before return.
|
|
Reserved for future extension. Currently, you must pass NULL .
|
Since 2.16
int g_test_run (void);
Runs all tests under the toplevel suite which can be retrieved
with g_test_get_root()
. Similar to g_test_run_suite()
, the test
cases to be run are filtered according to
test path arguments (-p testpath
) as
parsed by g_test_init()
.
g_test_run_suite()
or g_test_run()
may only be called once
in a program.
Returns : |
0 on success |
Since 2.16
void g_test_add_func (const char *testpath, GTestFunc test_func);
Create a new test case, similar to g_test_create_case()
. However
the test is assumed to use no fixture, and test suites are automatically
created on the fly and added to the root fixture, based on the
slash-separated portions of testpath
.
|
Slash-separated test case path name for the test. |
|
The test function to invoke for this test. |
Since 2.16
void (*GTestDataFunc) (gconstpointer user_data);
The type used for test case functions that take an extra pointer argument.
|
the data provided when registering the test |
void g_test_add_data_func (const char *testpath, gconstpointer test_data, GTestDataFunc test_func);
Create a new test case, similar to g_test_create_case()
. However
the test is assumed to use no fixture, and test suites are automatically
created on the fly and added to the root fixture, based on the
slash-separated portions of testpath
. The test_data
argument
will be passed as first argument to test_func
.
|
Slash-separated test case path name for the test. |
|
Test data argument for the test function. |
|
The test function to invoke for this test. |
Since 2.16
#define g_test_add(testpath, Fixture, tdata, fsetup, ftest, fteardown)
Hook up a new test case at testpath
, similar to g_test_add_func()
.
A fixture data structure with setup and teardown function may be provided
though, similar to g_test_create_case()
.
g_test_add()
is implemented as a macro, so that the fsetup()
, ftest()
and
fteardown()
callbacks can expect a Fixture
pointer as first argument in
a type safe manner.
|
The test path for a new test case. |
|
The type of a fixture data structure. |
|
Data argument for the test functions. |
|
The function to set up the fixture data. |
|
The actual test function. |
|
The function to tear down the fixture data. |
Since 2.16
void g_test_message (const char *format, ...);
Add a message to the test report.
|
the format string |
|
printf-like arguments to format
|
Since 2.16
void g_test_bug_base (const char *uri_pattern);
Specify the base URI for bug reports.
The base URI is used to construct bug report messages for
g_test_message()
when g_test_bug()
is called.
Calling this function outside of a test case sets the
default base URI for all test cases. Calling it from within
a test case changes the base URI for the scope of the test
case only.
Bug URIs are constructed by appending a bug specific URI
portion to uri_pattern
, or by replacing the special string
's
' within uri_pattern
if that is present.
|
the base pattern for bug URIs |
Since 2.16
void g_test_bug (const char *bug_uri_snippet);
This function adds a message to test reports that
associates a bug URI with a test case.
Bug URIs are constructed from a base URI set with g_test_bug_base()
and bug_uri_snippet
.
|
Bug specific bug tracker URI portion. |
Since 2.16
gboolean (*GTestLogFatalFunc) (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer user_data);
Specifies the prototype of fatal log handler functions.
|
the log domain of the message |
|
the log level of the message (including the fatal and recursion flags) |
|
the message to process |
|
user data, set in g_test_log_set_fatal_handler()
|
Returns : |
TRUE if the program should abort, FALSE otherwise
|
Since 2.22
void g_test_log_set_fatal_handler (GTestLogFatalFunc log_func, gpointer user_data);
Installs a non-error fatal log handler which can be used to decide whether log messages which are counted as fatal abort the program.
The use case here is that you are running a test case that depends on particular libraries or circumstances and cannot prevent certain known critical or warning messages. So you install a handler that compares the domain and message to precisely not abort in such a case.
Note that the handler is reset at the beginning of any test case, so you have to set it inside each test function which needs the special behavior.
This handler has no effect on g_error messages.
|
the log handler function. |
|
data passed to the log handler. |
Since 2.22
void g_test_timer_start (void);
Start a timing test. Call g_test_timer_elapsed()
when the task is supposed
to be done. Call this function again to restart the timer.
Since 2.16
double g_test_timer_elapsed (void);
Get the time since the last start of the timer with g_test_timer_start()
.
Returns : |
the time since the last start of the timer, as a double |
Since 2.16
double g_test_timer_last (void);
Report the last result of g_test_timer_elapsed()
.
Returns : |
the last result of g_test_timer_elapsed() , as a double
|
Since 2.16
void g_test_queue_free (gpointer gfree_pointer);
Enqueue a pointer to be released with g_free()
during the next
teardown phase. This is equivalent to calling g_test_queue_destroy()
with a destroy callback of g_free()
.
|
the pointer to be stored. |
Since 2.16
void g_test_queue_destroy (GDestroyNotify destroy_func, gpointer destroy_data);
This function enqueus a callback @destroy_func()
to be executed
during the next test case teardown phase. This is most useful
to auto destruct allocted test resources at the end of a test run.
Resources are released in reverse queue order, that means enqueueing
callback A before callback B will cause B()
to be called before
A()
during teardown.
|
Destroy callback for teardown phase. |
|
Destroy callback data. |
Since 2.16
typedef enum { G_TEST_TRAP_SILENCE_STDOUT = 1 << 7, G_TEST_TRAP_SILENCE_STDERR = 1 << 8, G_TEST_TRAP_INHERIT_STDIN = 1 << 9 } GTestTrapFlags;
gboolean g_test_trap_fork (guint64 usec_timeout, GTestTrapFlags test_trap_flags);
Fork the current test program to execute a test case that might
not return or that might abort. The forked test case is aborted
and considered failing if its run time exceeds usec_timeout
.
The forking behavior can be configured with the GTestTrapFlags flags.
In the following example, the test code forks, the forked child process produces some sample output and exits successfully. The forking parent process then asserts successful child program termination and validates child program outputs.
static void test_fork_patterns (void) { if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) { g_print ("some stdout text: somagic17\n"); g_printerr ("some stderr text: semagic43\n"); exit (0); /* successful test run */ } g_test_trap_assert_passed(); g_test_trap_assert_stdout ("*somagic17*"); g_test_trap_assert_stderr ("*semagic43*"); }
This function is implemented only on Unix platforms.
|
Timeout for the forked test in micro seconds. |
|
Flags to modify forking behaviour. |
Returns : |
TRUE for the forked child and FALSE for the executing parent process.
|
Since 2.16
gboolean g_test_trap_has_passed (void);
Check the result of the last g_test_trap_fork()
call.
Returns : |
TRUE if the last forked child terminated successfully.
|
Since 2.16
gboolean g_test_trap_reached_timeout (void);
Check the result of the last g_test_trap_fork()
call.
Returns : |
TRUE if the last forked child got killed due to a fork timeout.
|
Since 2.16
#define g_test_trap_assert_stdout_unmatched(soutpattern)
|
#define g_test_trap_assert_stderr_unmatched(serrpattern)
|
gint32 g_test_rand_int (void);
Get a reproducible random integer number.
The random numbers generated by the g_test_rand_*() family of functions change with every new test program start, unless the --seed option is given when starting test programs.
For individual test cases however, the random number generator is reseeded, to avoid dependencies between tests and to make --seed effective for all test cases.
Returns : |
a random number from the seeded random number generator. |
Since 2.16
gint32 g_test_rand_int_range (gint32 begin, gint32 end);
Get a reproducible random integer number out of a specified range,
see g_test_rand_int()
for details on test case random numbers.
|
the minimum value returned by this function |
|
the smallest value not to be returned by this function |
Returns : |
a number with begin <= number < end .
|
Since 2.16
double g_test_rand_double (void);
Get a reproducible random floating point number,
see g_test_rand_int()
for details on test case random numbers.
Returns : |
a random number from the seeded random number generator. |
Since 2.16
double g_test_rand_double_range (double range_start, double range_end);
Get a reproducible random floating pointer number out of a specified range,
see g_test_rand_int()
for details on test case random numbers.
|
the minimum value returned by this function |
|
the minimum value not returned by this function |
Returns : |
a number with range_start <= number < range_end .
|
Since 2.16
void (*GTestFixtureFunc) (gpointer fixture, gconstpointer user_data);
The type used for functions that operate on test fixtures. This is used for the fixture setup and teardown functions as well as for the testcases themselves.
user_data
is a pointer to the data that was given when registering
the test case.
fixture
will be a pointer to the area of memory allocated by the
test framework, of the size requested. If the requested size was
zero then fixture
will be equal to user_data
.
|
the test fixture |
|
the data provided when registering the test |
GTestCase* g_test_create_case (const char *test_name, gsize data_size, gconstpointer test_data, GTestFixtureFunc data_setup, GTestFixtureFunc data_test, GTestFixtureFunc data_teardown);
Create a new GTestCase, named test_name
, this API is fairly
low level, calling g_test_add()
or g_test_add_func()
is preferable.
When this test is executed, a fixture structure of size data_size
will be allocated and filled with 0s. Then data_setup()
is called
to initialize the fixture. After fixture setup, the actual test
function data_test()
is called. Once the test run completed, the
fixture structure is torn down by calling data_teardown()
and
after that the memory is released.
Splitting up a test run into fixture setup, test function and
fixture teardown is most usful if the same fixture is used for
multiple tests. In this cases, g_test_create_case()
will be
called with the same fixture, but varying test_name
and
data_test
arguments.
|
the name for the test case |
|
the size of the fixture data structure |
|
test data argument for the test functions |
|
the function to set up the fixture data |
|
the actual test function |
|
the function to teardown the fixture data |
Returns : |
a newly allocated GTestCase. |
Since 2.16
GTestSuite* g_test_create_suite (const char *suite_name);
Create a new test suite with the name suite_name
.
|
a name for the suite |
Returns : |
A newly allocated GTestSuite instance. |
Since 2.16
GTestSuite* g_test_get_root (void);
Get the toplevel test suite for the test path API.
Returns : |
the toplevel GTestSuite |
Since 2.16
void g_test_suite_add (GTestSuite *suite, GTestCase *test_case);
Adds test_case
to suite
.
|
a GTestSuite |
|
a GTestCase |
Since 2.16
void g_test_suite_add_suite (GTestSuite *suite, GTestSuite *nestedsuite);
Adds nestedsuite
to suite
.
|
a GTestSuite |
|
another GTestSuite |
Since 2.16
int g_test_run_suite (GTestSuite *suite);
Execute the tests within suite
and all nested GTestSuites.
The test suites to be executed are filtered according to
test path arguments (-p testpath
)
as parsed by g_test_init()
.
g_test_run_suite()
or g_test_run()
may only be called once
in a program.
|
a GTestSuite |
Returns : |
0 on success |
Since 2.16