Harness

Added in version 1.6.

class Harness(*args, **kwargs)

Harness is meant to make writing unit test for GStreamer much easier. It can be thought of as a way of treating a Element as a black box, deterministically feeding it data, and controlling what data it outputs.

The basic structure of Harness is two “floating” Pad that connect to the harnessed Element src and sink Pad like so:

          ``__________________________``
 ``_____``   |  ``_____``            ``_____``  |   ``_____``
|     |  | |     |          |     | |  |     |
| src |--+-| sink|  Element | src |-+--| sink|
|``_____``|  | |``_____``|          |``_____``| |  |``_____``|
         |``__________________________``|

With this, you can now simulate any environment the Element might find itself in. By specifying the Caps of the harness Pad, using functions like set_src_caps() or set_sink_caps_str(), you can test how the Element interacts with different caps sets.

Your harnessed Element can of course also be a bin, and using new_parse() supporting standard gst-launch syntax, you can easily test a whole pipeline instead of just one element.

You can then go on to push Buffer and Event on to the srcpad, using functions like push() and push_event(), and then pull them out to examine them with pull() and pull_event().

A simple buffer-in buffer-out example

``include`` <gst/gst.h>
``include`` <gst/check/gstharness.h>
GstHarness *h;
GstBuffer *in_buf;
GstBuffer *out_buf;

// attach the harness to the src and sink pad of GstQueue
h = gst_harness_new ("queue");

// we must specify a caps before pushing buffers
gst_harness_set_src_caps_str (h, "mycaps");

// create a buffer of size 42
in_buf = gst_harness_create_buffer (h, 42);

// push the buffer into the queue
gst_harness_push (h, in_buf);

// pull the buffer from the queue
out_buf = gst_harness_pull (h);

// validate the buffer in is the same as buffer out
fail_unless (in_buf == out_buf);

// cleanup
gst_buffer_unref (out_buf);
gst_harness_teardown (h);

Another main feature of the Harness is its integration with the TestClock. Operating the TestClock can be very challenging, but Harness simplifies some of the most desired actions a lot, like wanting to manually advance the clock while at the same time releasing a ClockID that is waiting, with functions like crank_single_clock_wait().

Harness also supports sub-harnesses, as a way of generating and validating data. A sub-harness is another Harness that is managed by the “parent” harness, and can either be created by using the standard gst_harness_new type functions directly on the (GstHarness *)->src_harness, or using the much more convenient add_src() or add_sink_parse(). If you have a decoder-element you want to test, (like vp8dec) it can be very useful to add a src-harness with both a src-element (videotestsrc) and an encoder (vp8enc) to feed the decoder data with different configurations, by simply doing:

GstHarness * h = gst_harness_new ("vp8dec");
gst_harness_add_src_parse (h, "videotestsrc is-live=1 ! vp8enc", TRUE);

and then feeding it data with:

gst_harness_push_from_src (h);

Methods

class Harness
add_element_sink_pad(sinkpad: Pad) → None

Links the specified Pad the GstHarness srcpad.

MT safe.

Added in version 1.6.

Parameters:

sinkpad – a Pad to link to the harness srcpad

add_element_src_pad(srcpad: Pad) → None

Links the specified Pad the GstHarness sinkpad. This can be useful if perhaps the srcpad did not exist at the time of creating the harness, like a demuxer that provides a sometimes-pad after receiving data.

MT safe.

Added in version 1.6.

Parameters:

srcpad – a Pad to link to the harness sinkpad

add_probe(element_name: str, pad_name: str, mask: PadProbeType, callback: Callable[[...], PadProbeReturn], *user_data: Any) → None

A convenience function to allows you to call gst_pad_add_probe on a Pad of a Element that are residing inside the Harness, by using normal gst_pad_add_probe syntax

MT safe.

Added in version 1.6.

