Introduction: libuhttpmock Reference Manual

## Introduction

libuhttpmock works by recording the Soup Session your application uses. It traces the requests your application makes and the reply it receives from the (online) server you query. After capturing an initial trace, libuhttpmock will be able to reply to your application's requests the same way the actual servers would and as such help you detect unwanted changes in behaviour in your application.

Example 1. A sample implementation of a test with libuhttpmock

    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
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    /*
     * Copyright (C) 2020 Rasmus Thomsen <oss@cogitri.dev>
     */
    #include <gio/gio.h>
    #include <glib.h>
    #include <libsoup/soup.h>
    #include <uhttpmock/uhm.h>

    UhmServer* mock_server = NULL;

    void
    test_mock (void)
    {
    	g_autoptr(GError) error = NULL;
    	g_autoptr(SoupLogger) soup_logger = NULL;
    	g_autoptr(SoupMessage) soup_message = NULL;
    	g_autoptr(SoupMessageBody) soup_response_message_body = NULL;
    	g_autoptr(SoupSession) soup_session = NULL;
    	g_autofree gchar *server_url = NULL;
    	guint http_status_code = 0;

    	/*
    	 * Start recording the trace if in online mode, otherwise read trace to comapre
    	 * Replace "testname" with the name of the test. This needs to be unique among
    	 * your test suite!
    	 */
    	uhm_server_start_trace (mock_server, "testname", &error);
    	g_assert (error == NULL);

    	soup_session = soup_session_new ();

    	/* Query actual server if online mode is activated */
    	if (uhm_server_get_enable_online (mock_server)) {
    		server_url = g_strdup ("https://jsonplaceholder.typicode.com/todos/1");

    		/*
    		 * Allow usage of the self-signed certificate we generate in
    		 * main (). Make sure this is _only_ set during testing!
    		 */
    		g_object_set (soup_session, "ssl-strict", FALSE, NULL);
    	} else {
    		const gchar *server_address = uhm_server_get_address (mock_server);
    		guint server_port = uhm_server_get_port (mock_server);
    		server_url = g_strdup_printf ("https://%s:%u", server_address, server_port);
    	}

    	/* Set uhttpmock as soup logger so it can capture the trace */
    	soup_logger = soup_logger_new (SOUP_LOGGER_LOG_BODY, -1);
    	soup_logger_set_printer (soup_logger, uhm_server_received_message_chunk_from_soup, mock_server, NULL);
    	soup_session_add_feature (soup_session, SOUP_SESSION_FEATURE (soup_logger));

    	/*
    	 * Send the message - usually your application would process the
    	 * response from uhttpmock, do further requests, etc. afterwards
    	 */
    	soup_message = soup_message_new ("GET", server_url);
    	http_status_code = soup_session_send_message (soup_session, soup_message);
    	g_assert (http_status_code == 200);

    	/* End the trace - in online mode this will save the trace, otherwise it'd compare it. */
    	uhm_server_end_trace (mock_server);
    }

    int
    main (int argc, char **argv)
    {
    	g_autofree gchar *cert_path = NULL;
    	g_autofree gchar *key_path = NULL;
    	g_autofree gchar *trace_path = NULL;
    	g_autoptr(GError) error = NULL;
    	g_autoptr(GFile) trace_dir = NULL;
    	g_autoptr(GTlsCertificate) tls_cert = NULL;

    	g_test_init (&argc, &argv, NULL);

    	/*
    	 * Setup the mock server with the directory to write traces to.
    	 * replace "testsuitename" with the name of the testsuite. This must
    	 * be unique among your project!
    	 */
    	mock_server = uhm_server_new ();
    	trace_path = g_test_build_filename (G_TEST_DIST, "traces", "testsuitename", NULL);
    	trace_dir = g_file_new_for_path (trace_path);
    	uhm_server_set_trace_directory (mock_server, trace_dir);

    	/*
    	 * Set up self signed cert for HTTPS. The cert doesn't actually need to be
    	 * secret - it can be distributed with your program or be generated during
    	 * build time with:  openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes
    	 */
    	cert_path = g_test_build_filename (G_TEST_DIST, "sslcertdir", "cert.pem", NULL);
    	key_path = g_test_build_filename (G_TEST_DIST, "sslcertdir", "key.pem", NULL);
    	tls_cert = g_tls_certificate_new_from_files (cert_path, key_path, &error);
    	g_assert (error == NULL);
    	uhm_server_set_tls_certificate (mock_server, tls_cert);

    	/*
    	 * TRUE, TRUE => Logging mode, records what actual server replies
    	 * FALSE, TRUE => Comparing mode, checks actual server still replies as expected from trace
    	 * FALSE, FALSE => Testing mode, requests are answered by mock server as per trace
    	 *
    	 * As such, you usually want TRUE, TRUE for the initial recording or if you/the server changed
    	 * something (and as such expect a legitimate change in the trace) and then FALSE, FALSE
    	 * to actually engage the tests.
    	 */
    	uhm_server_set_enable_logging (mock_server, TRUE);
    	uhm_server_set_enable_online (mock_server, TRUE);

    	g_test_add_func ("/test/mock", test_mock);
    	return g_test_run ();
    }

This example can be compiled using:

    1
    gcc -o uhttpsample uhttpsample.c $(pkg-config --cflags --libs gio-2.0 glib-2.0 libsoup-2.4 libuhttpmock-0.0)

Afterwards, executing `./uhttpsample` will run the test suite. Initially it will record a trace of the requests done by the test_mock function and the responses it receives, because `uhm_server_set_enable_logging` and `uhm_server_set_enable_online` are both set to `TRUE`. Upon setting both of these to `FALSE`, libuhttpmock will read the trace it created earlier and will fail the test (by returning an HTTP status code indicating failure for the faulty query your application makes) in case something is different - e.g. because your application queried a different URL than expected. Keep in mind that by default libuhttpmock will only compare the URI and methods of messages, but no headers and not the message bodies. To override this behaviour, you can connect to the `compare-messages` signal on `UhmServer` to implement your own custom handler for checking if messages are as expected.