## GstCheck

GstCheck — Common code for GStreamer unit tests

## Functions

#define | GST_START_TEST()
#define | ASSERT_BUFFER_REFCOUNT()
#define | ASSERT_CAPS_REFCOUNT()
#define | ASSERT_CRITICAL()
#define | ASSERT_WARNING()
#define | ASSERT_MINI_OBJECT_REFCOUNT()
#define | ASSERT_OBJECT_REFCOUNT()
#define | ASSERT_OBJECT_REFCOUNT_BETWEEN()
#define | ASSERT_SET_STATE()
#define | fail_unless_equals_int()
#define | fail_unless_equals_float()
#define | fail_unless_equals_string()
#define | fail_unless_equals_uint64()
#define | fail_unless_equals_int64()
#define | fail_unless_equals_int_hex()
#define | fail_unless_equals_int64_hex()
#define | fail_unless_equals_uint64_hex()
#define | fail_unless_equals_pointer()
#define | fail_unless_message_error()
#define | assert_equals_int()
#define | assert_equals_float()
#define | assert_equals_string()
#define | assert_equals_uint64()
#define | assert_equals_int64()
#define | assert_equals_int_hex()
#define | assert_equals_int64_hex()
#define | assert_equals_uint64_hex()
#define | assert_equals_pointer()
#define | assert_message_error()
void | gst_check_init ()
void | gst_check_message_error ()
GstElement * | gst_check_setup_element ()
GstPad * | gst_check_setup_sink_pad ()
GstPad * | gst_check_setup_src_pad ()
GstPad * | gst_check_setup_sink_pad_by_name ()
GstPad * | gst_check_setup_src_pad_by_name ()
void | gst_check_teardown_pad_by_name ()
void | gst_check_teardown_element ()
void | gst_check_teardown_sink_pad ()
void | gst_check_teardown_src_pad ()
void | gst_check_drop_buffers ()
void | gst_check_buffer_data ()
void | gst_check_caps_equal ()
void | gst_check_element_push_buffer_list ()
void | gst_check_element_push_buffer ()
gint | gst_check_run_suite ()
void | gst_check_setup_events ()
void | gst_check_setup_events_with_stream_id ()
GstPad * | gst_check_setup_sink_pad_by_name_from_template ()
GstPad * | gst_check_setup_sink_pad_from_template ()
GstPad * | gst_check_setup_src_pad_by_name_from_template ()
GstPad * | gst_check_setup_src_pad_from_template ()
void | gst_check_objects_destroyed_on_unref ()
void | gst_check_object_destroyed_on_unref ()
gboolean | (*GstCheckLogFilterFunc) ()
GstCheckLogFilter * | gst_check_add_log_filter ()
void | gst_check_clear_log_filter ()
void | gst_check_remove_log_filter ()

## Types and Values

#define | GST_END_TEST
| GstCheckLogFilter

## Includes

    #include <gst/check/check.h>

## Description

These macros and functions are for internal use of the unit tests found inside the 'check' directories of various GStreamer packages.

One notable feature is that one can use the environment variables GST_CHECKS and GST_CHECKS_IGNORE to select which tests to run or skip. Both variables can contain a comma separated list of test name globs (e.g. test_*).

## Functions

### GST_START_TEST()

    #define             GST_START_TEST(__testname)

wrapper for checks START_TEST

#### Parameters

__testname | test function name |

### ASSERT_BUFFER_REFCOUNT()

    #define             ASSERT_BUFFER_REFCOUNT(buffer, name, value)

### ASSERT_CAPS_REFCOUNT()

    #define             ASSERT_CAPS_REFCOUNT(caps, name, value)

### ASSERT_CRITICAL()

    #define ASSERT_CRITICAL(code)

### ASSERT_WARNING()

    #define             ASSERT_WARNING(code)

### ASSERT_MINI_OBJECT_REFCOUNT()

    #define             ASSERT_MINI_OBJECT_REFCOUNT(miniobj, name, value)

### ASSERT_OBJECT_REFCOUNT()

    #define             ASSERT_OBJECT_REFCOUNT(object, name, value)

### ASSERT_OBJECT_REFCOUNT_BETWEEN()

    #define             ASSERT_OBJECT_REFCOUNT_BETWEEN(object, name, lower, upper)

### ASSERT_SET_STATE()

    #define             ASSERT_SET_STATE(element, state, ret)