Parameters:

  • element_name – a utf8 with a ElementFactory name

  • pad_name – a utf8 with the name of the pad to attach the probe to

  • mask – a PadProbeType (see gst_pad_add_probe)

  • callback – a PadProbeCallback (see gst_pad_add_probe)

  • user_data – a gpointer (see gst_pad_add_probe)

add_propose_allocation_meta(api: type, params: Structure | None = None) → None

Add api with params as one of the supported metadata API to propose when receiving an allocation query.

MT safe.

Added in version 1.16.

Parameters:

  • api – a metadata API

  • params – API specific parameters

add_sink(sink_element_name: str) → None

Similar to gst_harness_add_sink_harness, this is a convenience to directly create a sink-harness using the sink_element_name name specified.

MT safe.

Added in version 1.6.

Parameters:

sink_element_name – a utf8 with the name of a Element

add_sink_harness(sink_harness: Harness) → None

Similar to gst_harness_add_src, this allows you to send the data coming out of your harnessed Element to a sink-element, allowing to test different responses the element output might create in sink elements. An example might be an existing sink providing some analytical data on the input it receives that can be useful to your testing. If the goal is to test a sink-element itself, this is better achieved using gst_harness_new directly on the sink.

If a sink-harness already exists it will be replaced.

MT safe.

Added in version 1.6.

Parameters:

sink_harness – a Harness to be added as a sink-harness.

add_sink_parse(launchline: str) → None

Similar to gst_harness_add_sink, this allows you to specify a launch-line instead of just an element name. See gst_harness_add_src_parse for details.

MT safe.

Added in version 1.6.

Parameters:

launchline – a utf8 with the name of a Element

add_src(src_element_name: str, has_clock_wait: bool) → None

Similar to gst_harness_add_src_harness, this is a convenience to directly create a src-harness using the src_element_name name specified.

MT safe.

Added in version 1.6.

Parameters:

  • src_element_name – a utf8 with the name of a Element

  • has_clock_wait – a gboolean specifying if the Element uses gst_clock_wait_id internally.

add_src_harness(src_harness: Harness, has_clock_wait: bool) → None

A src-harness is a great way of providing the Harness with data. By adding a src-type Element, it is then easy to use functions like gst_harness_push_from_src or gst_harness_src_crank_and_push_many to provide your harnessed element with input. The has_clock_wait variable is a great way to control you src-element with, in that you can have it produce a buffer for you by simply cranking the clock, and not have it spin out of control producing buffers as fast as possible.

If a src-harness already exists it will be replaced.

MT safe.

Added in version 1.6.

Parameters:

  • src_harness – a Harness to be added as a src-harness.

  • has_clock_wait – a gboolean specifying if the Element uses gst_clock_wait_id internally.

add_src_parse(launchline: str, has_clock_wait: bool) → None

Similar to gst_harness_add_src, this allows you to specify a launch-line, which can be useful for both having more then one Element acting as your src (Like a src producing raw buffers, and then an encoder, providing encoded data), but also by allowing you to set properties like “is-live” directly on the elements.

MT safe.

Added in version 1.6.

Parameters:

  • launchline – a utf8 describing a gst-launch type line

  • has_clock_wait – a gboolean specifying if the Element uses gst_clock_wait_id internally.

buffers_in_queue() → int

The number of Buffer currently in the Harness sinkpad AsyncQueue

MT safe.

Added in version 1.6.

buffers_received() → int

The total number of Buffer that has arrived on the Harness sinkpad. This number includes buffers that have been dropped as well as buffers that have already been pulled out.

MT safe.

Added in version 1.6.

crank_multiple_clock_waits(waits: int) → bool

Similar to crank_single_clock_wait(), this is the function to use if your harnessed element(s) are using more then one gst_clock_id_wait. Failing to do so can (and will) make it racy which ClockID you actually are releasing, where as this function will process all the waits at the same time, ensuring that one thread can’t register another wait before both are released.

MT safe.

Added in version 1.6.

Parameters:

waits – a guint describing the number of ClockID to crank

