Reference manual¶

Test harness API¶

enum testharness::renderer_type¶

Weston renderer type.

See: compositor_setup

Values:

RENDERER_NOOP = 0¶: Dummy renderer that does nothing.

RENDERER_PIXMAN¶: Pixman-renderer.

RENDERER_GL¶: GL-renderer.

enum testharness::shell_type¶

Weston shell plugin.

See: compositor_setup

Values:

SHELL_TEST_DESKTOP = 0¶: Desktop test-shell with predictable window placement and no helper clients.

SHELL_DESKTOP¶: The full desktop shell.

SHELL_IVI¶: The ivi-shell.

SHELL_FULLSCREEN¶: The fullscreen-shell.

enum testharness::test_result_code¶

Standard return codes.

Both Autotools and Meson use these codes as test program exit codes to denote the test result for the whole process.

Values:

RESULT_OK = 0¶

RESULT_SKIP = 77¶

RESULT_FAIL = 1¶

RESULT_HARD_ERROR = 99¶

const char *get_test_name(void)¶

Get the test name string with counter.

This is only usable from code paths inside

TEST(), TEST_P(), PLUGIN_TEST() etc. defined functions.

Return: The test name with fixture number -f%d added. For an array driven test, e.g. defined with TEST_P(), the name has also a -e%d suffix to indicate the array element number.

int get_test_fixture_index(void)¶

Get the current fixture index.

Returns the current fixture index which can be used directly as an index into the array passed as an argument to DECLARE_FIXTURE_SETUP_WITH_ARG().

This is only usable from code paths inside TEST(), TEST_P(), PLUGIN_TEST() etc. defined functions.

void testlog(const char *fmt, ...)¶

Print into test log.

This is exactly like printf() except the output goes to the test log, which is at stderr.

Parameters

fmt: printf format string

enum test_result_code weston_test_harness_execute_as_client(struct weston_test_harness *harness, const struct compositor_setup *setup)¶

Execute all tests as client tests.

Initializes the compositor with the given setup and executes the compositor. The compositor creates a new thread where all tests in the test program are serially executed. Once the thread finishes, the compositor returns from its event loop and cleans up.

Parameters

harness: The test harness context.
setup: The compositor configuration.

Returns RESULT_SKIP if the requested compositor features, e.g. GL-renderer, are not built.

See: DECLARE_FIXTURE_SETUP(), DECLARE_FIXTURE_SETUP_WITH_ARG()

enum test_result_code weston_test_harness_execute_as_plugin(struct weston_test_harness *harness, const struct compositor_setup *setup)¶

Execute all tests as plugin tests.

Initializes the compositor with the given setup and executes the compositor. The compositor executes all tests in the test program serially from an idle handler, then returns from its event loop and cleans up.

Parameters

harness: The test harness context.
setup: The compositor configuration.

Returns RESULT_SKIP if the requested compositor features, e.g. GL-renderer, are not built.

See: DECLARE_FIXTURE_SETUP(), DECLARE_FIXTURE_SETUP_WITH_ARG()

enum test_result_code weston_test_harness_execute_standalone(struct weston_test_harness *harness)¶

Execute all tests as standalone tests.

Executes all tests in the test program serially without any further setup, particularly without any compositor instance created.

Parameters

harness: The test harness context.

See: DECLARE_FIXTURE_SETUP(), DECLARE_FIXTURE_SETUP_WITH_ARG()

const struct fixture_setup_array *fixture_setup_array_get_(void)¶

Fixture data array getter method.

DECLARE_FIXTURE_SETUP_WITH_ARG() overrides this in test programs. The default implementation has no data and makes the tests run once.

enum test_result_code fixture_setup_run_(struct weston_test_harness *harness, const void *arg_)¶

Fixture setup function.

DECLARE_FIXTURE_SETUP() and DECLARE_FIXTURE_SETUP_WITH_ARG() override this in test programs. The default implementation just calls weston_test_harness_execute_standalone().

compositor_setup_defaults(s)¶

Initialize compositor setup to defaults.

The defaults are:

backend: headless
renderer: noop
shell: desktop shell
xwayland: no
width: 320
height: 240
scale: 1
transform: WL_OUTPUT_TRANSFORM_NORMAL
config_file: none
extra_module: none
logging_scopes: compositor defaults
testset_name: the test name from meson.build

Parameters

s: The variable to initialize.

TEST(name)¶

Add a test with no parameters.

This defines one test as a new function. Use this macro in place of the function signature and put the function body after this.

Parameters

name: Name for the test, must be a valid function name.

TEST_P(name, data_array)¶

Add an array driven test with a parameter.

This defines an array of tests as a new function. Use this macro in place of the function signature and put the function body after this. The function will be executed once for each element in data_array, passing the element as the argument void *data to the function.

This macro is not usable if fixture setup is using weston_test_harness_execute_as_plugin().

Parameters

