#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 |[<!-- language="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: |[<!-- 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: |[<!-- language="C" --> gst_harness_push_from_src (h); ]| the element inside the harness the internal harness source pad the internal harness sink pad the source (input) harness (if any) the sink (output) harness (if any) Adds a #GstElement to an empty #GstHarness MT safe. a #GstHarness a #GstElement to add to the harness (transfer none) a #GstStaticPadTemplate describing the harness srcpad. %NULL will not create a harness srcpad. 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. %NULL will not get/request a sinkpad from the element. (Like if the element is a src.) a #GstStaticPadTemplate describing the harness sinkpad. %NULL will not create a harness sinkpad. a #gchar with the name of the element srcpad that is then linked to the harness sinkpad, similar to the @element_sinkpad_name. Links the specified #GstPad the @GstHarness srcpad. MT safe. a #GstHarness a #GstPad to link to the harness srcpad 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. a #GstHarness a #GstPad to link to the harness sinkpad Parses the @launchline and puts that in a #GstBin, and then attches the supplied #GstHarness to the bin. MT safe. a #GstHarness a #gchar describing a gst-launch type line 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. a #GstHarness a #gchar with a #GstElementFactory name a #gchar with the name of the pad to attach the probe to a #GstPadProbeType (see gst_pad_add_probe) a #GstPadProbeCallback (see gst_pad_add_probe) a #gpointer (see gst_pad_add_probe) a #GDestroyNotify (see gst_pad_add_probe) Add api with params as one of the supported metadata API to propose when receiving an allocation query. MT safe. a #GstHarness a metadata API API specific parameters 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. a #GstHarness a #gchar with the name of a #GstElement 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. a #GstHarness a #GstHarness to be added as a sink-harness. 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. a #GstHarness a #gchar with the name of a #GstElement 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. a #GstHarness a #gchar with the name of a #GstElement a #gboolean specifying if the #GstElement uses gst_clock_wait_id internally. 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. a #GstHarness a #GstHarness to be added as a src-harness. a #gboolean specifying if the #GstElement uses gst_clock_wait_id internally. 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. a #GstHarness a #gchar describing a gst-launch type line a #gboolean specifying if the #GstElement uses gst_clock_wait_id internally. The number of #GstBuffers currently in the #GstHarness sinkpad #GAsyncQueue MT safe. a #guint number of buffers in the queue a #GstHarness 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. a #guint number of buffers received a #GstHarness 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. a @gboolean %TRUE if the "crank" was successful, %FALSE if not. a #GstHarness a #guint describing the number of #GstClockIDs to crank 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. a @gboolean %TRUE if the "crank" was successful, %FALSE if not. a #GstHarness Allocates a buffer using a #GstBufferPool if present, or else using the configured #GstAllocator and #GstAllocationParams MT safe. a #GstBuffer of size @size a #GstHarness a #gsize specifying the size of the buffer Allows you to dump the #GstBuffers the #GstHarness sinkpad #GAsyncQueue to a file. MT safe. a #GstHarness a #gchar with a the name of a file The number of #GstEvents currently in the #GstHarness sinkpad #GAsyncQueue MT safe. a #guint number of events in the queue a #GstHarness 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. a #guint number of events received a #GstHarness 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. a #GstElement or %NULL if not found a #GstHarness a #gchar with a #GstElementFactory name A convenience function to allows you to call g_object_get on a #GstElement that are residing inside the #GstHarness, by using normal g_object_get syntax. MT safe. a #GstHarness a #gchar with a #GstElementFactory name a #gchar with the first property name return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Gets the @allocator and its @params that has been decided to use after an allocation query. MT safe. a #GstHarness the #GstAllocator used the #GstAllocationParams of @allocator 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. a #GstClockTime with the timestamp or %GST_CLOCK_TIME_NONE if no #GstBuffer has been pushed on the #GstHarness srcpad a #GstHarness Get the #GstTestClock. Useful if specific operations on the testclock is needed. MT safe. a #GstTestClock, or %NULL if the testclock is not present. a #GstHarness 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. a #GstHarness 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. a #GstBuffer or %NULL if timed out. a #GstHarness Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness sinkpad. Timeouts after 60 seconds similar to gst_harness_pull. MT safe. a #GstEvent or %NULL if timed out. a #GstHarness 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. %TRUE on success, %FALSE on timeout. a #GstHarness A #GstBuffer, or %NULL if EOS or timeout occures first. Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness srcpad. Timeouts after 60 seconds similar to gst_harness_pull. MT safe. a #GstEvent or %NULL if timed out. a #GstHarness Pushes a #GstBuffer on the #GstHarness srcpad. The standard way of interacting with an harnessed element. MT safe. a #GstFlowReturn with the result from the push a #GstHarness a #GstBuffer to push 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. a #GstBuffer or %NULL if timed out. a #GstHarness a #GstBuffer to push Pushes an #GstEvent on the #GstHarness srcpad. MT safe. a #gboolean with the result from the push a #GstHarness a #GstEvent to push 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. a #GstFlowReturn with the result of the push a #GstHarness Transfer one #GstBuffer from the main-#GstHarness to the sink-#GstHarness. See gst_harness_push_from_src for details. MT safe. a #GstFlowReturn with the result of the push a #GstHarness Pushes an #GstEvent on the #GstHarness sinkpad. MT safe. a #gboolean with the result from the push a #GstHarness a #GstEvent to push Get the min latency reported by any harnessed #GstElement. MT safe. a #GstClockTime with min latency a #GstHarness A convenience function to allows you to call g_object_set on a #GstElement that are residing inside the #GstHarness, by using normal g_object_set syntax. MT safe. a #GstHarness a #gchar with a #GstElementFactory name a #gchar with the first property name value for the first property, followed optionally by more name/value pairs, followed by %NULL 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. a #GstHarness Sets the @GstHarness srcpad and sinkpad caps. MT safe. a #GstHarness a #GstCaps to set on the harness srcpad a #GstCaps to set on the harness sinkpad Sets the @GstHarness srcpad and sinkpad caps using strings. MT safe. a #GstHarness a @gchar describing a #GstCaps to set on the harness srcpad a @gchar describing a #GstCaps to set on the harness sinkpad When set to %TRUE, instead of placing the buffers arriving from the harnessed #GstElement inside the sinkpads #GAsyncQueue, they are instead unreffed. MT safe. a #GstHarness a #gboolean specifying to drop outgoing buffers or not 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. a #GstHarness a #gboolean to enable/disable forwarding Sets the @allocator and @params to propose when receiving an allocation query. MT safe. a #GstHarness a #GstAllocator a #GstAllocationParams Sets the @GstHarness sinkpad caps. MT safe. a #GstHarness a #GstCaps to set on the harness sinkpad Sets the @GstHarness sinkpad caps using a string. MT safe. a #GstHarness a @gchar describing a #GstCaps to set on the harness sinkpad Sets the @GstHarness srcpad caps. This must be done before any buffers can legally be pushed from the harness to the element. MT safe. a #GstHarness a #GstCaps to set on the harness srcpad 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. a #GstHarness a @gchar describing a #GstCaps to set on the harness srcpad Advance the #GstTestClock to a specific time. MT safe. a @gboolean %TRUE if the time could be set. %FALSE if not. a #GstHarness a #GstClockTime to advance the clock to Sets the min latency reported by #GstHarness when receiving a latency-query a #GstHarness a #GstClockTime specifying the latency Convenience that calls gst_harness_push_to_sink @pushes number of times. Will abort the pushing if any one push fails. MT safe. a #GstFlowReturn with the result of the push a #GstHarness a #gint with the number of calls to gst_harness_push_to_sink 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. a #GstFlowReturn with the result of the push a #GstHarness a #gint with the number of calls to gst_harness_crank_single_clock_wait a #gint with the number of calls to gst_harness_push 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. a #gboolean with the result of the push a #GstHarness Start a custom stress-thread that will call your @callback for every iteration allowing you to do something nasty. MT safe. a #GstHarnessThread a #GstHarness a #GFunc that is called initially and only once a #GFunc that is called as often as possible a #gpointer with custom data to pass to the @callback function a #gulong specifying how long to sleep in (microseconds) for each call to the @callback Call g_object_set with @name and @value in intervals of @sleep microseconds MT safe. a #GstHarnessThread a #GstHarness a #gchar specifying a property name a #GValue to set the property to a #gulong specifying how long to sleep in (microseconds) for each g_object_set with @name and @value Push a #GstBuffer in intervals of @sleep microseconds. MT safe. a #GstHarnessThread a #GstHarness a #GstCaps for the #GstBuffer a #GstSegment a #GstBuffer to push a #gulong specifying how long to sleep in (microseconds) for each call to gst_pad_push Push a #GstBuffer returned by @func in intervals of @sleep microseconds. MT safe. a #GstHarnessThread a #GstHarness a #GstCaps for the #GstBuffer a #GstSegment a #GstHarnessPrepareBufferFunc function called before every iteration to prepare / create a #GstBuffer for pushing a #gpointer with data to the #GstHarnessPrepareBufferFunc function a #GDestroyNotify that is called when thread is stopped a #gulong specifying how long to sleep in (microseconds) for each call to gst_pad_push Push the @event onto the harnessed #GstElement sinkpad in intervals of @sleep microseconds MT safe. a #GstHarnessThread a #GstHarness a #GstEvent to push a #gulong specifying how long to sleep in (microseconds) for each gst_event_push with @event Push a #GstEvent returned by @func onto the harnessed #GstElement sinkpad in intervals of @sleep microseconds. MT safe. a #GstHarnessThread a #GstHarness a #GstHarnessPrepareEventFunc function called before every iteration to prepare / create a #GstEvent for pushing a #gpointer with data to the #GstHarnessPrepareEventFunc function a #GDestroyNotify that is called when thread is stopped a #gulong specifying how long to sleep in (microseconds) for each call to gst_pad_push Push the @event onto the harnessed #GstElement srcpad in intervals of @sleep microseconds. MT safe. a #GstHarnessThread a #GstHarness a #GstEvent to push a #gulong specifying how long to sleep in (microseconds) for each gst_event_push with @event Push a #GstEvent returned by @func onto the harnessed #GstElement srcpad in intervals of @sleep microseconds. MT safe. a #GstHarnessThread a #GstHarness a #GstHarnessPrepareEventFunc function called before every iteration to prepare / create a #GstEvent for pushing a #gpointer with data to the #GstHarnessPrepareEventFunc function a #GDestroyNotify that is called when thread is stopped a #gulong specifying how long to sleep in (microseconds) for each call to gst_pad_push Call gst_element_request_pad in intervals of @sleep microseconds MT safe. a #GstHarnessThread a #GstHarness a #GstPadTemplate a #gchar a #GstCaps a #gboolean a #gulong specifying how long to sleep in (microseconds) for each gst_element_request_pad Change the state of your harnessed #GstElement from NULL to PLAYING and back again, only pausing for @sleep microseconds every time. MT safe. a #GstHarnessThread a #GstHarness a #gulong specifying how long to sleep in (microseconds) for each state-change Pulls all pending data from the harness and returns it as a single data slice. a pointer to the data, newly allocated. Free with g_free() when no longer needed. Will return %NULL if there is no data. a #GstHarness the size of the data in bytes Pulls all pending data from the harness and returns it as a single buffer. the data as a buffer. Unref with gst_buffer_unref() when no longer needed. a #GstHarness Pulls all pending data from the harness and returns it as a single #GBytes. a pointer to the data, newly allocated. Free with g_free() when no longer needed. a #GstHarness Tears down a @GstHarness, freeing all resources allocated using it. MT safe. a #GstHarness 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. a #GstBuffer or %NULL if no buffers are present in the #GAsyncQueue a #GstHarness Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness sinkpad. See gst_harness_try_pull for details. MT safe. a #GstEvent or %NULL if no buffers are present in the #GAsyncQueue a #GstHarness Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness srcpad. See gst_harness_try_pull for details. MT safe. a #GstEvent or %NULL if no buffers are present in the #GAsyncQueue a #GstHarness The number of #GstEvents currently in the #GstHarness srcpad #GAsyncQueue MT safe. a #guint number of events in the queue a #GstHarness 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. a #guint number of events received a #GstHarness Sets the system #GstClock on the @GstHarness #GstElement MT safe. a #GstHarness Sets the #GstTestClock on the #GstHarness #GstElement MT safe. a #GstHarness 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. a @gboolean %TRUE if the waits have been registered, %FALSE if not. (Could be that it timed out waiting or that more waits than waits was found) a #GstHarness a #guint describing the numbers of #GstClockID registered with the #GstTestClock a #guint describing how many seconds to wait for @waits to be true Creates a new harness. Works like gst_harness_new_with_padnames(), except it assumes the #GstElement sinkpad is named "sink" and srcpad is named "src" MT safe. a #GstHarness, or %NULL if the harness could not be created a #gchar describing the #GstElement name Creates a new empty harness. Use gst_harness_add_element_full() to add an #GstElement to it. MT safe. a #GstHarness, or %NULL if the harness could not be created Creates a new harness. MT safe. a #GstHarness, or %NULL if the harness could not be created a #GstElement to attach the harness to (transfer none) a #GstStaticPadTemplate describing the harness srcpad. %NULL will not create a harness srcpad. 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. %NULL will not get/request a sinkpad from the element. (Like if the element is a src.) a #GstStaticPadTemplate describing the harness sinkpad. %NULL will not create a harness sinkpad. a #gchar with the name of the element srcpad that is then linked to the harness sinkpad, similar to the @element_sinkpad_name. Creates a new harness, parsing the @launchline and putting that in a #GstBin, and then attches the harness to the bin. MT safe. a #GstHarness, or %NULL if the harness could not be created a #gchar describing a gst-launch type line Creates a new harness. Works in the same way as gst_harness_new_full(), only that generic padtemplates are used for the harness src and sinkpads, which will be sufficient in most usecases. MT safe. a #GstHarness, or %NULL if the harness could not be created a #GstElement to attach the harness to (transfer none) a #gchar with the name of the element sinkpad that is then linked to the harness srcpad. %NULL does not attach a sinkpad a #gchar with the name of the element srcpad that is then linked to the harness sinkpad. %NULL does not attach a srcpad Creates a new harness. Works like gst_harness_new_with_element(), except you specify the factoryname of the #GstElement MT safe. a #GstHarness, or %NULL if the harness could not be created a #gchar describing the #GstElement name a #gchar with the name of the element sinkpad that is then linked to the harness srcpad. %NULL does not attach a sinkpad a #gchar with the name of the element srcpad that is then linked to the harness sinkpad. %NULL does not attach a srcpad Creates a new harness, like gst_harness_new_full(), except it assumes the #GstElement sinkpad is named "sink" and srcpad is named "src" MT safe. a #GstHarness, or %NULL if the harness could not be created a #gchar describing the #GstElement name a #GstStaticPadTemplate describing the harness srcpad. %NULL will not create a harness srcpad. a #GstStaticPadTemplate describing the harness sinkpad. %NULL will not create a harness sinkpad. Stop the running #GstHarnessThread MT safe. a #GstHarnessThread a #GstHarness user data a #GstHarness user data Opaque handle representing a GstHarness stress testing thread. wrapper for checks START_TEST test function name Opaque consistency checker handle. GstTestClock is an implementation of #GstClock which has different behaviour compared to #GstSystemClock. Time for #GstSystemClock advances according to the system time, while time for #GstTestClock changes only when gst_test_clock_set_time() or gst_test_clock_advance_time() are called. #GstTestClock provides unit tests with the possibility to precisely advance the time in a deterministic manner, independent of the system time or any other external factors. ## Advancing the time of a #GstTestClock |[<!-- language="C" --> #include <gst/gst.h> #include <gst/check/gsttestclock.h> GstClock *clock; GstTestClock *test_clock; clock = gst_test_clock_new (); test_clock = GST_TEST_CLOCK (clock); GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); gst_test_clock_advance_time ( test_clock, 1 * GST_SECOND); GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); g_usleep (10 * G_USEC_PER_SEC); GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); gst_test_clock_set_time (test_clock, 42 * GST_SECOND); GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); ... ]| #GstClock allows for setting up single shot or periodic clock notifications as well as waiting for these notifications synchronously (using gst_clock_id_wait()) or asynchronously (using gst_clock_id_wait_async() or gst_clock_id_wait_async()). This is used by many GStreamer elements, among them #GstBaseSrc and #GstBaseSink. #GstTestClock keeps track of these clock notifications. By calling gst_test_clock_wait_for_next_pending_id() or gst_test_clock_wait_for_multiple_pending_ids() a unit tests may wait for the next one or several clock notifications to be requested. Additionally unit tests may release blocked waits in a controlled fashion by calling gst_test_clock_process_next_clock_id(). This way a unit test can control the inaccuracy (jitter) of clock notifications, since the test can decide to release blocked waits when the clock time has advanced exactly to, or past, the requested clock notification time. There are also interfaces for determining if a notification belongs to a #GstTestClock or not, as well as getting the number of requested clock notifications so far. N.B.: When a unit test waits for a certain amount of clock notifications to be requested in gst_test_clock_wait_for_next_pending_id() or gst_test_clock_wait_for_multiple_pending_ids() then these functions may block for a long time. If they block forever then the expected clock notifications were never requested from #GstTestClock, and so the assumptions in the code of the unit test are wrong. The unit test case runner in gstcheck is expected to catch these cases either by the default test case timeout or the one set for the unit test by calling tcase_set_timeout\(\). The sample code below assumes that the element under test will delay a buffer pushed on the source pad by some latency until it arrives on the sink pad. Moreover it is assumed that the element will at some point call gst_clock_id_wait() to synchronously wait for a specific time. The first buffer sent will arrive exactly on time only delayed by the latency. The second buffer will arrive a little late (7ms) due to simulated jitter in the clock notification. ## Demonstration of how to work with clock notifications and #GstTestClock |[<!-- language="C" --> #include <gst/gst.h> #include <gst/check/gstcheck.h> #include <gst/check/gsttestclock.h> GstClockTime latency; GstElement *element; GstPad *srcpad; GstClock *clock; GstTestClock *test_clock; GstBuffer buf; GstClockID pending_id; GstClockID processed_id; latency = 42 * GST_MSECOND; element = create_element (latency, ...); srcpad = get_source_pad (element); clock = gst_test_clock_new (); test_clock = GST_TEST_CLOCK (clock); gst_element_set_clock (element, clock); GST_INFO ("Set time, create and push the first buffer\n"); gst_test_clock_set_time (test_clock, 0); buf = create_test_buffer (gst_clock_get_time (clock), ...); gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK); GST_INFO ("Block until element is waiting for a clock notification\n"); gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id); GST_INFO ("Advance to the requested time of the clock notification\n"); gst_test_clock_advance_time (test_clock, latency); GST_INFO ("Release the next blocking wait and make sure it is the one from element\n"); processed_id = gst_test_clock_process_next_clock_id (test_clock); g_assert (processed_id == pending_id); g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK); gst_clock_id_unref (pending_id); gst_clock_id_unref (processed_id); GST_INFO ("Validate that element produced an output buffer and check its timestamp\n"); g_assert_cmpint (get_number_of_output_buffer (...), ==, 1); buf = get_buffer_pushed_by_element (element, ...); g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, latency); gst_buffer_unref (buf); GST_INFO ("Check that element does not wait for any clock notification\n"); g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL)); GST_INFO ("Set time, create and push the second buffer\n"); gst_test_clock_advance_time (test_clock, 10 * GST_SECOND); buf = create_test_buffer (gst_clock_get_time (clock), ...); gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK); GST_INFO ("Block until element is waiting for a new clock notification\n"); (gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id); GST_INFO ("Advance past 7ms beyond the requested time of the clock notification\n"); gst_test_clock_advance_time (test_clock, latency + 7 * GST_MSECOND); GST_INFO ("Release the next blocking wait and make sure it is the one from element\n"); processed_id = gst_test_clock_process_next_clock_id (test_clock); g_assert (processed_id == pending_id); g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK); gst_clock_id_unref (pending_id); gst_clock_id_unref (processed_id); GST_INFO ("Validate that element produced an output buffer and check its timestamp\n"); g_assert_cmpint (get_number_of_output_buffer (...), ==, 1); buf = get_buffer_pushed_by_element (element, ...); g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, 10 * GST_SECOND + latency + 7 * GST_MSECOND); gst_buffer_unref (buf); GST_INFO ("Check that element does not wait for any clock notification\n"); g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL)); ... ]| Since #GstTestClock is only supposed to be used in unit tests it calls g_assert(), g_assert_cmpint() or g_assert_cmpuint() to validate all function arguments. This will highlight any issues with the unit test code itself. Creates a new test clock with its time set to zero. MT safe. a #GstTestClock cast to #GstClock. Creates a new test clock with its time set to the specified time. MT safe. a #GstTestClock cast to #GstClock. a #GstClockTime set to the desired start time of the clock. Finds the latest time inside the list. MT safe. List of of pending #GstClockIDs Advances the time of the @test_clock by the amount given by @delta. The time of @test_clock is monotonically increasing, therefore providing a @delta which is negative or zero is a programming error. MT safe. a #GstTestClock for which to increase the time a positive #GstClockTimeDiff to be added to the time of the clock 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, unless the clock time is already passed the clock id (Since 1.18). 3: Release the #GstClockID wait. A "crank" can be though of as the notion of manually driving the clock forward to its next logical step. %TRUE if the crank was successful, %FALSE otherwise. MT safe. #GstTestClock to crank Retrieve the requested time for the next pending clock notification. MT safe. a #GstClockTime set to the time of the next pending clock notification. If no clock notifications have been requested %GST_CLOCK_TIME_NONE will be returned. a #GstTestClock to fetch the next clock notification time for Checks whether @test_clock was requested to provide the clock notification given by @id. MT safe. %TRUE if the clock has been asked to provide the given clock notification, %FALSE otherwise. a #GstTestClock to ask if it provided the notification a #GstClockID clock notification Determine the number of pending clock notifications that have been requested from the @test_clock. MT safe. the number of pending clock notifications. a #GstTestClock for which to count notifications Determines if the @pending_id is the next clock notification scheduled to be triggered given the current time of the @test_clock. MT safe. %TRUE if @pending_id is the next clock notification to be triggered, %FALSE otherwise. a #GstTestClock to check the clock notifications for a #GstClockID clock notification to look for Processes and releases the pending ID. MT safe. #GstTestClock for which to process the pending IDs #GstClockID Processes and releases the pending IDs in the list. MT safe. #GstTestClock for which to process the pending IDs List of pending #GstClockIDs MT safe. a #GstClockID containing the next pending clock notification. a #GstTestClock for which to retrieve the next pending clock notification Sets the time of @test_clock to the time given by @new_time. The time of @test_clock is monotonically increasing, therefore providing a @new_time which is earlier or equal to the time of the clock as given by gst_clock_get_time() is a programming error. MT safe. a #GstTestClock of which to set the time a #GstClockTime later than that returned by gst_clock_get_time() Blocks until at least @count clock notifications have been requested from @test_clock, or the timeout expires. MT safe. a @gboolean %TRUE if the waits have been registered, %FALSE if not. (Could be that it timed out waiting or that more waits than waits was found) #GstTestClock for which to await having enough pending clock the number of pending clock notifications to wait for the timeout in milliseconds Address of a #GList pointer variable to store the list of pending #GstClockIDs that expired, or %NULL Blocks until at least @count clock notifications have been requested from @test_clock. There is no timeout for this wait, see the main description of #GstTestClock. MT safe. #GstTestClock for which to await having enough pending clock the number of pending clock notifications to wait for Address of a #GList pointer variable to store the list of pending #GstClockIDs that expired, or %NULL Waits until a clock notification is requested from @test_clock. There is no timeout for this wait, see the main description of #GstTestClock. A reference to the pending clock notification is stored in @pending_id. MT safe. #GstTestClock for which to get the pending clock notification #GstClockID with information about the pending clock notification Blocks until at least @count clock notifications have been requested from @test_clock. There is no timeout for this wait, see the main description of #GstTestClock. use gst_test_clock_wait_for_multiple_pending_ids() instead. #GstTestClock for which to await having enough pending clock the number of pending clock notifications to wait for When a #GstTestClock is constructed it will have a certain start time set. If the clock was created using gst_test_clock_new_with_start_time() then this property contains the value of the @start_time argument. If gst_test_clock_new() was called the clock started at time zero, and thus this property contains the value 0. The class of a #GstTestClock, which has no virtual methods to override. the parent class structure Sets up a data probe on the given pad which will raise assertions if the data flow is inconsistent. %TRUE if the pad was added The #GstStreamConsistency handle The #GstPad on which the dataflow will be checked. Frees the allocated data and probes associated with @consist. The #GstStreamConsistency to free. Sets up a data probe on the given pad which will raise assertions if the data flow is inconsistent. A #GstStreamConsistency structure used to track data flow. The #GstPad on which the dataflow will be checked. Reset the stream checker's internal variables. The #GstStreamConsistency to reset. Creates a new harness. Works like gst_harness_new_with_padnames(), except it assumes the #GstElement sinkpad is named "sink" and srcpad is named "src" MT safe. a #GstHarness, or %NULL if the harness could not be created a #gchar describing the #GstElement name Creates a new empty harness. Use gst_harness_add_element_full() to add an #GstElement to it. MT safe. a #GstHarness, or %NULL if the harness could not be created Creates a new harness. MT safe. a #GstHarness, or %NULL if the harness could not be created a #GstElement to attach the harness to (transfer none) a #GstStaticPadTemplate describing the harness srcpad. %NULL will not create a harness srcpad. 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. %NULL will not get/request a sinkpad from the element. (Like if the element is a src.) a #GstStaticPadTemplate describing the harness sinkpad. %NULL will not create a harness sinkpad. a #gchar with the name of the element srcpad that is then linked to the harness sinkpad, similar to the @element_sinkpad_name. Creates a new harness, parsing the @launchline and putting that in a #GstBin, and then attches the harness to the bin. MT safe. a #GstHarness, or %NULL if the harness could not be created a #gchar describing a gst-launch type line Creates a new harness. Works in the same way as gst_harness_new_full(), only that generic padtemplates are used for the harness src and sinkpads, which will be sufficient in most usecases. MT safe. a #GstHarness, or %NULL if the harness could not be created a #GstElement to attach the harness to (transfer none) a #gchar with the name of the element sinkpad that is then linked to the harness srcpad. %NULL does not attach a sinkpad a #gchar with the name of the element srcpad that is then linked to the harness sinkpad. %NULL does not attach a srcpad Creates a new harness. Works like gst_harness_new_with_element(), except you specify the factoryname of the #GstElement MT safe. a #GstHarness, or %NULL if the harness could not be created a #gchar describing the #GstElement name a #gchar with the name of the element sinkpad that is then linked to the harness srcpad. %NULL does not attach a sinkpad a #gchar with the name of the element srcpad that is then linked to the harness sinkpad. %NULL does not attach a srcpad Creates a new harness, like gst_harness_new_full(), except it assumes the #GstElement sinkpad is named "sink" and srcpad is named "src" MT safe. a #GstHarness, or %NULL if the harness could not be created a #gchar describing the #GstElement name a #GstStaticPadTemplate describing the harness srcpad. %NULL will not create a harness srcpad. a #GstStaticPadTemplate describing the harness sinkpad. %NULL will not create a harness sinkpad. Stop the running #GstHarnessThread MT safe. a #GstHarnessThread