crank_single_clock_wait() → bool

A “crank” consists of three steps: 1: Wait for a ClockID to be registered with the TestClock. 2: Advance the TestClock to the time the ClockID is waiting for. 3: Release the ClockID wait. Together, this provides an easy way to not have to think about the details around clocks and time, but still being able to write deterministic tests that are dependent on this. A “crank” can be though of as the notion of manually driving the clock forward to its next logical step.

MT safe.

Added in version 1.6.

create_buffer(size: int) → Buffer

Allocates a buffer using a BufferPool if present, or else using the configured Allocator and AllocationParams

MT safe.

Added in version 1.6.

Parameters:

size – a gsize specifying the size of the buffer

dump_to_file(filename: str) → None

Allows you to dump the Buffer the Harness sinkpad AsyncQueue to a file.

MT safe.

Added in version 1.6.

Parameters:

filename – a utf8 with a the name of a file

events_in_queue() → int

The number of Event currently in the Harness sinkpad AsyncQueue

MT safe.

Added in version 1.6.

events_received() → int

The total number of Event that has arrived on the Harness sinkpad This number includes events handled by the harness as well as events that have already been pulled out.

MT safe.

Added in version 1.6.

find_element(element_name: str) → Element | None

Most useful in conjunction with gst_harness_new_parse, this will scan the Element inside the Harness, and check if any of them matches element_name. Typical usecase being that you need to access one of the harnessed elements for properties and/or signals.

MT safe.

Added in version 1.6.

Parameters:

element_name – a utf8 with a ElementFactory name

get_allocator() → tuple[Allocator, AllocationParams]

Gets the allocator and its params that has been decided to use after an allocation query.

MT safe.

Added in version 1.6.

get_last_pushed_timestamp() → int

Get the timestamp of the last Buffer pushed on the Harness srcpad, typically with gst_harness_push or gst_harness_push_from_src.

MT safe.

Added in version 1.6.

get_testclock() → TestClock | None

Get the TestClock. Useful if specific operations on the testclock is needed.

MT safe.

Added in version 1.6.

play() → None

This will set the harnessed Element to %GST_STATE_PLAYING. Element without a sink-Pad and with the %GST_ELEMENT_FLAG_SOURCE flag set is considered a src Element Non-src Element (like sinks and filters) are automatically set to playing by the Harness, but src Element are not to avoid them starting to produce buffers. Hence, for src Element you must call play() explicitly.

MT safe.

Added in version 1.6.

pull() → Buffer | None

Pulls a Buffer from the AsyncQueue on the Harness sinkpad. The pull will timeout in 60 seconds. This is the standard way of getting a buffer from a harnessed Element.

MT safe.

Added in version 1.6.

pull_event() → Event | None

Pulls an Event from the AsyncQueue on the Harness sinkpad. Timeouts after 60 seconds similar to gst_harness_pull.

MT safe.

Added in version 1.6.

pull_until_eos() → tuple[bool, Buffer]

Pulls a Buffer from the AsyncQueue on the Harness sinkpad. The pull will block until an EOS event is received, or timeout in 60 seconds. MT safe.

Added in version 1.18.

pull_upstream_event() → Event | None

Pulls an Event from the AsyncQueue on the Harness srcpad. Timeouts after 60 seconds similar to gst_harness_pull.

MT safe.

Added in version 1.6.

push(buffer: Buffer) → FlowReturn

Pushes a Buffer on the Harness srcpad. The standard way of interacting with an harnessed element.

MT safe.

Added in version 1.6.

Parameters:

buffer – a Buffer to push

push_and_pull(buffer: Buffer) → Buffer | None

Basically a gst_harness_push and a gst_harness_pull in one line. Reflects the fact that you often want to do exactly this in your test: Push one buffer in, and inspect the outcome.

MT safe.

Added in version 1.6.

Parameters:

buffer – a Buffer to push

push_event(event: Event) → bool

Pushes an Event on the Harness srcpad.