### fail_unless_equals_int()

    #define             fail_unless_equals_int(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a gint value or expression |
b | a gint value or expression |

### fail_unless_equals_float()

    #define             fail_unless_equals_float(a, b)

This macro checks that `a` and `b` are (almost) equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a gdouble or gfloat value or expression |
b | a gdouble or gfloat value or expression |

### fail_unless_equals_string()

    #define             fail_unless_equals_string(a, b)

This macro checks that `a` and `b` are equal (as per strcmp) and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a string literal or expression |
b | a string literal or expression |

### fail_unless_equals_uint64()

    #define             fail_unless_equals_uint64(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a guint64 value or expression |
b | a guint64 value or expression |

### fail_unless_equals_int64()

    #define             fail_unless_equals_int64(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a gint64 value or expression |
b | a gint64 value or expression |

### fail_unless_equals_int_hex()

    #define             fail_unless_equals_int_hex(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to in hexadecimal format. This macro is for use in unit tests.

#### Parameters

a | a gint value or expression |
b | a gint value or expression |

Since: 1.2

### fail_unless_equals_int64_hex()

    #define             fail_unless_equals_int64_hex(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to in hexadecimal format. This macro is for use in unit tests.

#### Parameters

a | a gint64 value or expression |
b | a gint64 value or expression |

Since: 1.2

### fail_unless_equals_uint64_hex()

    #define             fail_unless_equals_uint64_hex(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to in hexadecimal format. This macro is for use in unit tests.

#### Parameters

a | a gint64 value or expression |
b | a gint64 value or expression |

Since: 1.2

### fail_unless_equals_pointer()

    #define             fail_unless_equals_pointer(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a pointer value or expression |
b | a pointer value or expression |

Since: 1.2

### fail_unless_message_error()

    #define             fail_unless_message_error(msg, domain, code)

### assert_equals_int()

    #define assert_equals_int(a, b) fail_unless_equals_int(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a gint value or expression |
b | a gint value or expression |

### assert_equals_float()

    #define assert_equals_float(a, b) fail_unless_equals_float(a, b)

This macro checks that `a` and `b` are (almost) equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a gdouble or gfloat value or expression |
b | a gdouble or gfloat value or expression |

### assert_equals_string()

    #define assert_equals_string(a, b) fail_unless_equals_string(a, b)

This macro checks that `a` and `b` are equal (as per strcmp) and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a string literal or expression |
b | a string literal or expression |

### assert_equals_uint64()

    #define assert_equals_uint64(a, b) fail_unless_equals_uint64(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a guint64 value or expression |
b | a guint64 value or expression |

### assert_equals_int64()

    #define assert_equals_int64(a, b) fail_unless_equals_int64(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a gint64 value or expression |
b | a gint64 value or expression |

### assert_equals_int_hex()

    #define assert_equals_int_hex(a, b) fail_unless_equals_int_hex(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to in hexadecimal format. This macro is for use in unit tests.

#### Parameters

a | a gint value or expression |
b | a gint value or expression |

Since: 1.2

### assert_equals_int64_hex()

    #define assert_equals_int64_hex(a,b) fail_unless_equals_int64_hex(a,b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to in hexadecimal format. This macro is for use in unit tests.

#### Parameters

a | a gint64 value or expression |
b | a gint64 value or expression |

Since: 1.2

### assert_equals_uint64_hex()

    #define assert_equals_uint64_hex(a,b) fail_unless_equals_uint64_hex(a,b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to in hexadecimal format. This macro is for use in unit tests.

#### Parameters

a | a guint64 value or expression |
b | a guint64 value or expression |

Since: 1.2

### assert_equals_pointer()

    #define assert_equals_pointer(a, b) fail_unless_equals_pointer(a, b)

This macro checks that `a` and `b` are equal and aborts if this is not the case, printing both expressions and the values they evaluated to. This macro is for use in unit tests.

#### Parameters

a | a pointer value or expression |
b | a pointer value or expression |

Since: 1.2

### assert_message_error()

    #define assert_message_error(m, d, c) fail_unless_message_error(m, d, c)

### gst_check_init ()

    void
    gst_check_init (int *argc,
                    char **argv[]);

### gst_check_message_error ()

    void
    gst_check_message_error (GstMessage *message,
                             GstMessageType type,
                             GQuark domain,
                             gint code);

