558 lines
16 KiB
C
558 lines
16 KiB
C
/* PipeWire */
|
|
/* SPDX-FileCopyrightText: Copyright © 2021 Red Hat, Inc. */
|
|
/* SPDX-License-Identifier: MIT */
|
|
|
|
#include "config.h"
|
|
|
|
#ifndef PWTEST_H
|
|
#define PWTEST_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#include <limits.h>
|
|
#include <stddef.h>
|
|
#include <stdbool.h>
|
|
#include <math.h>
|
|
|
|
#include <spa/utils/string.h>
|
|
#include <spa/utils/dict.h>
|
|
#include "spa/support/plugin.h"
|
|
|
|
/**
|
|
* \defgroup pwtest Test Suite
|
|
* \brief `pwtest` is a test runner framework for PipeWire.
|
|
*
|
|
* It's modelled after other
|
|
* test suites like [check](https://libcheck.github.io/check/)
|
|
* and draws a lot of inspiration from the [libinput test
|
|
* suite](https://wayland.freedesktop.org/libinput/doc/latest/).
|
|
*
|
|
* `pwtest` captures logs from the tests (and the pipewire daemon, if
|
|
* applicable) and collects the output into YAML files printed to `stderr`.
|
|
*
|
|
* ## Tests
|
|
*
|
|
* A `pwtest` test is declared with the `PWTEST()` macro and must return one of
|
|
* the `pwtest` status codes. Those codes are:
|
|
* - \ref PWTEST_PASS for a successful test
|
|
* - \ref PWTEST_FAIL for a test case failure. Usually you should not return this
|
|
* value but rely on the `pwtest` macros to handle this case.
|
|
* - \ref PWTEST_SKIP to skip the current test
|
|
* - \ref PWTEST_SYSTEM_ERROR in case of an error that would cause the test to not run properly. This is not a test case failure but some required precondition not being met.
|
|
*
|
|
* ```c
|
|
* #include "pwtest.h"
|
|
*
|
|
* PWTEST(some_test)
|
|
* {
|
|
* int var = 10;
|
|
* const char *str = "foo";
|
|
*
|
|
* if (access("/", R_OK))
|
|
* pwtest_error_with_message("Oh dear, no root directory?");
|
|
*
|
|
* if (today_is_monday)
|
|
* return PWTEST_SKIP;
|
|
*
|
|
* pwtest_int_lt(var, 20);
|
|
* pwtest_ptr_notnull(&var);
|
|
* pwtest_str_ne(str, "bar");
|
|
*
|
|
* return PWTEST_PASS;
|
|
* }
|
|
* ...
|
|
* ```
|
|
*
|
|
* `pwtest` provides comparison macros for most basic data types with the `lt`,
|
|
* `le`, `eq`, `gt`, `ge` suffixes (`<, <=, ==, >, >=`). Tests usually should not
|
|
* return `PWTEST_FAIL` directly, use the `pwtest_fail()` macros if .
|
|
*
|
|
* By default, a test runs in a forked process, any changes to the
|
|
* process'environment, etc. are discarded in the next test.
|
|
*
|
|
* ## Suites
|
|
*
|
|
* Tests are grouped into suites and declared with the PWTEST_SUITE() macro.
|
|
* Each test must be added with the required arguments, it is acceptable to
|
|
* add the same test multiple times with different arguments.
|
|
*
|
|
* ```c
|
|
* ...
|
|
* PWTEST_SUITE(misc)
|
|
* {
|
|
* if (today_is_monday)
|
|
* return PWTEST_SKIP;
|
|
*
|
|
* // simple test
|
|
* pwtest_add(some_test, PWTEST_NOARG);
|
|
* // starts with its own pipewire daemon instance
|
|
* pwtest_add(some_test, PWTEST_ARG_DAEMON);
|
|
*
|
|
* return PWTEST_SUCCESS;
|
|
* }
|
|
* ```
|
|
* For a list of potential arguments, see \ref pwtest_arg and the
|
|
* `test-examples.c` file in the source directory.
|
|
*
|
|
* Suites are auto-discovered, they do not have to be manually added to a test run.
|
|
*
|
|
* ## Running tests
|
|
*
|
|
* The `pwtest` framework is built into each test binary, so just execute the
|
|
* matching binary. See the `--help` output for the full argument list.
|
|
*
|
|
* The most useful arguments when running the test suite:
|
|
* - `--verbose` to enable logs even when tests pass or are skipped
|
|
* - `--filter-test=glob`, `--filter-suite=glob` uses an `fnmatch()` glob to limit which tests or suites are run
|
|
* - `--no-fork` - see "Debugging test-case failures"
|
|
*
|
|
* ## Debugging test-case failures
|
|
*
|
|
* To debug a single test, disable forking and run the test through gdb:
|
|
*
|
|
* ```
|
|
* $ gdb path/to/test
|
|
* (gdb) break test_function_name
|
|
* Breakpoint 1 at 0xfffffffffffff: file ../test/test-file.c, line 123
|
|
* (gdb) r --no-fork --filter-test=test_function_name
|
|
* ```
|
|
* Disabling forking makes it easy to debug but should always be used with
|
|
* `--filter-test`. Any test that modifies its environment will affect
|
|
* subsequent tests and may invalidate the test results.
|
|
*
|
|
* Where a test has multiple iterations, use `--filter-iteration` to only run
|
|
* one single iteration.
|
|
*/
|
|
|
|
/**
|
|
* \addtogroup pwtest
|
|
* \{
|
|
*/
|
|
|
|
|
|
/** \struct pwtest_context */
|
|
struct pwtest_context;
|
|
/** \struct pwtest_suite */
|
|
struct pwtest_suite;
|
|
/** \struct pwtest_test */
|
|
struct pwtest_test;
|
|
|
|
#include "pwtest-implementation.h"
|
|
|
|
/**
|
|
* Result returned from tests or suites.
|
|
*/
|
|
enum pwtest_result {
|
|
PWTEST_PASS = 75, /**< test successful */
|
|
PWTEST_FAIL = 76, /**< test failed. Should not be returned directly,
|
|
Use the pwtest_ macros instead */
|
|
PWTEST_SKIP = 77, /**< test was skipped */
|
|
PWTEST_TIMEOUT = 78, /**< test aborted after timeout */
|
|
PWTEST_SYSTEM_ERROR = 79, /**< unrelated error occurred */
|
|
};
|
|
|
|
/**
|
|
* If the test was added with a range (see \ref PWTEST_ARG_RANGE), this
|
|
* function returns the current iteration within that range. Otherwise, this
|
|
* function returns zero.
|
|
*/
|
|
int pwtest_get_iteration(struct pwtest_test *t);
|
|
|
|
/**
|
|
* If the test had properties set (see \ref PWTEST_ARG_PROP), this function
|
|
* returns the \ref pw_properties. Otherwise, this function returns NULL.
|
|
*/
|
|
struct pw_properties *pwtest_get_props(struct pwtest_test *t);
|
|
|
|
struct pwtest_context *pwtest_get_context(struct pwtest_test *t);
|
|
|
|
/** Fail the current test */
|
|
#define pwtest_fail() \
|
|
_pwtest_fail_condition(PWTEST_FAIL, __FILE__, __LINE__, __func__, "aborting", "")
|
|
|
|
/** Same as above but more expressive in the code */
|
|
#define pwtest_fail_if_reached() \
|
|
_pwtest_fail_condition(PWTEST_FAIL, __FILE__, __LINE__, __func__, "This line is supposed to be unreachable", "")
|
|
|
|
/** Fail the current test with the given message */
|
|
#define pwtest_fail_with_msg(...) \
|
|
_pwtest_fail_condition(PWTEST_FAIL, __FILE__, __LINE__, __func__, \
|
|
"aborting", __VA_ARGS__)
|
|
|
|
/** Error out of the current test with the given message */
|
|
#define pwtest_error_with_msg(...) \
|
|
_pwtest_fail_condition(PWTEST_SYSTEM_ERROR, __FILE__, __LINE__, __func__, \
|
|
"error", __VA_ARGS__)
|
|
|
|
/** Assert r is not -1 and if it is, print the errno */
|
|
#define pwtest_errno_ok(r_) \
|
|
pwtest_errno_check(r_, 0);
|
|
|
|
/** Assert r is -1 and the errno is the given one */
|
|
#define pwtest_errno(r_, errno_) \
|
|
pwtest_errno_check(r_, errno_);
|
|
|
|
/** Assert r is not < 0 and if it is assume it's a negative errno */
|
|
#define pwtest_neg_errno_ok(r_) \
|
|
pwtest_neg_errno_check(r_, 0);
|
|
|
|
/** Assert r is < 0 and the given negative errno */
|
|
#define pwtest_neg_errno(r_, errno_) \
|
|
pwtest_neg_errno_check(r_, errno_);
|
|
|
|
/** Assert boolean (a == b) */
|
|
#define pwtest_bool_eq(a_, b_) \
|
|
pwtest_comparison_bool_(a_, ==, b_)
|
|
|
|
/** Assert boolean (a != b) */
|
|
#define pwtest_bool_ne(a_, b_) \
|
|
pwtest_comparison_bool_(a_, !=, b_)
|
|
|
|
/** Assert cond to be true. Convenience wrapper for readability */
|
|
#define pwtest_bool_true(cond_) \
|
|
pwtest_comparison_bool_(cond_, ==, true)
|
|
|
|
/** Assert cond to be false. Convenience wrapper for readability */
|
|
#define pwtest_bool_false(cond_) \
|
|
pwtest_comparison_bool_(cond_, ==, false)
|
|
|
|
/** Assert a == b */
|
|
#define pwtest_int_eq(a_, b_) \
|
|
pwtest_comparison_int_(a_, ==, b_)
|
|
|
|
/** Assert a != b */
|
|
#define pwtest_int_ne(a_, b_) \
|
|
pwtest_comparison_int_(a_, !=, b_)
|
|
|
|
/** Assert a < b */
|
|
#define pwtest_int_lt(a_, b_) \
|
|
pwtest_comparison_int_(a_, <, b_)
|
|
|
|
/** Assert a <= b */
|
|
#define pwtest_int_le(a_, b_) \
|
|
pwtest_comparison_int_(a_, <=, b_)
|
|
|
|
/** Assert a >= b */
|
|
#define pwtest_int_ge(a_, b_) \
|
|
pwtest_comparison_int_(a_, >=, b_)
|
|
|
|
/** Assert a > b */
|
|
#define pwtest_int_gt(a_, b_) \
|
|
pwtest_comparison_int_(a_, >, b_)
|
|
|
|
/** Assert ptr1 == ptr2 */
|
|
#define pwtest_ptr_eq(a_, b_) \
|
|
pwtest_comparison_ptr_(a_, ==, b_)
|
|
|
|
/** Assert ptr1 != ptr2 */
|
|
#define pwtest_ptr_ne(a_, b_) \
|
|
pwtest_comparison_ptr_(a_, !=, b_)
|
|
|
|
/** Assert ptr == NULL */
|
|
#define pwtest_ptr_null(a_) \
|
|
pwtest_comparison_ptr_(a_, ==, NULL)
|
|
|
|
/** Assert ptr != NULL */
|
|
#define pwtest_ptr_notnull(a_) \
|
|
pwtest_comparison_ptr_(a_, !=, NULL)
|
|
|
|
/** Assert a == b for a (hardcoded) epsilon */
|
|
#define pwtest_double_eq(a_, b_)\
|
|
pwtest_comparison_double_((a_), ==, (b_))
|
|
|
|
/** Assert a != b for a (hardcoded) epsilon */
|
|
#define pwtest_double_ne(a_, b_)\
|
|
pwtest_comparison_double_((a_), !=, (b_))
|
|
|
|
/** Assert a < b for a (hardcoded) epsilon */
|
|
#define pwtest_double_lt(a_, b_)\
|
|
pwtest_comparison_double_((a_), <, (b_))
|
|
|
|
/** Assert a <= b for a (hardcoded) epsilon */
|
|
#define pwtest_double_le(a_, b_)\
|
|
pwtest_comparison_double_((a_), <=, (b_))
|
|
|
|
/** Assert a >= b for a (hardcoded) epsilon */
|
|
#define pwtest_double_ge(a_, b_)\
|
|
pwtest_comparison_double_((a_), >=, (b_))
|
|
|
|
/** Assert a > b for a (hardcoded) epsilon */
|
|
#define pwtest_double_gt(a_, b_)\
|
|
pwtest_comparison_double_((a_), >, (b_))
|
|
|
|
#define pwtest_int(a_, op_, b_) \
|
|
pwtest_comparison_int_(a_, op_, b_)
|
|
|
|
|
|
/** Assert str1 is equal to str2 */
|
|
#define pwtest_str_eq(a_, b_) \
|
|
do { \
|
|
const char *_a = a_; \
|
|
const char *_b = b_; \
|
|
if (!spa_streq(_a, _b)) \
|
|
_pwtest_fail_comparison_str(__FILE__, __LINE__, __func__, \
|
|
#a_ " equals " #b_, _a, _b); \
|
|
} while(0)
|
|
|
|
/** Assert str1 is equal to str2 for l characters */
|
|
#define pwtest_str_eq_n(a_, b_, l_) \
|
|
do { \
|
|
const char *_a = a_; \
|
|
const char *_b = b_; \
|
|
if (!spa_strneq(_a, _b, l_)) \
|
|
_pwtest_fail_comparison_str(__FILE__, __LINE__, __func__, \
|
|
#a_ " equals " #b_ ", len: " #l_, _a, _b); \
|
|
} while(0)
|
|
|
|
/** Assert str1 is not equal to str2 */
|
|
#define pwtest_str_ne(a_, b_) \
|
|
do { \
|
|
const char *_a = a_; \
|
|
const char *_b = b_; \
|
|
if (spa_streq(_a, _b)) \
|
|
_pwtest_fail_comparison_str(__FILE__, __LINE__, __func__, \
|
|
#a_ " not equal to " #b_, _a, _b); \
|
|
} while(0)
|
|
|
|
/** Assert str1 is not equal to str2 for l characters */
|
|
#define pwtest_str_ne_n(a_, b_, l_) \
|
|
do { \
|
|
__typeof__(a_) _a = a_; \
|
|
__typeof__(b_) _b = b_; \
|
|
if (spa_strneq(_a, _b, l_)) \
|
|
_pwtest_fail_comparison_str(__FILE__, __LINE__, __func__, \
|
|
#a_ " not equal to " #b_ ", len: " #l_, _a, _b); \
|
|
} while(0)
|
|
|
|
|
|
/** Assert haystack contains needle */
|
|
#define pwtest_str_contains(haystack_, needle_) \
|
|
do { \
|
|
const char *_h = haystack_; \
|
|
const char *_n = needle_; \
|
|
if (!strstr(_h, _n)) \
|
|
_pwtest_fail_comparison_str(__FILE__, __LINE__, __func__, \
|
|
#haystack_ " contains " #needle_, _h, _n); \
|
|
} while(0)
|
|
|
|
|
|
/* Needs to be a #define NULL for SPA_SENTINEL */
|
|
enum pwtest_arg {
|
|
PWTEST_NOARG = 0,
|
|
/**
|
|
* The next argument is an int specifying the numerical signal number.
|
|
* The test is expected to raise that signal. The test fails if none
|
|
* or any other signal is raised.
|
|
*
|
|
* Example:
|
|
* ```c
|
|
* pwtest_add(mytest, PWTEST_ARG_SIGNAL, SIGABRT);
|
|
* ```
|
|
*/
|
|
PWTEST_ARG_SIGNAL,
|
|
/**
|
|
* The next two int arguments are the minimum (inclusive) and
|
|
* maximum (exclusive) range for this test.
|
|
*
|
|
* Example:
|
|
* ```c
|
|
* pwtest_add(mytest, PWTEST_ARG_RANGE, -50, 50);
|
|
* ```
|
|
* Use pwtest_get_iteration() in the test function to obtain the current iteration.
|
|
*/
|
|
PWTEST_ARG_RANGE,
|
|
/**
|
|
* The next two const char * arguments are the key and value
|
|
* for a property entry. This argument may be specified multiple times
|
|
* to add multiple properties.
|
|
*
|
|
* Use pwtest_get_props() to get the properties within the test function.
|
|
*
|
|
* Example:
|
|
* ```c
|
|
* pwtest_add(mytest,
|
|
* PWTEST_ARG_PROP, "key1", "value1",
|
|
* PWTEST_ARG_PROP, "key2", "value2");
|
|
* ```
|
|
*/
|
|
PWTEST_ARG_PROP,
|
|
/**
|
|
* The next two const char * arguments are the key and value
|
|
* for the environment variable to be set in the test. This argument
|
|
* may be specified multiple times to add multiple environment
|
|
* variables.
|
|
*
|
|
* Example:
|
|
* ```c
|
|
* pwtest_add(mytest,
|
|
* PWTEST_ARG_ENV, "env1", "value1",
|
|
* PWTEST_ARG_ENV, "env2", "value2");
|
|
* ```
|
|
*
|
|
* These environment variables are only set for the test itself, a
|
|
* a pipewire daemon started with \ref PWTEST_ARG_DAEMON does not share
|
|
* those variables.
|
|
*
|
|
*/
|
|
PWTEST_ARG_ENV,
|
|
/**
|
|
* Takes no extra arguments. If provided, the test case will start a
|
|
* pipewire daemon and stop the daemon when finished.
|
|
*
|
|
* The `PIPEWIRE_REMOTE` environment variable will be set in the
|
|
* test to point to this daemon.
|
|
*
|
|
* Example:
|
|
* ```c
|
|
* pwtest_add(mytest, PWTEST_ARG_DAEMON);
|
|
* ```
|
|
*
|
|
* Environment variables specified with \ref PWTEST_ARG_ENV are
|
|
* **not** available to the daemon, only to the test itself.
|
|
*/
|
|
PWTEST_ARG_DAEMON,
|
|
};
|
|
/**
|
|
* Add function \a func_ to the current test suite.
|
|
*
|
|
* This macro should be used within PWTEST_SUITE() to register the test in that suite, for example:
|
|
*
|
|
* ```c
|
|
* PWTEST_SUITE(mysuite)
|
|
* {
|
|
* pwtest_add(test1, PWTEST_NOARG);
|
|
* pwtest_add(test2, PWTEST_ARG_DAEMON);
|
|
* pwtest_add(test3, PWTEST_ARG_RANGE, 0, 100, PWTEST_ARG_DAEMON);
|
|
* }
|
|
*
|
|
* ```
|
|
*
|
|
* If the test matches the given filters and the suite is executed, the test
|
|
* will be executed with the parameters given to pwtest_add().
|
|
*
|
|
* Arguments take a argument-dependent number of extra parameters, see
|
|
* see the \ref pwtest_arg documentation for details.
|
|
*/
|
|
#define pwtest_add(func_, ...) \
|
|
_pwtest_add(ctx, suite, #func_, func_, __VA_ARGS__, NULL)
|
|
|
|
|
|
/**
|
|
* Declare a test case. To execute the test, add the test case name with pwtest_add().
|
|
*
|
|
* This macro expands so each test has a struct \ref pwtest_test variable
|
|
* named `current_test` available.
|
|
*
|
|
* ```c
|
|
* PWTEST(mytest)
|
|
* {
|
|
* struct pwtest_test *t = current_test;
|
|
*
|
|
* ... do stuff ...
|
|
*
|
|
* return PWTEST_PASS;
|
|
* }
|
|
*
|
|
* PWTEST_SUITE(mysuite)
|
|
* {
|
|
* pwtest_add(mytest);
|
|
*
|
|
* return PWTEST_PASS;
|
|
* }
|
|
* ```
|
|
*/
|
|
#define PWTEST(tname) \
|
|
static enum pwtest_result tname(struct pwtest_test *current_test)
|
|
|
|
/**
|
|
* Initialize a test suite. A test suite is a group of related
|
|
* tests that filters and other conditions may apply to.
|
|
*
|
|
* Test suites are automatically discovered at build-time.
|
|
*/
|
|
#define PWTEST_SUITE(cname) \
|
|
static enum pwtest_result (cname##__setup)(struct pwtest_context *ctx, struct pwtest_suite *suite); \
|
|
__attribute__((used)) \
|
|
__attribute__((retain)) \
|
|
__attribute__((section("pwtest_suite_section"))) \
|
|
__attribute__((aligned(__alignof__(struct pwtest_suite_decl)))) \
|
|
static const struct pwtest_suite_decl _test_suite = { \
|
|
.name = #cname, \
|
|
.setup = cname##__setup, \
|
|
}; \
|
|
static enum pwtest_result (cname##__setup)(struct pwtest_context *ctx, struct pwtest_suite *suite)
|
|
|
|
struct pwtest_spa_plugin {
|
|
#define PWTEST_PLUGIN_MAX 32
|
|
size_t nsupport;
|
|
struct spa_support support[PWTEST_PLUGIN_MAX];
|
|
|
|
size_t ndlls;
|
|
void *dlls[PWTEST_PLUGIN_MAX];
|
|
|
|
size_t nhandles;
|
|
struct spa_handle *handles[PWTEST_PLUGIN_MAX];
|
|
};
|
|
|
|
struct pwtest_spa_plugin* pwtest_spa_plugin_new(void);
|
|
void pwtest_spa_plugin_destroy(struct pwtest_spa_plugin *plugin);
|
|
|
|
/**
|
|
* Identical to pwtest_spa_plugin_try_load_interface() but returns the
|
|
* interface and fails if the interface is NULL.
|
|
*/
|
|
void*
|
|
pwtest_spa_plugin_load_interface(struct pwtest_spa_plugin *plugin,
|
|
const char *libname,
|
|
const char *factory_name,
|
|
const char *interface_name,
|
|
const struct spa_dict *info);
|
|
|
|
/**
|
|
* Load \a interface_name from the factory in \a libname.
|
|
* If successful, the interface is returned and added to \a plugin's
|
|
* support items, i.e. subsequent loads of an interface will be able to
|
|
* make use of previously loaded ones.
|
|
*
|
|
* \return 0 on success or a negative errno on error
|
|
* \retval -ENOENT \a libname does not exist
|
|
* \retval -EINVAL \a factory_name does not exist in \a libname
|
|
* \retval -ENOSYS \a interface_name does not exist in \a factory_name
|
|
*/
|
|
int
|
|
pwtest_spa_plugin_try_load_interface(struct pwtest_spa_plugin *plugin,
|
|
void **iface_return,
|
|
const char *libname,
|
|
const char *factory_name,
|
|
const char *interface_name,
|
|
const struct spa_dict *info);
|
|
|
|
|
|
|
|
/**
|
|
* Create a temporary file and copy its full path to \a path. Fails the test
|
|
* with \ref PWTEST_SYSTEM_ERROR on error.
|
|
*
|
|
* This file does not need to be removed by the test, the pwtest framework
|
|
* will take care of it on exit.
|
|
*/
|
|
void pwtest_mkstemp(char path[PATH_MAX]);
|
|
|
|
/**
|
|
* Run a command and wait for it to return.
|
|
*/
|
|
int pwtest_spawn(const char *file, char *const argv[]);
|
|
|
|
|
|
/**
|
|
* \}
|
|
*/
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* PWTEST_H */
|