MT safe.

Added in version 1.6.

Parameters:

event – a Event to push

push_from_src() → FlowReturn

Transfer data from the src-Harness to the main-Harness. It consists of 4 steps: 1: Make sure the src is started. (see: gst_harness_play) 2: Crank the clock (see: gst_harness_crank_single_clock_wait) 3: Pull a Buffer from the src-Harness (see: gst_harness_pull) 4: Push the same Buffer into the main-Harness (see: gst_harness_push)

MT safe.

Added in version 1.6.

push_to_sink() → FlowReturn

Transfer one Buffer from the main-Harness to the sink-Harness. See gst_harness_push_from_src for details.

MT safe.

Added in version 1.6.

push_upstream_event(event: Event) → bool

Pushes an Event on the Harness sinkpad.

MT safe.

Added in version 1.6.

Parameters:

event – a Event to push

query_latency() → int

Get the min latency reported by any harnessed Element.

MT safe.

Added in version 1.6.

set_blocking_push_mode() → None

Setting this will make the harness block in the chain-function, and then release when pull() or try_pull() is called. Can be useful when wanting to control a src-element that is not implementing id_wait() so it can’t be controlled by the TestClock, since it otherwise would produce buffers as fast as possible.

MT safe.

Added in version 1.6.

set_caps(in_: Caps, out: Caps) → None

Sets the GstHarness srcpad and sinkpad caps.

MT safe.

Added in version 1.6.

Parameters:

  • in

  • out – a Caps to set on the harness sinkpad

set_caps_str(in_: str, out: str) → None

Sets the GstHarness srcpad and sinkpad caps using strings.

MT safe.

Added in version 1.6.

Parameters:

  • in

  • out – a gchar describing a Caps to set on the harness sinkpad

set_drop_buffers(drop_buffers: bool) → None

When set to True, instead of placing the buffers arriving from the harnessed Element inside the sinkpads AsyncQueue, they are instead unreffed.

MT safe.

Added in version 1.6.

Parameters:

drop_buffers – a gboolean specifying to drop outgoing buffers or not

set_forwarding(forwarding: bool) → None

As a convenience, a src-harness will forward %GST_EVENT_STREAM_START, %GST_EVENT_CAPS and %GST_EVENT_SEGMENT to the main-harness if forwarding is enabled, and forward any sticky-events from the main-harness to the sink-harness. It will also forward the %GST_QUERY_ALLOCATION.

If forwarding is disabled, the user will have to either manually push these events from the src-harness using src_push_event(), or create and push them manually. While this will allow full control and inspection of these events, for the most cases having forwarding enabled will be sufficient when writing a test where the src-harness’ main function is providing data for the main-harness.

Forwarding is enabled by default.

MT safe.

Added in version 1.6.

Parameters:

forwarding – a gboolean to enable/disable forwarding

set_live(is_live: bool) → None

Sets the liveness reported by Harness when receiving a latency-query. The default is True.

Added in version 1.20.

Parameters:

is_live – True for live, False for non-live

set_propose_allocator(allocator: Allocator | None = None, params: AllocationParams | None = None) → None

Sets the allocator and params to propose when receiving an allocation query.

MT safe.

Added in version 1.6.

Parameters:
set_sink_caps(caps: Caps) → None

Sets the GstHarness sinkpad caps.

MT safe.

Added in version 1.6.

Parameters:

caps – a Caps to set on the harness sinkpad

set_sink_caps_str(str: str) → None

Sets the GstHarness sinkpad caps using a string.

MT safe.

Added in version 1.6.

Parameters:

str – a gchar describing a Caps to set on the harness sinkpad

set_src_caps(caps: Caps) → None

Sets the GstHarness srcpad caps. This must be done before any buffers can legally be pushed from the harness to the element.

MT safe.

Added in version 1.6.

Parameters:

caps – a Caps to set on the harness srcpad

set_src_caps_str(str: str) → None