### gst_check_setup_element ()

    GstElement *
    gst_check_setup_element (const gchar *factory);

setup an element for a filter test with mysrcpad and mysinkpad

#### Parameters

factory | factory |

#### Returns

a new element.

[transfer full]

### gst_check_setup_sink_pad ()

    GstPad *
    gst_check_setup_sink_pad (GstElement *element,
                              GstStaticPadTemplate *tmpl);

Does the same as gst_check_setup_sink_pad_by_name with the name parameter equal to "src".

#### Parameters

element | element to setup pad on |
tmpl | pad template |

#### Returns

a new pad that can be used to check the output of `element` .

[transfer full]

### gst_check_setup_src_pad ()

    GstPad *
    gst_check_setup_src_pad (GstElement *element,
                             GstStaticPadTemplate *tmpl);

Does the same as gst_check_setup_src_pad_by_name with the name parameter equal to "sink".

#### Parameters

element | element to setup pad on |
tmpl | pad template |

#### Returns

A new pad that can be used to inject data on `element` .

[transfer full]

### gst_check_setup_sink_pad_by_name ()

    GstPad *
    gst_check_setup_sink_pad_by_name (GstElement *element,
                                      GstStaticPadTemplate *tmpl,
                                      const gchar *name);

Creates a new sink pad (based on the given `tmpl` ) and links it to the given `element` src pad (the pad that matches the given `name` ). You can set event/chain/query functions on this pad to check the output of the `element` .

#### Parameters

element | element to setup pad on |
tmpl | pad template |
name | Name of the `element` src pad that will be linked to the sink pad that will be setup |

#### Returns

a new pad that can be used to check the output of `element` .

[transfer full]

### gst_check_setup_src_pad_by_name ()

    GstPad *
    gst_check_setup_src_pad_by_name (GstElement *element,
                                     GstStaticPadTemplate *tmpl,
                                     const gchar *name);

Creates a new src pad (based on the given `tmpl` ) and links it to the given `element` sink pad (the pad that matches the given `name` ). Before using the src pad to push data on `element` you need to call gst_check_setup_events on the created src pad.

Example of how to push a buffer on `element` :

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24

    static GstStaticPadTemplate sinktemplate = GST_STATIC_PAD_TEMPLATE ("sink",
    GST_PAD_SINK,
    GST_PAD_ALWAYS,
    GST_STATIC_CAPS (YOUR_CAPS_TEMPLATE_STRING)
    );
    static GstStaticPadTemplate srctemplate = GST_STATIC_PAD_TEMPLATE ("src",
    GST_PAD_SRC,
    GST_PAD_ALWAYS,
    GST_STATIC_CAPS (YOUR_CAPS_TEMPLATE_STRING)
    );

    GstElement * element = gst_check_setup_element ("element");
    GstPad * mysrcpad = gst_check_setup_src_pad (element, &srctemplate);
    GstPad * mysinkpad = gst_check_setup_sink_pad (element, &sinktemplate);

    gst_pad_set_active (mysrcpad, TRUE);
    gst_pad_set_active (mysinkpad, TRUE);
    fail_unless (gst_element_set_state (element, GST_STATE_PLAYING) == GST_STATE_CHANGE_SUCCESS, "could not set to playing");

    GstCaps * caps = gst_caps_from_string (YOUR_DESIRED_SINK_CAPS);
    gst_check_setup_events (mysrcpad, element, caps, GST_FORMAT_TIME);
    gst_caps_unref (caps);

    fail_unless (gst_pad_push (mysrcpad, gst_buffer_new_and_alloc(2)) == GST_FLOW_OK);

For very simple input/output test scenarios checkout gst_check_element_push_buffer_list and gst_check_element_push_buffer.

#### Parameters

element | element to setup src pad on |
tmpl | pad template |
name | Name of the `element` sink pad that will be linked to the src pad that will be setup |

#### Returns

A new pad that can be used to inject data on `element` .

[transfer full]

### gst_check_teardown_pad_by_name ()

    void
    gst_check_teardown_pad_by_name (GstElement *element,
                                    const gchar *name);

### gst_check_teardown_element ()

    void
    gst_check_teardown_element (GstElement *element);

### gst_check_teardown_sink_pad ()

    void
    gst_check_teardown_sink_pad (GstElement *element);

