Functions
g_test_minimized_result ()
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.
Since: 2.16
g_test_maximized_result ()
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.
Since: 2.16
g_test_init ()
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:
-l: List test cases available in a test executable.
--seed=SEED: Provide a random seed to reproduce test
runs using random numbers.
--verbose: Run tests verbosely.
-q, --quiet: Run tests quietly.
-p PATH: Execute all tests matching the given path.
-s PATH: Skip all tests matching the given path.
This can also be used to force a test to run that would otherwise
be skipped (ie, a test whose name contains "/subprocess").
-
-m {perf|slow|thorough|quick|undefined|no-undefined}: Execute tests according to these test modes:
perf: Performance tests, may take long and report results (off by default).
slow, thorough: Slow and thorough tests, may take quite long and maximize coverage
(off by default).
quick: Quick tests, should run really quickly and give good coverage (the default).
undefined: Tests for undefined behaviour, may provoke programming errors
under g_test_trap_subprocess() or g_test_expect_message() to check
that appropriate assertions or warnings are given (the default).
no-undefined: Avoid tests for undefined behaviour
--debug-log: Debug test logging output.
Options which can be passed to @... are:
Since 2.58, if tests are compiled with G_DISABLE_ASSERT defined,
g_test_init() will print an error and exit. This is to prevent no-op tests
from being executed, as g_assert() is commonly (erroneously) used in unit
tests, and is a no-op when compiled with G_DISABLE_ASSERT. Ensure your
tests are compiled without G_DISABLE_ASSERT defined.
Since: 2.16
g_test_initialized
#define g_test_initialized()
Returns TRUE if g_test_init() has been called.
Since: 2.36
g_test_quick
#define g_test_quick()
Returns TRUE if tests are run in quick mode.
Exactly one of g_test_quick() and g_test_slow() is active in any run;
there is no "medium speed".
By default, tests are run in quick mode. In tests that use
g_test_init(), the options -m quick, -m slow and -m thorough
can be used to change this.
Returns
TRUE if in quick mode
g_test_slow
#define g_test_slow()
Returns TRUE if tests are run in slow mode.
Exactly one of g_test_quick() and g_test_slow() is active in any run;
there is no "medium speed".
By default, tests are run in quick mode. In tests that use
g_test_init(), the options -m quick, -m slow and -m thorough
can be used to change this.
g_test_thorough
#define g_test_thorough()
Returns TRUE if tests are run in thorough mode, equivalent to
g_test_slow().
By default, tests are run in quick mode. In tests that use
g_test_init(), the options -m quick, -m slow and -m thorough
can be used to change this.
g_test_perf
#define g_test_perf()
Returns TRUE if tests are run in performance mode.
By default, tests are run in quick mode. In tests that use
g_test_init(), the option -m perf enables performance tests, while
-m quick disables them.
Returns
TRUE if in performance mode
g_test_verbose
#define g_test_verbose()
Returns TRUE if tests are run in verbose mode.
In tests that use g_test_init(), the option --verbose enables this,
while -q or --quiet disables it.
The default is neither g_test_verbose() nor g_test_quiet().
Returns
TRUE if in verbose mode
g_test_undefined
#define g_test_undefined()
Returns TRUE if tests may provoke assertions and other formally-undefined
behaviour, to verify that appropriate warnings are given. It might, in some
cases, be useful to turn this off with if running tests under valgrind;
in tests that use g_test_init(), the option -m no-undefined disables
those tests, while -m undefined explicitly enables them (the default
behaviour).
Returns
TRUE if tests may provoke programming errors
g_test_quiet
#define g_test_quiet()
Returns TRUE if tests are run in quiet mode.
In tests that use g_test_init(), the option -q or --quiet enables
this, while --verbose disables it.
The default is neither g_test_verbose() nor g_test_quiet().
Returns
TRUE if in quiet mode
g_test_run ()
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 and -s testpath) as parsed by g_test_init().
g_test_run_suite() or g_test_run() may only be called once in a
program.
In general, the tests and sub-suites within each suite are run in
the order in which they are defined. However, note that prior to
GLib 2.36, there was a bug in the g_test_add_*
functions which caused them to create multiple suites with the same
name, meaning that if you created tests "/foo/simple",
"/bar/simple", and "/foo/using-bar" in that order, they would get
run in that order (since g_test_run() would run the first "/foo"
suite, then the "/bar" suite, then the second "/foo" suite). As of
2.36, this bug is fixed, and adding the tests in that order would
result in a running order of "/foo/simple", "/foo/using-bar",
"/bar/simple". If this new ordering is sub-optimal (because it puts
more-complicated tests before simpler ones, making it harder to
figure out exactly what has failed), you can fix it by changing the
test paths to group tests by suite in a way that will result in the
desired running order. Eg, "/simple/foo", "/simple/bar",
"/complex/foo-using-bar".
However, you should never make the actual result of a test depend
on the order that tests are run in. If you need to ensure that some
particular code runs before or after a given test case, use
g_test_add(), which lets you specify setup and teardown functions.
If all tests are skipped or marked as incomplete (expected failures),
this function will return 0 if producing TAP output, or 77 (treated
as "skip test" by Automake) otherwise.
Since: 2.16
GTestFunc ()
void
(*GTestFunc) (void);
The type used for test case functions.
Since: 2.28
g_test_add_func ()
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
.
If testpath
includes the component "subprocess" anywhere in it,
the test will be skipped by default, and only run if explicitly
required via the -p command-line option or g_test_trap_subprocess().
No component of testpath
may start with a dot (.) if the
G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
do so even if it isn’t.
Since: 2.16
GTestDataFunc ()
void
(*GTestDataFunc) (gconstpointer user_data);
The type used for test case functions that take an extra pointer
argument.
Since: 2.28
g_test_add_data_func ()
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
.
If testpath
includes the component "subprocess" anywhere in it,
the test will be skipped by default, and only run if explicitly
required via the -p command-line option or g_test_trap_subprocess().
No component of testpath
may start with a dot (.) if the
G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
do so even if it isn’t.
Since: 2.16
g_test_add()
#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 functions may be provided,
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 their first argument
in a type safe manner. They otherwise have type GTestFixtureFunc.
Since: 2.16
g_test_build_filename ()
gchar *
g_test_build_filename (GTestFileType file_type,
const gchar *first_path,
...);
Creates the pathname to a data file that is required for a test.
This function is conceptually similar to g_build_filename() except
that the first argument has been replaced with a GTestFileType
argument.
The data file should either have been distributed with the module
containing the test (G_TEST_DIST) or built as part of the build
system of that module (G_TEST_BUILT).
In order for this function to work in srcdir != builddir situations,
the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to
have been defined. As of 2.38, this is done by the glib.mk
included in GLib. Please ensure that your copy is up to date before
using this function.
In case neither variable is set, this function will fall back to
using the dirname portion of argv[0], possibly removing ".libs".
This allows for casual running of tests directly from the commandline
in the srcdir == builddir case and should also support running of
installed tests, assuming the data files have been installed in the
same relative path as the test binary.
Returns
the path of the file, to be freed using g_free()
Since: 2.38
g_test_get_filename ()
const gchar *
g_test_get_filename (GTestFileType file_type,
const gchar *first_path,
...);
Gets the pathname to a data file that is required for a test.
This is the same as g_test_build_filename() with two differences.
The first difference is that must only use this function from within
a testcase function. The second difference is that you need not free
the return value -- it will be automatically freed when the testcase
finishes running.
It is safe to use this function from a thread inside of a testcase
but you must ensure that all such uses occur before the main testcase
function returns (ie: it is best to ensure that all threads have been
joined).
Returns
the path, automatically freed at the end of the testcase
Since: 2.38
g_test_get_dir ()
const gchar *
g_test_get_dir (GTestFileType file_type);
Gets the pathname of the directory containing test files of the type
specified by file_type
.
This is approximately the same as calling g_test_build_filename("."),
but you don't need to free the return value.
Returns
the path of the directory, owned by GLib.
[type filename]
Since: 2.38
g_test_fail ()
void
g_test_fail (void);
Indicates that a test failed. This function can be called
multiple times from the same test. You can use this function
if your test failed in a recoverable way.
Do not use this function if the failure of a test could cause
other tests to malfunction.
Calling this function will not stop the test from running, you
need to return from the test function yourself. So you can
produce additional diagnostic messages or even continue running
the test.
If not called from inside a test, this function does nothing.
Since: 2.30
g_test_skip ()
void
g_test_skip (const gchar *msg);
Indicates that a test was skipped.
Calling this function will not stop the test from running, you
need to return from the test function yourself. So you can
produce additional diagnostic messages or even continue running
the test.
If not called from inside a test, this function does nothing.
Since: 2.38
g_test_incomplete ()
void
g_test_incomplete (const gchar *msg);
Indicates that a test failed because of some incomplete
functionality. This function can be called multiple times
from the same test.
Calling this function will not stop the test from running, you
need to return from the test function yourself. So you can
produce additional diagnostic messages or even continue running
the test.
If not called from inside a test, this function does nothing.
Since: 2.38
g_test_failed ()
gboolean
g_test_failed (void);
Returns whether a test has already failed. This will
be the case when g_test_fail(), g_test_incomplete()
or g_test_skip() have been called, but also if an
assertion has failed.
This can be useful to return early from a test if
continuing after a failed assertion might be harmful.
The return value of this function is only meaningful
if it is called from inside a test function.
Returns
TRUE if the test has failed
Since: 2.38
g_test_message ()
void
g_test_message (const char *format,
...);
Add a message to the test report.
Since: 2.16
g_test_bug_base ()
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.
If g_test_bug_base() is not called, bug URIs are formed solely
from the value provided by g_test_bug().
Since: 2.16
g_test_bug ()
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
. If g_test_bug_base() has not been called, it is
assumed to be the empty string, so a full URI can be provided to
g_test_bug() instead.
Since: 2.16
g_test_summary ()
void
g_test_summary (const char *summary);
Set the summary for a test, which describes what the test checks, and how it
goes about checking it. This may be included in test report output, and is
useful documentation for anyone reading the source code or modifying a test
in future. It must be a single line.
This should be called at the top of a test function.
For example:
Since: 2.62
GTestLogFatalFunc ()
gboolean
(*GTestLogFatalFunc) (const gchar *log_domain,
GLogLevelFlags log_level,
const gchar *message,
gpointer user_data);
Specifies the prototype of fatal log handler functions.
Returns
TRUE if the program should abort, FALSE otherwise
Since: 2.22
g_test_log_set_fatal_handler ()
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.
This handler also has no effect on structured log messages (using
g_log_structured() or g_log_structured_array()). To change the fatal
behaviour for specific log messages, programs must install a custom log
writer function using g_log_set_writer_func().See
Using Structured Logging.
Since: 2.22
g_test_timer_start ()
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
g_test_timer_elapsed ()
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
g_test_queue_free ()
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().
Since: 2.16
g_test_queue_destroy ()
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 allocated 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.
Since: 2.16
g_test_queue_unref()
#define g_test_queue_unref(gobject)
Enqueue an object to be released with g_object_unref() during
the next teardown phase. This is equivalent to calling
g_test_queue_destroy() with a destroy callback of g_object_unref().
Since: 2.16
g_test_expect_message ()
void
g_test_expect_message (const gchar *log_domain,
GLogLevelFlags log_level,
const gchar *pattern);
Indicates that a message with the given log_domain
and log_level
,
with text matching pattern
, is expected to be logged. When this
message is logged, it will not be printed, and the test case will
not abort.
This API may only be used with the old logging API (g_log() without
G_LOG_USE_STRUCTURED defined). It will not work with the structured logging
API. See Testing for Messages.
Use g_test_assert_expected_messages() to assert that all
previously-expected messages have been seen and suppressed.
You can call this multiple times in a row, if multiple messages are
expected as a result of a single call. (The messages must appear in
the same order as the calls to g_test_expect_message().)
For example:
Note that you cannot use this to test g_error() messages, since
g_error() intentionally never returns even if the program doesn't
abort; use g_test_trap_subprocess() in this case.
If messages at G_LOG_LEVEL_DEBUG are emitted, but not explicitly
expected via g_test_expect_message() then they will be ignored.
Since: 2.34
g_test_assert_expected_messages
#define g_test_assert_expected_messages()
Asserts that all messages previously indicated via
g_test_expect_message() have been seen and suppressed.
This API may only be used with the old logging API (g_log() without
G_LOG_USE_STRUCTURED defined). It will not work with the structured logging
API. See Testing for Messages.
If messages at G_LOG_LEVEL_DEBUG are emitted, but not explicitly
expected via g_test_expect_message() then they will be ignored.
Since: 2.34
g_test_trap_subprocess ()
void
g_test_trap_subprocess (const char *test_path,
guint64 usec_timeout,
GTestSubprocessFlags test_flags);
Respawns the test program to run only test_path
in a subprocess.
This can be used for a test case that might not return, or that
might abort.
If test_path
is NULL then the same test is re-run in a subprocess.
You can use g_test_subprocess() to determine whether the test is in
a subprocess or not.
test_path
can also be the name of the parent test, followed by
"/subprocess/" and then a name for the specific subtest (or just
ending with "/subprocess" if the test only has one child test);
tests with names of this form will automatically be skipped in the
parent process.
If usec_timeout
is non-0, the test subprocess is aborted and
considered failing if its run time exceeds it.
The subprocess behavior can be configured with the
GTestSubprocessFlags flags.
You can use methods such as g_test_trap_assert_passed(),
g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to
check the results of the subprocess. (But note that
g_test_trap_assert_stdout() and g_test_trap_assert_stderr()
cannot be used if test_flags
specifies that the child should
inherit the parent stdout/stderr.)
If your main() needs to behave differently in
the subprocess, you can call g_test_subprocess() (after calling
g_test_init()) to see whether you are in a subprocess.
The following example tests that calling
my_object_new(1000000) will abort with an error
message.
Since: 2.38
g_test_trap_has_passed ()
gboolean
g_test_trap_has_passed (void);
Check the result of the last g_test_trap_subprocess() call.
Returns
TRUE if the last test subprocess terminated successfully.
Since: 2.16
g_test_trap_reached_timeout ()
gboolean
g_test_trap_reached_timeout (void);
Check the result of the last g_test_trap_subprocess() call.
Returns
TRUE if the last test subprocess got killed due to a timeout.
Since: 2.16
g_test_trap_assert_passed
#define g_test_trap_assert_passed()
Assert that the last test subprocess passed.
See g_test_trap_subprocess().
Since: 2.16
g_test_trap_assert_failed
#define g_test_trap_assert_failed()
Assert that the last test subprocess failed.
See g_test_trap_subprocess().
This is sometimes used to test situations that are formally considered to
be undefined behaviour, like inputs that fail a g_return_if_fail()
check. In these situations you should skip the entire test, including the
call to g_test_trap_subprocess(), unless g_test_undefined() returns TRUE
to indicate that undefined behaviour may be tested.
Since: 2.16
g_test_trap_assert_stdout()
#define g_test_trap_assert_stdout(soutpattern)
Assert that the stdout output of the last test subprocess matches
soutpattern
. See g_test_trap_subprocess().
Since: 2.16
g_test_trap_assert_stdout_unmatched()
#define g_test_trap_assert_stdout_unmatched(soutpattern)
Assert that the stdout output of the last test subprocess
does not match soutpattern
. See g_test_trap_subprocess().
Since: 2.16
g_test_trap_assert_stderr()
#define g_test_trap_assert_stderr(serrpattern)
Assert that the stderr output of the last test subprocess
matches serrpattern
. See g_test_trap_subprocess().
This is sometimes used to test situations that are formally
considered to be undefined behaviour, like code that hits a
g_assert() or g_error(). In these situations you should skip the
entire test, including the call to g_test_trap_subprocess(), unless
g_test_undefined() returns TRUE to indicate that undefined
behaviour may be tested.
Since: 2.16
g_test_trap_assert_stderr_unmatched()
#define g_test_trap_assert_stderr_unmatched(serrpattern)
Assert that the stderr output of the last test subprocess
does not match serrpattern
. See g_test_trap_subprocess().
Since: 2.16
g_test_trap_fork ()
gboolean
g_test_trap_fork (guint64 usec_timeout,
GTestTrapFlags test_trap_flags);
g_test_trap_fork is deprecated and should not be used in newly-written code.
This function is implemented only on Unix platforms,
and is not always reliable due to problems inherent in
fork-without-exec. Use g_test_trap_subprocess() instead.
Fork the current test program to execute a test case that might
not return or that might abort.
If usec_timeout
is non-0, the forked test case is aborted and
considered failing if its run time exceeds it.
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.
Returns
TRUE for the forked child and FALSE for the executing parent process.
Since: 2.16
g_test_rand_bit
#define g_test_rand_bit()
Get a reproducible random bit (0 or 1), see g_test_rand_int()
for details on test case random numbers.
Since: 2.16
g_test_rand_int ()
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
g_test_rand_int_range ()
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.
Returns
a number with begin
<= number < end
.
Since: 2.16
g_test_rand_double ()
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
g_test_rand_double_range ()
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.
Returns
a number with range_start
<= number < range_end
.
Since: 2.16
g_assert()
#define g_assert(expr)
Debugging macro to terminate the application if the assertion
fails. If the assertion fails (i.e. the expression is not true),
an error message is logged and the application is terminated.
The macro can be turned off in final releases of code by defining
G_DISABLE_ASSERT when compiling the application, so code must
not depend on any side effects from expr
. Similarly, it must not be used
in unit tests, otherwise the unit tests will be ineffective if compiled with
G_DISABLE_ASSERT. Use g_assert_true() and related macros in unit tests
instead.
g_assert_not_reached
#define g_assert_not_reached()
Debugging macro to terminate the application if it is ever
reached. If it is reached, an error message is logged and the
application is terminated.
The macro can be turned off in final releases of code by defining
G_DISABLE_ASSERT when compiling the application. Hence, it should not be
used in unit tests, where assertions should always be effective.
g_assert_cmpstr()
#define g_assert_cmpstr(s1, cmp, s2)
Debugging macro to compare two strings. If the comparison fails,
an error message is logged and the application is either terminated
or the testcase marked as failed.
The strings are compared using g_strcmp0().
The effect of g_assert_cmpstr (s1, op, s2) is
the same as g_assert_true (g_strcmp0 (s1, s2) op 0).
The advantage of this macro is that it can produce a message that
includes the actual values of s1
and s2
.
Since: 2.16
g_assert_cmpint()
#define g_assert_cmpint(n1, cmp, n2)
Debugging macro to compare two integers.
The effect of g_assert_cmpint (n1, op, n2) is
the same as g_assert_true (n1 op n2). The advantage
of this macro is that it can produce a message that includes the
actual values of n1
and n2
.
Since: 2.16
g_assert_cmpuint()
#define g_assert_cmpuint(n1, cmp, n2)
Debugging macro to compare two unsigned integers.
The effect of g_assert_cmpuint (n1, op, n2) is
the same as g_assert_true (n1 op n2). The advantage
of this macro is that it can produce a message that includes the
actual values of n1
and n2
.
Since: 2.16
g_assert_cmphex()
#define g_assert_cmphex(n1, cmp, n2)
Debugging macro to compare to unsigned integers.
This is a variant of g_assert_cmpuint() that displays the numbers
in hexadecimal notation in the message.
Since: 2.16
g_assert_cmpfloat()
#define g_assert_cmpfloat(n1,cmp,n2)
Debugging macro to compare two floating point numbers.
The effect of g_assert_cmpfloat (n1, op, n2) is
the same as g_assert_true (n1 op n2). The advantage
of this macro is that it can produce a message that includes the
actual values of n1
and n2
.
Since: 2.16
g_assert_cmpfloat_with_epsilon()
#define g_assert_cmpfloat_with_epsilon(n1,n2,epsilon)
Debugging macro to compare two floating point numbers within an epsilon.
The effect of g_assert_cmpfloat_with_epsilon (n1, n2, epsilon) is
the same as g_assert_true (abs (n1 - n2) < epsilon). The advantage
of this macro is that it can produce a message that includes the
actual values of n1
and n2
.
Since: 2.58
g_assert_cmpmem()
#define g_assert_cmpmem(m1, l1, m2, l2)
Debugging macro to compare memory regions. If the comparison fails,
an error message is logged and the application is either terminated
or the testcase marked as failed.
The effect of g_assert_cmpmem (m1, l1, m2, l2) is
the same as g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0).
The advantage of this macro is that it can produce a message that
includes the actual values of l1
and l2
.
m1
may be NULL if (and only if) l1
is zero; similarly for m2
and l2
.
Since: 2.46
g_assert_cmpvariant()
#define g_assert_cmpvariant(v1, v2)
Debugging macro to compare two GVariants. If the comparison fails,
an error message is logged and the application is either terminated
or the testcase marked as failed. The variants are compared using
g_variant_equal().
The effect of g_assert_cmpvariant (v1, v2) is the same as
g_assert_true (g_variant_equal (v1, v2)). The advantage of this macro is
that it can produce a message that includes the actual values of v1
and v2
.
Since: 2.60
g_assert_no_error()
#define g_assert_no_error(err)
Debugging macro to check that a GError is not set.
The effect of g_assert_no_error (err) is
the same as g_assert_true (err == NULL). The advantage
of this macro is that it can produce a message that includes
the error message and code.
Since: 2.20
g_assert_error()
#define g_assert_error(err, dom, c)
Debugging macro to check that a method has returned
the correct GError.
The effect of g_assert_error (err, dom, c) is
the same as g_assert_true (err != NULL && err->domain
== dom && err->code == c). The advantage of this
macro is that it can produce a message that includes the incorrect
error message and code.
This can only be used to test for a specific error. If you want to
test that err
is set, but don't care what it's set to, just use
g_assert_nonnull (err).
Since: 2.20
g_assert_true()
#define g_assert_true(expr)
Debugging macro to check that an expression is true.
If the assertion fails (i.e. the expression is not true),
an error message is logged and the application is either
terminated or the testcase marked as failed.
Note that unlike g_assert(), this macro is unaffected by whether
G_DISABLE_ASSERT is defined. Hence it should only be used in tests and,
conversely, g_assert() should not be used in tests.
See g_test_set_nonfatal_assertions().
Since: 2.38
g_assert_false()
#define g_assert_false(expr)
Debugging macro to check an expression is false.
If the assertion fails (i.e. the expression is not false),
an error message is logged and the application is either
terminated or the testcase marked as failed.
Note that unlike g_assert(), this macro is unaffected by whether
G_DISABLE_ASSERT is defined. Hence it should only be used in tests and,
conversely, g_assert() should not be used in tests.
See g_test_set_nonfatal_assertions().
Since: 2.38
g_assert_null()
#define g_assert_null(expr)
Debugging macro to check an expression is NULL.
If the assertion fails (i.e. the expression is not NULL),
an error message is logged and the application is either
terminated or the testcase marked as failed.
Note that unlike g_assert(), this macro is unaffected by whether
G_DISABLE_ASSERT is defined. Hence it should only be used in tests and,
conversely, g_assert() should not be used in tests.
See g_test_set_nonfatal_assertions().
Since: 2.38
g_assert_nonnull()
#define g_assert_nonnull(expr)
Debugging macro to check an expression is not NULL.
If the assertion fails (i.e. the expression is NULL),
an error message is logged and the application is either
terminated or the testcase marked as failed.
Note that unlike g_assert(), this macro is unaffected by whether
G_DISABLE_ASSERT is defined. Hence it should only be used in tests and,
conversely, g_assert() should not be used in tests.
See g_test_set_nonfatal_assertions().
Since: 2.40
g_test_set_nonfatal_assertions ()
void
g_test_set_nonfatal_assertions (void);
Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(),
g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(),
g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(),
g_assert_error(), g_test_assert_expected_messages() and the various
g_test_trap_assert_*() macros to not abort to program, but instead
call g_test_fail() and continue. (This also changes the behavior of
g_test_fail() so that it will not cause the test program to abort
after completing the failed test.)
Note that the g_assert_not_reached() and g_assert() are not
affected by this.
This function can only be called after g_test_init().
Since: 2.38
GTestFixtureFunc ()
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
.
Since: 2.28
g_test_create_case ()
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 automatically allocated and filled with zeros. Then data_setup
is
called to initialize the fixture. After fixture setup, the actual test
function data_test
is called. Once the test run completes, the
fixture structure is torn down by calling data_teardown
and
after that the memory is automatically released by the test framework.
Splitting up a test run into fixture setup, test function and
fixture teardown is most useful 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.
Since: 2.16
g_test_create_suite ()
GTestSuite *
g_test_create_suite (const char *suite_name);
Create a new test suite with the name suite_name
.
Since: 2.16
g_test_get_root ()
GTestSuite *
g_test_get_root (void);
Get the toplevel test suite for the test path API.
Since: 2.16
g_test_suite_add ()
void
g_test_suite_add (GTestSuite *suite,
GTestCase *test_case);
Adds test_case
to suite
.
Since: 2.16
g_test_suite_add_suite ()
void
g_test_suite_add_suite (GTestSuite *suite,
GTestSuite *nestedsuite);
Adds nestedsuite
to suite
.
Since: 2.16
g_test_run_suite ()
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 and -s testpath) as parsed by
g_test_init(). See the g_test_run() documentation for more
information on the order that tests are run in.
g_test_run_suite() or g_test_run() may only be called once
in a program.
Since: 2.16