geocode-mock-backend: geocode-glib Reference Manual

## geocode-mock-backend geocode-mock-backend — Geocode mock backend implementation |

## Functions

GeocodeMockBackend * | geocode_mock_backend_new ()
void | geocode_mock_backend_add_forward_result ()
void | geocode_mock_backend_add_reverse_result ()
void | geocode_mock_backend_clear ()
GPtrArray * | geocode_mock_backend_get_query_log ()

## Types and Values

#define | GEOCODE_TYPE_MOCK_BACKEND
| GeocodeMockBackendQuery
| GeocodeMockBackend

## Object Hierarchy

        GObject
        ╰── GeocodeMockBackend

## Implemented Interfaces

GeocodeMockBackend implements GeocodeBackend.

## Includes

    #include <geocode-glib/geocode-glib.h>

## Description

GeocodeMockBackend is intended to be used in unit tests for applications which use geocode-glib — it allows them to set the geocode results they expect their application to query, and check afterwards that the queries were performed. It works offline, which allows application unit tests to be run on integration and build machines which are not online. It is not expected that GeocodeMockBackend will be used in production code.

To use it, create the backend instance, add the query results to it which you want to be returned to your application’s queries, then use it as the GeocodeBackend for `geocode_forward_set_backend()` or `geocode_reverse_set_backend()`. After a test has been run, the set of queries which the code under test actually made on the backend can be checked using `geocode_mock_backend_get_query_log()`. The backend can be reset using `geocode_mock_backend_clear()` and new queries added for the next test.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    static void
    place_list_free (GList *l)
    {
      g_list_free_full (l, g_object_unref);
    }

    typedef GList PlaceList;
    G_DEFINE_AUTOPTR_CLEANUP_FUNC (PlaceList, place_list_free)

    g_autoptr (GeocodeForward) forward = NULL;
    g_autoptr (GeocodeMockBackend) backend = NULL;
    g_autoptr (GHashTable) params = NULL;
    GValue location = G_VALUE_INIT;
    g_autoptr (PlaceList) results = NULL;
    g_autoptr (PlaceList) expected_results = NULL;
    g_autoptr (GError) error = NULL;
    g_autoptr (GeocodePlace) expected_place = NULL;
    g_autoptr (GeocodeLocation) expected_location = NULL;
    GPtrArray *query_log;  /<!-- -->* (element-type GeocodeMockBackendQuery) *<!-- -->/

    backend = geocode_mock_backend_new ();

    /<!-- -->* Build the set of parameters the mock backend expects to receive from
     * the #GeocodeForward instance. *<!-- -->/
    params = g_hash_table_new_full (g_str_hash, g_str_equal, NULL, NULL);

    g_value_init (&location, G_TYPE_STRING);
    g_value_set_static_string (&location, "Bullpot Farm");
    g_hash_table_insert (params, (gpointer) "location", &location);

    /<!-- -->* Build the set of results the mock backend should return. *<!-- -->/
    expected_location = geocode_location_new_with_description (
        54.22759825, -2.51857179181113, 5.0,
        "Bullpot Farm, Fell Road, South Lakeland, Cumbria, "
        "North West England, England, United Kingdom");
    expected_place = geocode_place_new_with_location (
        "Bullpot Farm", GEOCODE_PLACE_TYPE_BUILDING, expected_location);
    expected_results = g_list_prepend (expected_results,
                                       g_steal_pointer (&expected_place));

    geocode_mock_backend_add_forward_result (backend, params,
                                             expected_results, NULL);

    /<!-- -->* Do the search. This would typically call the application code
     * under test, rather than geocode-glib directly. *<!-- -->/
    forward = geocode_forward_new_for_string ("Bullpot Farm");
    geocode_forward_set_backend (forward, GEOCODE_BACKEND (backend));
    results = geocode_forward_search (forward, &error);

    g_assert_no_error (error);
    assert_place_list_equal (results, expected_results);

    /<!-- -->* Check the application made the expected query. *<!-- -->/
    query_log = geocode_mock_backend_get_query_log (backend);
    g_assert_cmpuint (query_log->len, ==, 1);

## Functions

### geocode_mock_backend_new ()

    GeocodeMockBackend *
    geocode_mock_backend_new (void);

Creates a new mock backend implementation with no initial forward or reverse query results (so it will return an empty result set for all queries).

#### Returns

a new GeocodeMockBackend.

[transfer full]

Since: 3.23.1

### geocode_mock_backend_add_forward_result ()

    void
    geocode_mock_backend_add_forward_result
                                   (GeocodeMockBackend *self,
                                    GHashTable *params,
                                    GList *results,
                                    const GError *error);

Add a query and corresponding result (or error) to the mock backend, meaning that if it receives a forward search for `params` through `geocode_backend_forward_search()` (or its asynchronous variants), the mock backend will return the given `results` or `error` to the caller.

If a set of `params` is added to the backend multiple times, the most recently provided `results` and `error` will be used.