### gst_check_teardown_src_pad ()

    void
    gst_check_teardown_src_pad (GstElement *element);

### gst_check_drop_buffers ()

    void
    gst_check_drop_buffers (void);

Unref and remove all buffers that are in the global `buffers` GList, emptying the list.

### gst_check_buffer_data ()

    void
    gst_check_buffer_data (GstBuffer *buffer,
                           gconstpointer data,
                           gsize size);

Compare the buffer contents with `data` and `size` .

#### Parameters

buffer | buffer to compare |
data | data to compare to |
size | size of data to compare |

### gst_check_caps_equal ()

    void
    gst_check_caps_equal (GstCaps *caps1,
                          GstCaps *caps2);

Compare two caps with gst_caps_is_equal and fail unless they are equal.

#### Parameters

caps1 | first caps to compare |
caps2 | second caps to compare |

### gst_check_element_push_buffer_list ()

    void
    gst_check_element_push_buffer_list (const gchar *element_name,
                                        GList *buffer_in,
                                        GstCaps *caps_in,
                                        GList *buffer_out,
                                        GstCaps *caps_out,
                                        GstFlowReturn last_flow_return);

Create an element using the factory providing the `element_name` and push the buffers in `buffer_in` to this element. The element should create the buffers equal to the buffers in `buffer_out` . We only check the size and the data of the buffers. This function unrefs the buffers in the two lists. The last_flow_return parameter indicates the expected flow return value from pushing the final buffer in the list. This can be used to set up a test which pushes some buffers and then an invalid buffer, when the final buffer is expected to fail, for example.

#### Parameters

element_name | name of the element that needs to be created |
buffer_in | a list of buffers that needs to be pushed to the element. | [element-type GstBuffer][transfer full]
caps_in | the GstCaps expected of the sinkpad of the element |
buffer_out | a list of buffers that we expect from the element. | [element-type GstBuffer][transfer full]
caps_out | the GstCaps expected of the srcpad of the element |
last_flow_return | the last buffer push needs to give this GstFlowReturn |

### gst_check_element_push_buffer ()

    void
    gst_check_element_push_buffer (const gchar *element_name,
                                   GstBuffer *buffer_in,
                                   GstCaps *caps_in,
                                   GstBuffer *buffer_out,
                                   GstCaps *caps_out);

Create an element using the factory providing the `element_name` and push the `buffer_in` to this element. The element should create one buffer and this will be compared with `buffer_out` . We only check the caps and the data of the buffers. This function unrefs the buffers.

#### Parameters

element_name | name of the element that needs to be created |
buffer_in | push this buffer to the element |
caps_in | the GstCaps expected of the sinkpad of the element |
buffer_out | compare the result with this buffer |
caps_out | the GstCaps expected of the srcpad of the element |

### gst_check_run_suite ()

    gint
    gst_check_run_suite (Suite *suite,
                         const gchar *name,
                         const gchar *fname);

[skip]

#### Parameters

suite | the check test suite |
name | name |
fname | file name |

#### Returns

number of failed tests

### gst_check_setup_events ()

    void
    gst_check_setup_events (GstPad *srcpad,
                            GstElement *element,
                            GstCaps *caps,
                            GstFormat format);

Push stream-start, caps and segment event, which consist of the minimum required events to allow streaming. Caps is optional to allow raw src testing. If `element` has more than one src or sink pad, use `gst_check_setup_events_with_stream_id()` instead.

#### Parameters

srcpad | The src GstPad to push on |
element | The GstElement use to create the stream id |
caps | GstCaps in case caps event must be sent. | [allow-none]
format | The GstFormat of the default segment to send |

### gst_check_setup_events_with_stream_id ()

    void
    gst_check_setup_events_with_stream_id (GstPad *srcpad,
                                           GstElement *element,
                                           GstCaps *caps,
                                           GstFormat format,
                                           const gchar *stream_id);

Push stream-start, caps and segment event, which consist of the minimum required events to allow streaming. Caps is optional to allow raw src testing.

#### Parameters

srcpad | The src GstPad to push on |
element | The GstElement use to create the stream id |
caps | GstCaps in case caps event must be sent. | [allow-none]
format | The GstFormat of the default segment to send |
stream_id | A unique identifier for the stream |

