Struct gstreamer_check::harness::Harness[−][src]

pub struct Harness(_);

Expand description

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

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

  #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 gst_harness_crank_single_clock_wait().

#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 gst_harness_add_src() or
gst_harness_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:

|[<!-- language="C" -->
  GstHarness * h = gst_harness_new (h, "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);

Implementations

impl Harness[src]

pub fn add_element_full<P: IsA<Element>>(
    &mut self, 
    element: &P, 
    hsrc: Option<&StaticPadTemplate>, 
    element_sinkpad_name: Option<&str>, 
    hsink: Option<&StaticPadTemplate>, 
    element_srcpad_name: Option<&str>
)

[src]

Adds a gst::Element to an empty Harness

MT safe.

`element`

a gst::Element to add to the harness (transfer none)

`hsrc`

a gst::StaticPadTemplate describing the harness srcpad. None will not create a harness srcpad.

`element_sinkpad_name`

a gchar with the name of the element sinkpad that is then linked to the harness srcpad. Can be a static or request or a sometimes pad that has been added. None will not get/request a sinkpad from the element. (Like if the element is a src.)

`hsink`

a gst::StaticPadTemplate describing the harness sinkpad. None will not create a harness sinkpad.

`element_srcpad_name`

a gchar with the name of the element srcpad that is then linked to the harness sinkpad, similar to the element_sinkpad_name.

pub fn add_element_sink_pad<P: IsA<Pad>>(&mut self, sinkpad: &P)[src]

Links the specified gst::Pad the Harness srcpad.

MT safe.

`sinkpad`

a gst::Pad to link to the harness srcpad

pub fn add_element_src_pad<P: IsA<Pad>>(&mut self, srcpad: &P)[src]

Links the specified gst::Pad the Harness 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.

`srcpad`

a gst::Pad to link to the harness sinkpad

pub fn add_parse(&mut self, launchline: &str)[src]

Parses the launchline and puts that in a gst::Bin, and then attches the supplied Harness to the bin.

MT safe.

`launchline`

a gchar describing a gst-launch type line

pub fn add_probe<F>(
    &mut self, 
    element_name: &str, 
    pad_name: &str, 
    mask: PadProbeType, 
    func: F
) where
    F: Fn(&Pad, &mut PadProbeInfo<'_>) -> PadProbeReturn + Send + Sync + 'static,

[src]

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

MT safe.

`element_name`

a gchar with a gst::ElementFactory name

`pad_name`

a gchar with the name of the pad to attach the probe to

`mask`

a gst::PadProbeType (see gst_pad_add_probe)

`callback`

a GstPadProbeCallback (see gst_pad_add_probe)

`destroy_data`

a GDestroyNotify (see gst_pad_add_probe)

pub fn add_propose_allocation_meta(
    &mut self, 
    api: Type, 
    params: Option<&StructureRef>
)

[src]

This is supported on crate feature v1_16 only.

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

MT safe.

`api`

a metadata API

`params`

API specific parameters

pub fn add_sink(&mut self, sink_element_name: &str)[src]

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.

`sink_element_name`

a gchar with the name of a gst::Element

pub fn add_sink_harness(&mut self, sink_harness: Harness)[src]

Similar to gst_harness_add_src, this allows you to send the data coming out of your harnessed gst::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.

`sink_harness`

a Harness to be added as a sink-harness.

pub fn add_sink_parse(&mut self, launchline: &str)[src]

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.

`launchline`

a gchar with the name of a gst::Element

pub fn add_src(&mut self, src_element_name: &str, has_clock_wait: bool)[src]

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.

`src_element_name`

a gchar with the name of a gst::Element

`has_clock_wait`

a gboolean specifying if the gst::Element uses gst_clock_wait_id internally.

pub fn add_src_harness(&mut self, src_harness: Harness, has_clock_wait: bool)[src]

A src-harness is a great way of providing the Harness with data. By adding a src-type gst::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.

`src_harness`

a Harness to be added as a src-harness.

`has_clock_wait`

a gboolean specifying if the gst::Element uses gst_clock_wait_id internally.

pub fn add_src_parse(&mut self, launchline: &str, has_clock_wait: bool)[src]

Similar to gst_harness_add_src, this allows you to specify a launch-line, which can be useful for both having more then one gst::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.

`launchline`

a gchar describing a gst-launch type line

`has_clock_wait`

a gboolean specifying if the gst::Element uses gst_clock_wait_id internally.

pub fn buffers_in_queue(&self) -> u32[src]

The number of GstBuffers currently in the Harness sinkpad GAsyncQueue

MT safe.

Struct gstreamer_check::harness::Harness[−][src]

Implementations

Trait Implementations

Auto Trait Implementations

Blanket Implementations