Exactly one of `results` and `error` must be set. Empty result sets are represented as a `GEOCODE_ERROR_NO_MATCHES` error.

#### Parameters

self | a GeocodeMockBackend |
params | query parameters to respond to, in the same format as accepted by `geocode_forward_search()`. | [transfer none][element-type utf8 GValue]
results | result set to return for the query, or `NULL` if `error` is non-`NULL`; result sets must be in the same format as returned by `geocode_forward_search()`. | [transfer none][nullable][element-type GeocodePlace]
error | error to return for the query, or `NULL` if `results` should be returned instead; errors must match those returned by `geocode_forward_search()`. | [nullable]

Since: 3.23.1

### geocode_mock_backend_add_reverse_result ()

    void
    geocode_mock_backend_add_reverse_result
                                   (GeocodeMockBackend *self,
                                    GHashTable *params,
                                    GList *results,
                                    const GError *error);

Add a query and corresponding result (or error) to the mock backend, meaning that if it receives a reverse search for `params` through `geocode_backend_reverse_resolve()` (or its asynchronous variants), the mock backend will return the given `results` or `error` to the caller.

If a set of `params` is added to the backend multiple times, the most recently provided `results` and `error` will be used.

Exactly one of `results` and `error` must be set. Empty result sets are represented as a `GEOCODE_ERROR_NOT_SUPPORTED` error.

#### Parameters

self | a GeocodeMockBackend |
params | query parameters to respond to, in the same format as accepted by `geocode_reverse_resolve()`. | [transfer none][element-type utf8 GValue]
results | result set to return for the query, or `NULL` if `error` is non-`NULL`; result sets must be in the same format as returned by `geocode_reverse_resolve()`. | [transfer none][nullable][element-type GeocodePlace]
error | error to return for the query, or `NULL` if `results` should be returned instead; errors must match those returned by `geocode_reverse_resolve()`. | [nullable]

Since: 3.23.1

### geocode_mock_backend_clear ()

    void
    geocode_mock_backend_clear (GeocodeMockBackend *self);

Clear the set of stored results in the mock backend which have been added using `geocode_mock_backend_add_forward_result()` and `geocode_mock_backend_add_reverse_result()`. Additionally, clear the query log so far (see `geocode_mock_backend_get_query_log()`).

This effectively resets the mock backend to its initial state.

#### Parameters

self | a GeocodeMockBackend |

Since: 3.23.1

### geocode_mock_backend_get_query_log ()

    GPtrArray *
    geocode_mock_backend_get_query_log (GeocodeMockBackend *self);

Get the details of the forward and reverse queries which have been requested of the mock backend since the most recent call to `geocode_mock_backend_clear()`. The query details are provided as GeocodeMockBackendQuery structures, which map the query parameters to either the result set or the error which `geocode_backend_forward_search()` or `geocode_backend_reverse_resolve()` (or their asynchronous variants) returned to the caller.

The results are provided in the order in which calls were made to `geocode_backend_forward_search()` and `geocode_backend_reverse_resolve()`. Results for forward and reverse queries may be interleaved.

#### Parameters

self | a GeocodeMockBackend |

#### Returns

potentially empty sequence of forward and reverse query details.

[transfer none][element-type GeocodeMockBackendQuery]

Since: 3.23.1

## Types and Values

### GEOCODE_TYPE_MOCK_BACKEND

    #define GEOCODE_TYPE_MOCK_BACKEND (geocode_mock_backend_get_type ())

See GeocodeMockBackend.

Since: 3.23.1

### GeocodeMockBackendQuery

    typedef struct {
    	/* Request */
    	GHashTable *params;
    	gboolean is_forward;

    	/* Response */
    	GList *results;
    	GError *error;
    } GeocodeMockBackendQuery;

The details of a forward or reverse query which was performed on a GeocodeMockBackend by application code. This includes the input (`params` , `is_forward` ), and the output which was returned (`results` or `error` ).

Empty result sets are represented by the `GEOCODE_ERROR_NO_MATCHES` error (for forward queries) or the `GEOCODE_ERROR_NOT_SUPPORTED` error (for reverse queries), rather than an empty `results` list.

#### Members

GHashTable *`params`; | query parameters, in the format accepted by `geocode_forward_search()` (if `is_forward` is `TRUE`) or `geocode_reverse_resolve()` (otherwise) |
gboolean `is_forward`; | `TRUE` if this represents a call to `geocode_forward_search()`; `FALSE` if it represents a call to `geocode_reverse_resolve()` |
GList *`results`; | results returned by the query, or `NULL` if an error was returned. | [nullable][element-type GeocodePlace]
GError *`error`; | error returned by the query, or `NULL` if a result set was returned. | [nullable]

Since: 3.23.1

### GeocodeMockBackend

    typedef struct _GeocodeMockBackend GeocodeMockBackend;

All the fields in the GeocodeMockBackend structure are private and should never be accessed directly.

Since: 3.23.1