### gst_check_setup_sink_pad_by_name_from_template ()

    GstPad *
    gst_check_setup_sink_pad_by_name_from_template
                                   (GstElement *element,
                                    GstPadTemplate *tmpl,
                                    const gchar *name);

#### Parameters

element | element to setup pad on |
tmpl | pad template |
name | name |

#### Returns

a new pad.

[transfer full]

Since: 1.4

### gst_check_setup_sink_pad_from_template ()

    GstPad *
    gst_check_setup_sink_pad_from_template
                                   (GstElement *element,
                                    GstPadTemplate *tmpl);

#### Parameters

element | element to setup pad on |
tmpl | pad template |

#### Returns

a new pad.

[transfer full]

Since: 1.4

### gst_check_setup_src_pad_by_name_from_template ()

    GstPad *
    gst_check_setup_src_pad_by_name_from_template
                                   (GstElement *element,
                                    GstPadTemplate *tmpl,
                                    const gchar *name);

#### Parameters

element | element to setup pad on |
tmpl | pad template |
name | name |

#### Returns

a new pad.

[transfer full]

Since: 1.4

### gst_check_setup_src_pad_from_template ()

    GstPad *
    gst_check_setup_src_pad_from_template (GstElement *element,
                                           GstPadTemplate *tmpl);

#### Parameters

element | element to setup pad on |
tmpl | pad template |

#### Returns

a new pad.

[transfer full]

Since: 1.4

### gst_check_objects_destroyed_on_unref ()

    void
    gst_check_objects_destroyed_on_unref (gpointer object_to_unref,
                                          gpointer first_object,
                                          ...);

Unrefs `object_to_unref` and checks that is has properly been destroyed, also checks that the other objects passed in parametter have been destroyed as a concequence of unrefing `object_to_unref` . Last variable argument should be NULL.

#### Parameters

object_to_unref | The GObject to unref |
first_object | The first object that should be destroyed as a concequence of unrefing `object_to_unref` . | [allow-none]
... | Additional object that should have been destroyed. |

Since: 1.6

### gst_check_object_destroyed_on_unref ()

    void
    gst_check_object_destroyed_on_unref (gpointer object_to_unref);

Unrefs `object_to_unref` and checks that is has properly been destroyed.

#### Parameters

object_to_unref | The GObject to unref |

Since: 1.6

### GstCheckLogFilterFunc ()

    gboolean
    (*GstCheckLogFilterFunc) (const gchar *log_domain,
                              GLogLevelFlags log_level,
                              const gchar *message,
                              gpointer user_data);

A function that is called for messages matching the filter added by `gst_check_add_log_filter` .

#### Parameters

log_domain | the log domain of the message |
log_level | the log level of the message |
message | the message that has occurred |
user_data | user data |

#### Returns

`TRUE` if message should be discarded by GstCheck.

Since: 1.12

### gst_check_add_log_filter ()

    GstCheckLogFilter *
    gst_check_add_log_filter (const gchar *log_domain,
                              GLogLevelFlags log_level,
                              GRegex *regex,
                              GstCheckLogFilterFunc func,
                              gpointer user_data,
                              GDestroyNotify destroy_data);

Add a callback `func` to be called for all log messages that matches `log_domain` , `log_level` and `regex` . If `func` is NULL the matching logs will be silently discarded by GstCheck.

MT safe.

[skip]

#### Parameters

log_domain | the log domain of the message |
log_level | the log level of the message |
regex | a GRegex to match the message. | [transfer full]
func | the function to call for matching messages |
user_data | the user data to pass to `func` |
destroy_data | GDestroyNotify for `user_data` |

#### Returns

A filter that can be passed to `gst_check_remove_log_filter` .

Since: 1.12

### gst_check_clear_log_filter ()

    void
    gst_check_clear_log_filter (void);

Clear all filters added by `gst_check_add_log_filter` .

MT safe.

Since: 1.12

### gst_check_remove_log_filter ()

    void
    gst_check_remove_log_filter (GstCheckLogFilter *filter);

Remove a filter that has been added by `gst_check_add_log_filter` .

MT safe.

#### Parameters

filter | Filter returned by `gst_check_add_log_filter` |

Since: 1.12

## Types and Values

### GST_END_TEST

    #define             GST_END_TEST

wrapper for checks END_TEST

### GstCheckLogFilter

    typedef struct _GstCheckLogFilter GstCheckLogFilter;