Gjsify LogoGjsify Logo

#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 gst_harness_set_src_caps() or gst_harness_set_sink_caps_str(),
you can test how the #GstElement interacts with different caps sets.

Your harnessed #GstElement 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 #GstBuffers and #GstEvents on to the srcpad,
using functions like gst_harness_push() and gst_harness_push_event(), and
then pull them out to examine them with gst_harness_pull() and
gst_harness_pull_event().

## A simple buffer-in buffer-out example


```c
#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:

  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);

@record

Hierarchy

  • Harness

Index

Constructors

Properties

element: Gst.Element

the element inside the harness

field
sinkHarness: Harness

the sink (output) harness (if any)

field
sinkpad: Gst.Pad

the internal harness sink pad

field
srcHarness: Harness

the source (input) harness (if any)

field
srcpad: Gst.Pad

the internal harness source pad

field
name: string

Methods

  • addElementSinkPad(sinkpad: Gst.Pad): void
  • Links the specified #GstPad the GstHarness srcpad.

    MT safe.

    Parameters

    • sinkpad: Gst.Pad

      a #GstPad to link to the harness srcpad

    Returns void

  • addElementSrcPad(srcpad: Gst.Pad): void
  • Links the specified #GstPad 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.

    Parameters

    • srcpad: Gst.Pad

      a #GstPad to link to the harness sinkpad

    Returns void

  • A convenience function to allows you to call gst_pad_add_probe on a #GstPad of a #GstElement that are residing inside the #GstHarness, by using normal gst_pad_add_probe syntax

    MT safe.

    Parameters

    • elementName: string

      a #gchar with a #GstElementFactory name

    • padName: string

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

    • mask: PadProbeType

      a #GstPadProbeType (see gst_pad_add_probe)

    • callback: PadProbeCallback

      a #GstPadProbeCallback (see gst_pad_add_probe)

    Returns void

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

    MT safe.

    Parameters

    Returns void

  • addSink(sinkElementName: string): void
  • 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.

    Parameters

    • sinkElementName: string

      a #gchar with the name of a #GstElement

    Returns void

  • addSinkHarness(sinkHarness: Harness): void
  • Similar to gst_harness_add_src, this allows you to send the data coming out of your harnessed #GstElement 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.

    Parameters

    • sinkHarness: Harness

      a #GstHarness to be added as a sink-harness.

    Returns void

  • addSinkParse(launchline: string): void
  • 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.

    Parameters

    • launchline: string

      a #gchar with the name of a #GstElement

    Returns void

  • addSrc(srcElementName: string, hasClockWait: boolean): void
  • 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.

    Parameters

    • srcElementName: string

      a #gchar with the name of a #GstElement

    • hasClockWait: boolean

      a #gboolean specifying if the #GstElement uses gst_clock_wait_id internally.

    Returns void

  • addSrcHarness(srcHarness: Harness, hasClockWait: boolean): void
  • A src-harness is a great way of providing the #GstHarness with data. By adding a src-type #GstElement, 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.

    Parameters

    • srcHarness: Harness

      a #GstHarness to be added as a src-harness.

    • hasClockWait: boolean

      a #gboolean specifying if the #GstElement uses gst_clock_wait_id internally.

    Returns void

  • addSrcParse(launchline: string, hasClockWait: boolean): void
  • Similar to gst_harness_add_src, this allows you to specify a launch-line, which can be useful for both having more then one #GstElement 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.

    Parameters

    • launchline: string

      a #gchar describing a gst-launch type line

    • hasClockWait: boolean

      a #gboolean specifying if the #GstElement uses gst_clock_wait_id internally.

    Returns void

  • buffersInQueue(): number
  • The number of #GstBuffers currently in the #GstHarness sinkpad #GAsyncQueue

    MT safe.

    Returns number

  • buffersReceived(): number
  • The total number of #GstBuffers that has arrived on the #GstHarness sinkpad. This number includes buffers that have been dropped as well as buffers that have already been pulled out.

    MT safe.

    Returns number

  • crankMultipleClockWaits(waits: number): boolean
  • Similar to gst_harness_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 #GstClockID 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.

    Parameters

    • waits: number

      a #guint describing the number of #GstClockIDs to crank

    Returns boolean

  • crankSingleClockWait(): boolean
  • A "crank" consists of three steps: 1: Wait for a #GstClockID to be registered with the #GstTestClock. 2: Advance the #GstTestClock to the time the #GstClockID is waiting for. 3: Release the #GstClockID 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.

    Returns boolean

  • Allocates a buffer using a #GstBufferPool if present, or else using the configured #GstAllocator and #GstAllocationParams

    MT safe.

    Parameters

    • size: number

      a #gsize specifying the size of the buffer

    Returns Gst.Buffer

  • dumpToFile(filename: string): void
  • Allows you to dump the #GstBuffers the #GstHarness sinkpad #GAsyncQueue to a file.

    MT safe.

    Parameters

    • filename: string

      a #gchar with a the name of a file

    Returns void

  • eventsInQueue(): number
  • The number of #GstEvents currently in the #GstHarness sinkpad #GAsyncQueue

    MT safe.

    Returns number

  • eventsReceived(): number
  • The total number of #GstEvents that has arrived on the #GstHarness sinkpad This number includes events handled by the harness as well as events that have already been pulled out.

    MT safe.

    Returns number

  • Most useful in conjunction with gst_harness_new_parse, this will scan the #GstElements inside the #GstHarness, 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.

    Parameters

    • elementName: string

      a #gchar with a #GstElementFactory name

    Returns Gst.Element

  • getLastPushedTimestamp(): number
  • Get the timestamp of the last #GstBuffer pushed on the #GstHarness srcpad, typically with gst_harness_push or gst_harness_push_from_src.

    MT safe.

    Returns number

  • play(): void
  • This will set the harnessed #GstElement to %GST_STATE_PLAYING. #GstElements without a sink-#GstPad and with the %GST_ELEMENT_FLAG_SOURCE flag set is considered a src #GstElement Non-src #GstElements (like sinks and filters) are automatically set to playing by the #GstHarness, but src #GstElements are not to avoid them starting to produce buffers. Hence, for src #GstElement you must call gst_harness_play() explicitly.

    MT safe.

    Returns void

  • Pulls a #GstBuffer from the #GAsyncQueue on the #GstHarness sinkpad. The pull will timeout in 60 seconds. This is the standard way of getting a buffer from a harnessed #GstElement.

    MT safe.

    Returns Gst.Buffer

  • Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness sinkpad. Timeouts after 60 seconds similar to gst_harness_pull.

    MT safe.

    Returns Gst.Event

  • Pulls a #GstBuffer from the #GAsyncQueue on the #GstHarness sinkpad. The pull will block until an EOS event is received, or timeout in 60 seconds. MT safe.

    Returns [boolean, Gst.Buffer]

  • Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness srcpad. Timeouts after 60 seconds similar to gst_harness_pull.

    MT safe.

    Returns Gst.Event

  • Pushes a #GstBuffer on the #GstHarness srcpad. The standard way of interacting with an harnessed element.

    MT safe.

    Parameters

    Returns Gst.FlowReturn

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

    Parameters

    Returns Gst.Buffer

  • Pushes an #GstEvent on the #GstHarness srcpad.

    MT safe.

    Parameters

    Returns boolean

  • Transfer data from the src-#GstHarness to the main-#GstHarness. 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 #GstBuffer from the src-#GstHarness (see: gst_harness_pull) 4: Push the same #GstBuffer into the main-#GstHarness (see: gst_harness_push)

    MT safe.

    Returns Gst.FlowReturn

  • Transfer one #GstBuffer from the main-#GstHarness to the sink-#GstHarness. See gst_harness_push_from_src for details.

    MT safe.

    Returns Gst.FlowReturn

  • pushUpstreamEvent(event: Gst.Event): boolean
  • Pushes an #GstEvent on the #GstHarness sinkpad.

    MT safe.

    Parameters

    Returns boolean

  • queryLatency(): number
  • Get the min latency reported by any harnessed #GstElement.

    MT safe.

    Returns number

  • setBlockingPushMode(): void
  • Setting this will make the harness block in the chain-function, and then release when gst_harness_pull() or gst_harness_try_pull() is called. Can be useful when wanting to control a src-element that is not implementing gst_clock_id_wait() so it can't be controlled by the #GstTestClock, since it otherwise would produce buffers as fast as possible.

    MT safe.

    Returns void

  • Sets the GstHarness srcpad and sinkpad caps.

    MT safe.

    Parameters

    • in_: Gst.Caps

      a #GstCaps to set on the harness srcpad

    • out: Gst.Caps

      a #GstCaps to set on the harness sinkpad

    Returns void

  • setCapsStr(in_: string, out: string): void
  • Sets the GstHarness srcpad and sinkpad caps using strings.

    MT safe.

    Parameters

    • in_: string

      a gchar describing a #GstCaps to set on the harness srcpad

    • out: string

      a gchar describing a #GstCaps to set on the harness sinkpad

    Returns void

  • setDropBuffers(dropBuffers: boolean): void
  • When set to %TRUE, instead of placing the buffers arriving from the harnessed #GstElement inside the sinkpads #GAsyncQueue, they are instead unreffed.

    MT safe.

    Parameters

    • dropBuffers: boolean

      a #gboolean specifying to drop outgoing buffers or not

    Returns void

  • setForwarding(forwarding: boolean): void
  • 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 gst_harness_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.

    Parameters

    • forwarding: boolean

      a #gboolean to enable/disable forwarding

    Returns void

  • setLive(isLive: boolean): void
  • Sets the liveness reported by #GstHarness when receiving a latency-query. The default is %TRUE.

    Parameters

    • isLive: boolean

      %TRUE for live, %FALSE for non-live

    Returns void

  • Sets the GstHarness sinkpad caps.

    MT safe.

    Parameters

    • caps: Gst.Caps

      a #GstCaps to set on the harness sinkpad

    Returns void

  • setSinkCapsStr(str: string): void
  • Sets the GstHarness sinkpad caps using a string.

    MT safe.

    Parameters

    • str: string

      a gchar describing a #GstCaps to set on the harness sinkpad

    Returns void

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

    MT safe.

    Parameters

    • caps: Gst.Caps

      a #GstCaps to set on the harness srcpad

    Returns void

  • setSrcCapsStr(str: string): void
  • 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.

    Parameters

    • str: string

      a gchar describing a #GstCaps to set on the harness srcpad

    Returns void

  • setTime(time: number): boolean
  • Advance the #GstTestClock to a specific time.

    MT safe.

    Parameters

    • time: number

      a #GstClockTime to advance the clock to

    Returns boolean

  • setUpstreamLatency(latency: number): void
  • Sets the min latency reported by #GstHarness when receiving a latency-query

    Parameters

    • latency: number

      a #GstClockTime specifying the latency

    Returns void

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

    MT safe.

    Parameters

    • pushes: number

      a #gint with the number of calls to gst_harness_push_to_sink

    Returns Gst.FlowReturn

  • srcCrankAndPushMany(cranks: number, pushes: number): Gst.FlowReturn
  • Transfer data from the src-#GstHarness to the main-#GstHarness. 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.

    Parameters

    • cranks: number

      a #gint with the number of calls to gst_harness_crank_single_clock_wait

    • pushes: number

      a #gint with the number of calls to gst_harness_push

    Returns Gst.FlowReturn

  • srcPushEvent(): boolean
  • Similar to what gst_harness_src_push does with #GstBuffers, this transfers a #GstEvent from the src-#GstHarness to the main-#GstHarness. Note that some #GstEvents are being transferred automagically. Look at sink_forward_pad for details.

    MT safe.

    Returns boolean

  • takeAllData(): any
  • Pulls all pending data from the harness and returns it as a single #GBytes.

    Returns any

  • teardown(): void
  • Tears down a GstHarness, freeing all resources allocated using it.

    MT safe.

    Returns void

  • Pulls a #GstBuffer from the #GAsyncQueue on the #GstHarness sinkpad. Unlike gst_harness_pull this will not wait for any buffers if not any are present, and return %NULL straight away.

    MT safe.

    Returns Gst.Buffer

  • Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness sinkpad. See gst_harness_try_pull for details.

    MT safe.

    Returns Gst.Event

  • Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness srcpad. See gst_harness_try_pull for details.

    MT safe.

    Returns Gst.Event

  • upstreamEventsInQueue(): number
  • The number of #GstEvents currently in the #GstHarness srcpad #GAsyncQueue

    MT safe.

    Returns number

  • upstreamEventsReceived(): number
  • The total number of #GstEvents that has arrived on the #GstHarness srcpad This number includes events handled by the harness as well as events that have already been pulled out.

    MT safe.

    Returns number

  • useSystemclock(): void
  • Sets the system #GstClock on the GstHarness #GstElement

    MT safe.

    Returns void

  • useTestclock(): void
  • waitForClockIdWaits(waits: number, timeout: number): boolean
  • Waits for timeout seconds until waits number of #GstClockID waits is registered with the #GstTestClock. Useful for writing deterministic tests, where you want to make sure that an expected number of waits have been reached.

    MT safe.

    Parameters

    • waits: number

      a #guint describing the numbers of #GstClockID registered with the #GstTestClock

    • timeout: number

      a #guint describing how many seconds to wait for waits to be true

    Returns boolean

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Type alias with type parameter
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method