# Reference manual

## Test harness API

enum shell_type

  Weston shell plugin.

  See also

  compositor_setup

  Values:

  enumerator SHELL_TEST_DESKTOP

    Desktop test-shell with predictable window placement and no helper clients.

  enumerator SHELL_DESKTOP

    The full desktop shell.

  enumerator SHELL_IVI

    The ivi-shell.

  enumerator SHELL_FULLSCREEN

    The fullscreen-shell.

  enumerator SHELL_KIOSK

    The kiosk shell.

  enumerator SHELL_LUA

    The lua shell.

enum 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:

  enumerator RESULT_OK
  enumerator RESULT_SKIP
  enumerator RESULT_FAIL
  enumerator RESULT_HARD_ERROR

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.

  Returns:

    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

int get_test_fixture_number_from_harness(struct weston_test_harness *harness)

  Get the current fixture number from test harness.

  Similar to get_test_fixture_index(), but get the fixture number (index + 1) directly from the test harness. Can be called from fixture_setup() functions.

  See also

  DECLARE_FIXTURE_SETUP(), DECLARE_FIXTURE_SETUP_WITH_ARG()

  Parameters:

    harness – The test harness.

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.

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

  See also

  DECLARE_FIXTURE_SETUP(), DECLARE_FIXTURE_SETUP_WITH_ARG()

  Parameters:

    - harness – The test harness context.

    - setup – The compositor configuration.

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.

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

  See also

  DECLARE_FIXTURE_SETUP(), DECLARE_FIXTURE_SETUP_WITH_ARG()

  Parameters:

    - harness – The test harness context.

    - setup – The compositor configuration.

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.

  See also

  DECLARE_FIXTURE_SETUP(), DECLARE_FIXTURE_SETUP_WITH_ARG()

  Parameters:

    harness – The test harness context.

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: test desktop shell

  - xwayland: no

  - width: 320

  - height: 240

  - refresh: 0 (repaint only on demand)

  - 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.

TEST_GET_SUITE_DATA()

  Get test suite data structure.

  This returns the shared test suite data structure, to be used in any test which is declared with TEST(), TEST_P(), or PLUGIN_TEST().

  Returns:

    Test suite data structure

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_, meta_)

  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.

    - meta_ – Name of the field with type struct fixture_metadata.

struct weston_testsuite_quirks
  #include <libweston.h>

  Weston test suite quirks.

  There are some things that need a specific behavior when we run Weston in the test suite. Tests can use this struct to select for certain behaviors.

  See also

  compositor_setup

  Public Members

  bool force_full_upload

    Force GL/Vulkan-renderer to do a full upload of wl_shm buffers.

  bool gl_force_full_redraw_of_shadow_fb

    Ensure GL shadow fb is used, and always repaint it fully.

  bool gl_force_import_yuv_fallback

    Force GL-renderer to use the internal YUV->RGB shader.

  uint32_t required_capabilities

    Required enum weston_capability bit mask, otherwise skip run.

struct weston_testsuite_data
  #include <libweston.h>

  Weston test suite data that is given to compositor.

  It contains two members:

  1. The struct weston_testsuite_quirks, which can be used by the tests to change certain behavior of Weston when running these tests.

  2. The void *test_private_data member which can be used by the testsuite of projects that uses libweston in order to give arbitrary test data to the compositor. Its type should be defined by the testsuite of the project.

  See also

  compositor_setup

  Public Members

  struct weston_testsuite_quirks test_quirks
  void *test_private_data

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

  struct weston_testsuite_quirks test_quirks

    The test suite quirks.

  enum weston_compositor_backend backend

    The backend to use.

  enum weston_renderer_type renderer

    The renderer to use.

  enum 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.

  int refresh

    Default output refresh rate (headless backend); set to HIGHEST_REFRESH_RATE for maximum throughput, or to 0 for only rendering on demand (e.g.

    when a screenshot is requested).

  enum wl_output_transform transform

    Default output transform, one of WL_OUTPUT_TRANSFORM_*.

  char *config_file

    The absolute path to `weston.ini` to use, or NULL for `--no-config` .

    To properly fill this entry use weston_ini_setup()

  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.

struct fixture_metadata
  #include <weston-test-runner.h>

  Metadata for fixture setup array elements.

  Every type used as a fixture setup array’s elements needs one member of this type, initialized.

  See also

  DECLARE_FIXTURE_SETUP_WITH_ARG()

  Public Members

  const char *name

    Human friendly name of the fixture setup.

## Test harness Internals

enum test_type

  Weston test types.

  See also

  weston_test_harness_execute_standalone weston_test_harness_execute_as_plugin weston_test_harness_execute_as_client

  Values:

  enumerator TEST_TYPE_STANDALONE
  enumerator TEST_TYPE_PLUGIN
  enumerator 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.

static inline void wet_test_post_sem(sem_t *sem)

  Safely handle posting a semaphore to wake a waiter.

static inline void wet_test_wait_sem(sem_t *sem)

  Safely handle waiting on a semaphore.

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
  enum test_result_code (*run)(struct wet_testsuite_data*, 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
  size_t meta_offset

struct wet_test_pending_breakpoint
  #include <weston-testsuite-data.h>

  An individual breakpoint set for the server.

  This breakpoint data is created and placed in a list by either the server (when handling protocol messages) or the client (when directly manipulating the list during a breakpoint).

  It must be freed by the client.

  Public Members

  uint32_t breakpoint

    breakpoint type - enum weston_test_breakpoint from protocol

  void *resource

    type-specific resource to filter on (optional)

  struct wl_list link

    wet_testsuite_breakpoints.list

struct wet_test_active_breakpoint
  #include <weston-testsuite-data.h>

  Information about the server’s active breakpoint.

  This breakpoint data is created by the server and passed to the client when the server enters a breakpoint.

  It must be freed by the client.

  Public Members

  struct weston_compositor *compositor

    libweston compositor instance in use

  void *resource

    type-specific pointer to resource which triggered this breakpoint

  bool rearm_on_release

    on release, reinsert the template to trigger next time

  struct wet_test_pending_breakpoint *template_

    client’s original breakpoint request

struct wet_testsuite_breakpoints
  #include <weston-testsuite-data.h>

  Client/compositor synchronisation for breakpoint state.

  Manages the set of active breakpoints placed for the server, as well as signalling the pausing/continuing of server actions.

  Public Members

  sem_t client_break

    signalled by the server when it reaches a breakpoint

  sem_t server_release

    signalled by the client to resume server execution

  struct wet_test_active_breakpoint *active_bp

    Pushed by the server when a breakpoint is triggered, immediately before it signals the client_break semaphore.

    Client consumes this and takes ownership after the wait succeeds.

  bool in_client_break

    client-internal state; set by consuming active_bp, cleared by signalling server_release

  struct wl_list list

    list of pending breakpoints: owned by the server during normal execution (ordinarily added to by a protocol request, and traversed to find a possible breakpoint to trigger), and owned by the client wtihin a breakpoint (pending breakpoints may be added or removed).

    Members are wet_test_pending_breakpoint.link

struct wet_testsuite_data
  #include <weston-testsuite-data.h>

  Test harness specific data for running tests.

  Public Members

  void (*run)(struct wet_testsuite_data*)
  void *wl_client
  const struct weston_test_entry *tests
  unsigned tests_count
  int case_index
  enum test_type type
  struct weston_compositor *compositor
  int thread_event_pipe
  struct wet_testsuite_breakpoints breakpoints
  int fixture_iteration
  const char *fixture_name
  unsigned counter
  unsigned passed
  unsigned skipped
  unsigned failed
  unsigned total