Sets the GstHarness srcpad caps using a string. This must be done before any buffers can legally be pushed from the harness to the element.

MT safe.

Added in version 1.6.

Parameters:

str – a gchar describing a Caps to set on the harness srcpad

set_time(time: int) → bool

Advance the TestClock to a specific time.

MT safe.

Added in version 1.6.

Parameters:

time – a ClockTime to advance the clock to

set_upstream_latency(latency: int) → None

Sets the min latency reported by Harness when receiving a latency-query

Added in version 1.6.

Parameters:

latency – a ClockTime specifying the latency

sink_push_many(pushes: int) → FlowReturn

Convenience that calls gst_harness_push_to_sink pushes number of times. Will abort the pushing if any one push fails.

MT safe.

Added in version 1.6.

Parameters:

pushes – a int with the number of calls to gst_harness_push_to_sink

src_crank_and_push_many(cranks: int, pushes: int) → FlowReturn

Transfer data from the src-Harness to the main-Harness. Similar to gst_harness_push_from_src, this variant allows you to specify how many cranks and how many pushes to perform. This can be useful for both moving a lot of data at the same time, as well as cases when one crank does not equal one buffer to push and v.v.

MT safe.

Added in version 1.6.

Parameters:

  • cranks – a int with the number of calls to gst_harness_crank_single_clock_wait

  • pushes – a int with the number of calls to gst_harness_push

src_push_event() → bool

Similar to what gst_harness_src_push does with Buffer, this transfers a Event from the src-Harness to the main-Harness. Note that some Event are being transferred automagically. Look at sink_forward_pad for details.

MT safe.

Added in version 1.6.

stress_thread_stop(t: HarnessThread) → int

Stop the running HarnessThread

MT safe.

Added in version 1.6.

Parameters:

t – a HarnessThread

take_all_data() → Bytes

Pulls all pending data from the harness and returns it as a single data slice.

Added in version 1.14.

take_all_data_as_buffer() → Buffer

Pulls all pending data from the harness and returns it as a single buffer.

Added in version 1.14.

teardown() → None

Tears down a GstHarness, freeing all resources allocated using it.

MT safe.

Added in version 1.6.

try_pull() → Buffer | None

Pulls a Buffer from the AsyncQueue on the Harness sinkpad. Unlike gst_harness_pull this will not wait for any buffers if not any are present, and return None straight away.

MT safe.

Added in version 1.6.

try_pull_event() → Event | None

Pulls an Event from the AsyncQueue on the Harness sinkpad. See gst_harness_try_pull for details.

MT safe.

Added in version 1.6.

try_pull_upstream_event() → Event | None

Pulls an Event from the AsyncQueue on the Harness srcpad. See gst_harness_try_pull for details.

MT safe.

Added in version 1.6.

upstream_events_in_queue() → int

The number of Event currently in the Harness srcpad AsyncQueue

MT safe.

Added in version 1.6.

upstream_events_received() → int

The total number of Event that has arrived on the Harness srcpad This number includes events handled by the harness as well as events that have already been pulled out.

MT safe.

Added in version 1.6.

use_systemclock() → None

Sets the system Clock on the GstHarness Element

MT safe.

Added in version 1.6.

use_testclock() → None

Sets the TestClock on the Harness Element

MT safe.

Added in version 1.6.

wait_for_clock_id_waits(waits: int, timeout: int) → bool

Waits for timeout seconds until waits number of ClockID waits is registered with the TestClock. Useful for writing deterministic tests, where you want to make sure that an expected number of waits have been reached.

MT safe.

Added in version 1.6.

Parameters:

  • waits – a guint describing the numbers of ClockID registered with the TestClock

  • timeout – a guint describing how many seconds to wait for waits to be true

Fields

class Harness
element

The element inside the harness

priv
sink_harness

The sink (output) harness (if any)

sinkpad

The internal harness sink pad

src_harness

The source (input) harness (if any)

srcpad

The internal harness source pad