name: Name for the test, must be a valid function name.
data_array: A static const array of any type. The length will be recorded automatically.

PLUGIN_TEST(name)¶

Add a test with weston_compositor argument.

This defines one test as a new function. Use this macro in place of the function signature and put the function body after this. The function will have one argument struct weston_compositor *compositor.

This macro is only usable if fixture setup is using weston_test_harness_execute_as_plugin().

Parameters

name: Name for the test, must be a valid function name.

DECLARE_FIXTURE_SETUP(func_)¶

Register a fixture setup function.

This registers the given (preferably static) function to be used for setting up any fixtures you might need. The function must have the signature:

enum test_result_code func_(struct weston_test_harness *harness)

The function must call one of weston_test_harness_execute_standalone(), weston_test_harness_execute_as_plugin() or weston_test_harness_execute_as_client() passing in the harness argument, and return the return value from that call. The function can also return a test_result_code on its own if it does not want to run the tests, e.g. RESULT_SKIP or RESULT_HARD_ERROR.

The function will be called once to run all tests.

Parameters

func_: The function to be used as fixture setup.

DECLARE_FIXTURE_SETUP_WITH_ARG(func_, array_)¶

Register a fixture setup function with a data array.

This registers the given (preferably static) function to be used for setting up any fixtures you might need. The function must have the signature:

enum test_result_code func_(struct weston_test_harness *harness, typeof(array_[0]) *arg)

The function must call one of weston_test_harness_execute_standalone(), weston_test_harness_execute_as_plugin() or weston_test_harness_execute_as_client() passing in the harness argument, and return the return value from that call. The function can also return a test_result_code on its own if it does not want to run the tests, e.g. RESULT_SKIP or RESULT_HARD_ERROR.

The function will be called once with each element of the array pointed to by arg, so that all tests would be repeated for each element in turn.

Parameters

func_: The function to be used as fixture setup.
array_: A static const array of arbitrary type.

struct compositor_setup¶

#include <weston-test-fixture-compositor.h>

Weston compositor configuration.

This structure determines the Weston compositor command line arguments. You should always use compositor_setup_defaults() to initialize this, then override any members you need with assignments.

Public Members

weston_compositor_backend backend¶: The backend to use.

renderer_type renderer¶: The renderer to use.

shell_type shell¶: The shell plugin to use.

bool xwayland¶: Whether to enable xwayland support.

unsigned width¶: Default output width.

unsigned height¶: Default output height.

int scale¶: Default output scale.

wl_output_transform transform¶: Default output transform, one of WL_OUTPUT_TRANSFORM_*.

const char *config_file¶: The absolute path to weston.ini to use, or NULL for no-config .

const char *extra_module¶: Full path to an extra plugin to load, or NULL for none.

const char *logging_scopes¶: Debug scopes for the compositor log, or NULL for compositor defaults.

const char *testset_name¶: The name of this test program, used as a unique identifier.

Test harness Internals¶

enum testharness_private::test_type¶

Weston test types.

See: weston_test_harness_execute_standalone weston_test_harness_execute_as_plugin weston_test_harness_execute_as_client

Values:

TEST_TYPE_STANDALONE¶

TEST_TYPE_PLUGIN¶

TEST_TYPE_CLIENT¶

void compositor_setup_defaults_(struct compositor_setup *setup, const char *testset_name)¶

Initialize part of compositor setup.

Parameters

setup: The variable to initialize.
testset_name: Value for testset_name member.

int execute_compositor(const struct compositor_setup *setup, struct wet_testsuite_data *data)¶

Execute compositor.

Manufactures the compositor command line and calls wet_main().

Returns RESULT_SKIP if the given setup contains features that were disabled in the build, e.g. GL-renderer or DRM-backend.

struct weston_test_entry¶

#include <weston-test-runner.h>

Test program entry.

Each invocation of TEST(), TEST_P(), or PLUGIN_TEST() will create one more weston_test_entry in a custom named section in the final binary. Iterating through the section then allows to iterate through all the defined tests.

Public Members

const char *name¶

void (*run)(void *)¶

const void *table_data¶

size_t element_size¶

int n_elements¶

struct fixture_setup_array¶

#include <weston-test-runner.h>

Fixture setup array record.

Helper to store the attributes of the data array passed in to DECLARE_FIXTURE_SETUP_WITH_ARG().

Public Members

const void *array¶

size_t element_size¶

int n_elements¶

struct wet_testsuite_data¶

#include <weston-testsuite-data.h>

Test harness specific data for running tests.

Public Members

void (*run)(struct wet_testsuite_data *)¶

const struct weston_test_entry *tests¶

unsigned tests_count¶

int case_index¶

test_type type¶

struct weston_compositor *compositor¶

int thread_event_pipe¶

int fixture_iteration¶

unsigned counter¶

unsigned passed¶

unsigned skipped¶

unsigned failed¶

unsigned total¶