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" Pads that connect to the
harnessed Element src and sink Pads 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 Pads, 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 gst_harness_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 Buffers and Events on to the srcpad, using functions
like push and
push_event, and then pull them out to examine them with pull and
pull_event.
typeof (unichar2)typeof
(unichar2) 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);
- public void add_element_sink_pad (Pad sinkpad)
Links the specified Pad the
GstHarness srcpad.
- public void add_element_src_pad (Pad srcpad)
Links the specified Pad the
GstHarness sinkpad.
- public void add_probe (string element_name, string pad_name, PadProbeType mask, owned PadProbeCallback callback)
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
- public void add_propose_allocation_meta (Type api, Structure? @params)
Add api with params as one of the supported metadata API to propose
when receiving an allocation query.
- public void add_sink (string sink_element_name)
Similar to gst_harness_add_sink_harness, this is a convenience to
directly create a sink-harness using the sink_element_name name specified.
- public void add_sink_harness (owned Harness sink_harness)
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.
- public void add_sink_parse (string launchline)
Similar to gst_harness_add_sink, this allows you to specify a
launch-line instead of just an element name.
- public void add_src (string src_element_name, bool has_clock_wait)
Similar to gst_harness_add_src_harness, this is a convenience to
directly create a src-harness using the src_element_name name specified.
- public void add_src_harness (owned Harness src_harness, bool has_clock_wait)
A src-harness is a great way of providing the
Harness with data.
- public void add_src_parse (string launchline, bool has_clock_wait)
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.
- public uint buffers_in_queue ()
The number of Buffers currently in the
Harness sinkpad AsyncQueue
- public uint buffers_received ()
The total number of Buffers that has
arrived on the Harness sinkpad.
- public bool crank_multiple_clock_waits (uint waits)
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.
- public bool crank_single_clock_wait ()
A "crank" consists of three steps: 1: Wait for a
ClockID to be registered with the TestClock.
- public Buffer create_buffer (size_t size)
Allocates a buffer using a BufferPool if
present, or else using the configured Allocator and AllocationParams
- public void dump_to_file (string filename)
Allows you to dump the Buffers the
Harness sinkpad AsyncQueue to a file.
- public uint events_in_queue ()
The number of Events currently in the
Harness sinkpad AsyncQueue
- public uint events_received ()
The total number of Events 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.
- public Element? find_element (string element_name)
Most useful in conjunction with gst_harness_new_parse, this will scan
the Elements inside the Harness, and check if any of them matches
element_name.
- public void get_allocator (out unowned Allocator allocator, out AllocationParams @params)
Gets the allocator and its params that has
been decided to use after an allocation query.
- public ClockTime get_last_pushed_timestamp ()
Get the timestamp of the last Buffer pushed
on the Harness srcpad, typically with gst_harness_push or gst_harness_push_from_src.
- public TestClock get_testclock ()
- public void play ()
This will set the harnessed Element
to PLAYING.
- public Buffer pull ()
Pulls a Buffer from the
AsyncQueue on the Harness sinkpad.
- public Event pull_event ()
Pulls an Event from the
AsyncQueue on the Harness sinkpad.
- public bool pull_until_eos (out Buffer buf)
Pulls a Buffer from the
AsyncQueue on the Harness sinkpad.
- public Event pull_upstream_event ()
Pulls an Event from the
AsyncQueue on the Harness srcpad.
- public FlowReturn push (owned Buffer buffer)
Pushes a Buffer on the
Harness srcpad.
- public Buffer push_and_pull (owned Buffer buffer)
Basically a gst_harness_push and a gst_harness_pull in one line.
- public bool push_event (Event event)
Pushes an Event on the
Harness srcpad.
- public FlowReturn push_from_src ()
Transfer data from the src-#GstHarness to the main-#GstHarness.
- public FlowReturn push_to_sink ()
Transfer one Buffer from the
main-#GstHarness to the sink-#GstHarness.
- public bool push_upstream_event (Event event)
Pushes an Event on the
Harness sinkpad.
- public ClockTime query_latency ()
Get the min latency reported by any harnessed
Element.
- public void set_blocking_push_mode ()
Setting this will make the harness block in the chain-function, and
then release when pull or
try_pull is called.
- public void set_caps (owned Caps @in, owned Caps @out)
Sets the GstHarness srcpad and sinkpad caps.
- public void set_caps_str (string @in, string @out)
Sets the GstHarness srcpad and sinkpad caps using
strings.
- public void set_drop_buffers (bool drop_buffers)
When set to true, instead of placing the buffers arriving
from the harnessed Element inside the sinkpads AsyncQueue, they are
instead unreffed.
- public void set_forwarding (bool forwarding)
As a convenience, a src-harness will forward
STREAM_START, CAPS and SEGMENT to the main-harness if
forwarding is enabled, and forward any sticky-events from the main-harness to the sink-harness.
- public void set_live (bool is_live)
Sets the liveness reported by Harness when
receiving a latency-query.
- public void set_propose_allocator (owned Allocator? allocator, AllocationParams? @params)
Sets the allocator and params to propose
when receiving an allocation query.
- public void set_sink_caps (owned Caps caps)
Sets the GstHarness sinkpad caps.
- public void set_sink_caps_str (string str)
Sets the GstHarness sinkpad caps using a string.
- public void set_src_caps (owned Caps caps)
Sets the GstHarness srcpad caps.
- public void set_src_caps_str (string str)
Sets the GstHarness srcpad caps using a string.
- public bool set_time (ClockTime time)
- public void set_upstream_latency (ClockTime latency)
Sets the min latency reported by Harness
when receiving a latency-query
- public FlowReturn sink_push_many (int pushes)
Convenience that calls gst_harness_push_to_sink pushes
number of times.
- public FlowReturn src_crank_and_push_many (int cranks, int pushes)
Transfer data from the src-#GstHarness to the main-#GstHarness.
- public bool src_push_event ()
Similar to what gst_harness_src_push does with
Buffers, this transfers a Event from the src-#GstHarness to the main-#GstHarness.
- public Buffer take_all_data_as_buffer ()
Pulls all pending data from the harness and returns it as a single
buffer.
- public Bytes take_all_data_as_bytes ()
Pulls all pending data from the harness and returns it as a single
Bytes.
- public void teardown ()
Tears down a GstHarness, freeing all resources allocated
using it.
- public Buffer try_pull ()
Pulls a Buffer from the
AsyncQueue on the Harness sinkpad.
- public Event try_pull_event ()
Pulls an Event from the
AsyncQueue on the Harness sinkpad.
- public Event try_pull_upstream_event ()
Pulls an Event from the
AsyncQueue on the Harness srcpad.
- public uint upstream_events_in_queue ()
The number of Events currently in the
Harness srcpad AsyncQueue
- public uint upstream_events_received ()
The total number of Events 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.
- public void use_systemclock ()
Sets the system Clock on the
GstHarness Element
- public void use_testclock ()
- public bool wait_for_clock_id_waits (uint waits, uint timeout)
Waits for timeout seconds until waits number
of ClockID waits is registered with the TestClock.