stubbing

(This documentation is adapted from the original documentation of WireMock.)

A core feature of Mimus Serve is the ability to return canned HTTP responses for requests matching criteria. These are described in detail in Request Matching.

Basic stubbing

The following code will configure a response with a status of 200 to be returned when the relative URL exactly matches /some/thing (including query parameters). The body of the response will be "Hello world!" and a Content-Type header will be sent with a value of text/plain.

{
    "request": {
        "method": "GET",
        "url": "/some/thing"
    },
    "response": {
        "status": 200,
        "body": "Hello world!",
        "headers": {
            "Content-Type": "text/plain"
        }
    }
}

Setting the response status message

In addition to the status code, the status message can optionally also be set.

{
    "request": {
        "method": "GET",
        "url": "/some/thing"
    },
    "response": {
        "status": 200,
        "statusMessage": "Everything was just fine!"
    }
}

Stub priority

It is sometimes the case that you'll want to declare two or more stub mappings that "overlap", in that a given request would be a match for more than one of them. By default, Mimus Serve will use the most recently added matching stub to satisfy the request. However, in some cases it is useful to exert more control.

One example of this might be where you want to define a catch-all stub for any URL that doesn't match any more specific cases. Adding a priority to a stub mapping facilitates this:

{
    "priority": 1,
    "request": {
        "method": "GET",
        "url": "/api/specific-resource"
    },
    "response": {
        "status": 200
    }
}

When unspecified, stubs default to a priority of 0 where 0 is the highest priority.

Sending response headers

In addition to matching on request headers, it's also possible to send response headers.

{
    "request": {
        "method": "GET",
        "url": "/whatever"
    },
    "response": {
        "status": 200,
        "headers": {
            "Content-Type": "text/plain",
            "Set-Cookie": ["session_id=91837492837", "split_test_group=B"],
            "Cache-Control": "no-cache"
        }
    }
}

Specifying the response body

The simplest way to specify a response body is as a string literal.

{
    "request": {
        "method": "GET",
        "url": "/body"
    },
    "response": {
        "status": 200,
        "body": "Literal text to put in the body"
    }
}

(TODO) If you're specifying a JSON body via the JSON API, you can avoid having to escape it like this:

    "response": {
        "status": 200,
        "jsonBody": {
          "arbitrary_json": [1, 2, 3]
        }
    }

To read the body content from a file, place the file under the files directory (See CLI).

{
    "request": {
        "method": "GET",
        "url": "/body-file"
    },
    "response": {
        "status": 200,
        "bodyFileName": "path/to/myfile.xml"
    }
}

note

Body file paths should always be relative i.e. not have a leading /. It should not be possible to break from the configured files directory.

note

All strings used by Mimus Serve, including the contents of body files are expected to be in UTF-8 format.

(TODO) A response body in binary format can be specified as a base64 string (to avoid stupidly long JSON documents):

{
    "request": {
        "method": "GET",
        "url": "/binary-body"
    },
    "response": {
        "status": 200,
        "base64Body": "WUVTIElOREVFRCE="
    }
}

Default response for unmapped requests

When a request cannot be mapped to a response, Mimus Serve returns an HTML response with a 404 status code.

It is possible to customize the response by catching all URLs with a low priority.

{
    "priority": 10,
    "request": {
        "method": "ANY",
        "urlPattern": ".*"
    },
    "response": {
        "status": 404,
        "jsonBody": { "status": "Error", "message": "Endpoint not found" },
        "headers": {
            "Content-Type": "application/json"
        }
    }
}

Getting all currently registered stub mappings

To fetch them via the HTTP API send a GET to http://<host>:<port>/__admin/mappings.

Optionally limit and offset parameters can be specified to constrain the set returned e.g. GET http://localhost:8080/__admin/mappings?limit=10&offset=50