## GstCheck

GstCheck — Common code for GStreamer unit tests

## Synopsis

    #include <gst/check/gstcheck.h>

    #define             GST_START_TEST                      (__testname)
    #define             GST_END_TEST
    #define             ASSERT_BUFFER_REFCOUNT              (buffer,
                                                             name,
                                                             value)
    #define             ASSERT_CAPS_REFCOUNT                (caps,
                                                             name,
                                                             value)
    #define             ASSERT_CRITICAL                     (code)
    #define             ASSERT_WARNING                      (code)
    #define             ASSERT_MINI_OBJECT_REFCOUNT         (miniobj,
                                                             name,
                                                             value)
    #define             ASSERT_OBJECT_REFCOUNT              (object,
                                                             name,
                                                             value)
    #define             ASSERT_OBJECT_REFCOUNT_BETWEEN      (object,
                                                             name,
                                                             lower,
                                                             upper)
    #define             ASSERT_SET_STATE                    (element,
                                                             state,
                                                             ret)
    #define             fail_unless_equals_int              (a,
                                                             b)
    #define             fail_unless_equals_float            (a,
                                                             b)
    #define             fail_unless_equals_string           (a,
                                                             b)
    #define             fail_unless_equals_uint64           (a,
                                                             b)
    #define             fail_unless_equals_int64            (a,
                                                             b)
    #define             fail_unless_equals_int_hex          (a,
                                                             b)
    #define             fail_unless_equals_int64_hex        (a,
                                                             b)
    #define             fail_unless_equals_uint64_hex       (a,
                                                             b)
    #define             fail_unless_equals_pointer          (a,
                                                             b)
    #define             fail_unless_message_error           (msg,
                                                             domain,
                                                             code)
    #define             assert_equals_int                   (a,
                                                             b)
    #define             assert_equals_float                 (a,
                                                             b)
    #define             assert_equals_string                (a,
                                                             b)
    #define             assert_equals_uint64                (a,
                                                             b)
    #define             assert_equals_int64                 (a,
                                                             b)
    #define             assert_equals_int_hex               (a,
                                                             b)
    #define             assert_equals_int64_hex             (a,
                                                             b)
    #define             assert_equals_uint64_hex            (a,
                                                             b)
    #define             assert_equals_pointer               (a,
                                                             b)
    #define             assert_message_error                (m,
                                                             d,
                                                             c)
    void                gst_check_init                      (int *argc,
                                                             char **argv[]);
    void                gst_check_message_error             (GstMessage *message,
                                                             GstMessageType type,
                                                             GQuark domain,
                                                             gint code);
    GstElement *        gst_check_setup_element             (const gchar *factory);
    GstPad *            gst_check_setup_sink_pad            (GstElement *element,
                                                             GstStaticPadTemplate *tmpl);
    GstPad *            gst_check_setup_src_pad             (GstElement *element,
                                                             GstStaticPadTemplate *tmpl);
    GstPad *            gst_check_setup_sink_pad_by_name    (GstElement *element,
                                                             GstStaticPadTemplate *tmpl,
                                                             const gchar *name);
    GstPad *            gst_check_setup_src_pad_by_name     (GstElement *element,
                                                             GstStaticPadTemplate *tmpl,
                                                             const gchar *name);
    void                gst_check_teardown_pad_by_name      (GstElement *element,
                                                             const gchar *name);
    void                gst_check_teardown_element          (GstElement *element);
    void                gst_check_teardown_sink_pad         (GstElement *element);
    void                gst_check_teardown_src_pad          (GstElement *element);
    void                gst_check_drop_buffers              (void);
    void                gst_check_buffer_data               (GstBuffer *buffer,
                                                             gconstpointer data,
                                                             gsize size);
    void                gst_check_caps_equal                (GstCaps *caps1,
                                                             GstCaps *caps2);
    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);
    void                gst_check_element_push_buffer       (const gchar *element_name,
                                                             GstBuffer *buffer_in,
                                                             GstCaps *caps_in,
                                                             GstBuffer *buffer_out,
                                                             GstCaps *caps_out);
    gint                gst_check_run_suite                 (Suite *suite,
                                                             const gchar *name,
                                                             const gchar *fname);
    void                gst_check_setup_events              (GstPad *srcpad,
                                                             GstElement *element,
                                                             GstCaps *caps,
                                                             GstFormat format);
    void                gst_check_setup_events_with_stream_id
                                                            (GstPad *srcpad,
                                                             GstElement *element,
                                                             GstCaps *caps,
                                                             GstFormat format,
                                                             const gchar *stream_id);

## Description

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

## Details

### GST_START_TEST()

    #define             GST_START_TEST(__testname)

wrapper for checks START_TEST

`__testname` : | test function name

### GST_END_TEST

    #define             GST_END_TEST

wrapper for checks END_TEST

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`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

`factory` : | factory
Returns : | a new element. [transfer full]

### gst_check_setup_sink_pad ()

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

`element` : | element to setup pad on
`tmpl` : | pad template
Returns : | a new pad. [transfer full]

### gst_check_setup_src_pad ()

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

`element` : | element to setup pad on
`tmpl` : | pad template
Returns : | a new pad. [transfer full]

### gst_check_setup_sink_pad_by_name ()

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

`element` : | element to setup pad on
`tmpl` : | pad template
`name` : | name
Returns : | a new pad. [transfer full]

### gst_check_setup_src_pad_by_name ()

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

`element` : | element to setup pad on
`tmpl` : | pad template
`name` : | name
Returns : | a new pad. [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`.

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

`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` with the factory with the 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 caps, 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.

`element_name` : | name of the element that needs to be created
`buffer_in` : | a list of buffers that needs to be puched to the element. [element-type GstBuffer][transfer full]
`buffer_out` : | a list of buffers that we expect from the element. [element-type GstBuffer][transfer full]
`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` with the factory with the 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.

`element_name` : | name of the element that needs to be created
`buffer_in` : | push this buffer to the element
`buffer_out` : | compare the result with this buffer

### gst_check_run_suite ()

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

### 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 concist 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.

`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 concist of the minimum required events to allow streaming. Caps is optional to allow raw src testing.

`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