gstcheck.harness

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

The basic structure of #GstHarness is two "floating" #GstPads that connect to the harnessed #GstElement src and sink #GstPads like so:

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

With this, you can now simulate any environment the #GstElement might find itself in. By specifying the #GstCaps of the harness #GstPads, using functions like [gstcheck.harness.Harness.setSrcCaps] or [gstcheck.harness.Harness.setSinkCapsStr], you can test how the #GstElement interacts with different caps sets.

Your harnessed #GstElement can of course also be a bin, and using [gstcheck.harness.Harness.newParse] supporting standard gst-launch syntax, you can easily test a whole pipeline instead of just one element.

You can then go on to push #GstBuffers and #GstEvents on to the srcpad, using functions like [gstcheck.harness.Harness.push] and [gstcheck.harness.Harness.pushEvent], and then pull them out to examine them with [gstcheck.harness.Harness.pull] and [gstcheck.harness.Harness.pullEvent].

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 #GstHarness is its integration with the #GstTestClock. Operating the #GstTestClock can be very challenging, but #GstHarness simplifies some of the most desired actions a lot, like wanting to manually advance the clock while at the same time releasing a #GstClockID that is waiting, with functions like [gstcheck.harness.Harness.crankSingleClockWait].

#GstHarness also supports sub-harnesses, as a way of generating and validating data. A sub-harness is another #GstHarness 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 [gstcheck.harness.Harness.addSrc] or [gstcheck.harness.Harness.addSinkParse]. 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);