## 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         (caps,
                                                             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_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_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,
                                                             GstCaps *caps);
    GstPad *            gst_check_setup_src_pad             (GstElement *element,
                                                             GstStaticPadTemplate *tmpl,
                                                             GstCaps *caps);
    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_caps_equal                (GstCaps *caps1,
                                                             GstCaps *caps2);
    void                gst_check_element_push_buffer_list  (const gchar *element_name,
                                                             GList *buffer_in,
                                                             GList *buffer_out,
                                                             GstFlowReturn last_flow_return);
    void                gst_check_element_push_buffer       (const gchar *element_name,
                                                             GstBuffer *buffer_in,
                                                             GstBuffer *buffer_out);
    gint                gst_check_run_suite                 (Suite *suite,
                                                             const gchar *name,
                                                             const gchar *fname);

## 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(caps, 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

Since 0.10.14

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

Since 0.10.14

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

### gst_check_setup_sink_pad ()

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

### gst_check_setup_src_pad ()

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

### gst_check_setup_sink_pad_by_name ()

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

### gst_check_setup_src_pad_by_name ()

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

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

Since 0.10.18

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

Since 0.10.18

### gst_check_element_push_buffer_list ()

    void                gst_check_element_push_buffer_list  (const gchar *element_name,
                                                             GList *buffer_in,
                                                             GList *buffer_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
`buffer_out` : | a list of buffers that we expect from the element
`last_flow_return` : | the last buffer push needs to give this GstFlowReturn

Since 0.10.18

### gst_check_element_push_buffer ()

    void                gst_check_element_push_buffer       (const gchar *element_name,
                                                             GstBuffer *buffer_in,
                                                             GstBuffer *buffer_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

Since 0.10.18

### gst_check_run_suite ()

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