Ekko Proxy WireMock Editor

The Ekko Proxy WireMock Editor lets you manage wiremocks for the proxy instances. The wiremock configuration files created by the editor are not just available to the proxy instances but can also be used in WireMock based unit tests.

Managing WireMocks

The Mock Editor is accessed from the navigation pane and lists any virtual mocks that are available to the proxy instances:

Available WireMocks will appear in the table as shown above and are stored in a mocks folder (relative to the application).

Fields and functions

The fields and functions of this part of the WireMock management view are as follows:

Mocks table

The mocks table contain the following columns:

Note multiple messages can be selected by clicking the check box or by holding down the Ctrl key while clicking on a mock row.

Mock details

Mock details of a mock (either selected from the mocks table or directly entered) are displayed in the mock details section as shown below.

The fields on the mock details section are described below:

Request details

The request details section shows the request matching details of a mock:

The fields and functions of this part of the mock management view are:

You can find further details on request matching here: WireMock request matching.

Response details

The response details section shows what the response of the mock will be:

The fields and functions of this part of the mock management view are:

For further information on WireMock please refer to the WireMock documentation.

Response Templating

You can send back different responses by configuring different mocks that matches on different request properties. This works well in simple scenarios but can get a bit cumbersome depending on the number of different responses required. For these use cases you can take advantage of the templating option instead which allows you to define handlebars type expressions to output dynamic values based on the request. These expressions can be used in the response headers as well as the response body. For more information on handlebars see handlebars guide.

To enable templating simply tick the Templating checkbox.

The table below shows the request object properties that are available for templating.

Dynamic expressions using Handlebars are denoted using double curly brackets e.g. {{request.path}} would output the request path. There are also a number of HTTP elements like query parameters, form fields and headers that can be single or multiple valued. The template request model and built-in helpers attempt to make this easy to work with by wrapping these in a list or single type that returns the first (and often the only) value when no index is specified, but there is also support index access. For instance, given a request URL like /multi-query?myparams=1&myparams=2&myparams=3 then you can extract the query data in the following ways:

{{request.query.myparams}} {{!- Will return 1 --}}
{{request.query.myparams.0}} {{!- Will return 1 --}}
{{request.query.myparams.first}} {{!- Will return 1 --}}
{{request.query.myparams.1}} {{!- Will return 2 --}}
{{request.query.myparams.[-1]}} {{!- Will return 2 --}}
{{request.query.myparams.last}} {{!- Will return 3 --}}

Note when using the Handlebars eq helper with single or multiple valued elements, it is necessary to use the indexed form, even if only one value is present. The reason for this is that the non-indexed form returns the wrapper type and not a String type, and will therefore fail to compare with another String value.

In Handlebars there are special characters that have special meaning and therefore can't be used in key names when referencing values. If you need to access keys containing these characters you can use the lookup helper, which permits you to pass the key name instead as a string literal and thus avoid the restriction. One common example of this issue is with array-style query parameters, so for instance if your request URLs that you're matching are of the form /myapi?ids[]=111&ids[]=222&ids[]=333 then you can access these values like:

{{lookup request.query 'ids[].1'}} {{!- Will return 2 --}}

Handlebars Helpers

In addition to the standard helpers and template functions provided by the Java Handlebars implementation by jknack (see guide), EkkoProxy supports a number of convenience helpers for simulating delays and faults, working with JSON or XML request bodies, date/time etc. as described in the following sections.

Delay & fault

Description	Example(s)
The delay helper allows for setting delays programmatically. The types of delays possible are: fixed - this delay will hold up the response such that it will not be returned until after the specified number of milliseconds has passed. This is the default delay type. uniform - this random delay follows a uniform distributed delay allowing for simulation of a stable latency with a fixed amount of jitter. lognormal - this random delay type follows a log-normal distribution curve which allows for simulation of more specific downstream latencies, such as a long tail. You can also set delays easily using the Delay tab settings - see the Mocking Delays section for details.	In the simplest form you can just write: {{delay}} or {{delay type='fixed'}} , this would add a delay of 100ms - the default value of the wait parameter. By adding the wait parameter you can then specify a fixed delay in milliseconds as seen below: {{delay wait=190}} or {{delay type='fixed' wait=190}} For a random uniform delay simply specify the type, lower and upper bounds: {{delay type='uniform' lower=200 upper=600}} , this would simulate a stable latency of 400ms +/- 200ms. The default values for the lower and upper bounds are 100ms and 500ms respectively which will be used if omitted. A log-normal delay can be set as follows: {{delay type='lognormal' median=500 sigma=0.5}} , the median is the 50th percentile of the distribution in milliseconds and sigma is the standard deviation of the distribution - a larger value results in a longer tail. The defaults for median and sigma are 500ms and 0.4 respectively. Lastly there is an option to print out the actual delay value used at the time by setting print to true. The example below only sets and displays the delay value if the JSON request body contains a top level age property with the value of 18. {{#eq (jsonPath request.body '$.age') 18}}   The delay was {{delay type='lognormal' median=500 sigma=0.5 print=true}}ms {{/eq}}
The fault helper let you set faults programmatically. The types of faults supported are: empty the fault returns a completely empty response which generally causes "socket hang up" or "empty response" error to be thrown by the client. This is the default type of fault if the type property is not given. malformed - this fault sends an OK status header, then garbage and then closes the connection. Typically causes "invalid header token" parse error thrown by the client. random - the fault sends garbage and then closes the connection. This generally causes "malformed http response" or "http parse error" thrown by the client. reset - closes the connection, with SO_LINGER set to 0 and thus preventing the TIME_WAIT state being entered. This typically causes a "connection reset by peer" type error to be thrown by the client. http - this fault allows you to directly specify the HTTP response. mock - with this fault you can configure another mock that will be used as a response. You can also set faults easily using the Fault tab settings - see the Mocking Faults section for details.	You can set a fault by simply adding the following to the body template: {{fault}} , this would trigger a fault of the empty type as the default. When a fault is fired the template processing stops and the fault is immediately returned as the response. To specify a different fault type just add the type property e.g. {{fault type="malformed"}} Note - the empty, malformed, random and reset fault types take no parameters. You can further surround faults by conditions to control when they should trigger. For instance, to make the malformed fault have a 50% chance of triggering you can use it in combination with the randomInt helper: {{#lt (randomInt lower=0 upper=99) 50}}   {{fault type="malformed"}} {{/lt}} In another example with the given JSON: { "name": "FooBar", "age": 25 } You could set a http type error to fire with a JSON error response as per below: {{#eq (jsonPath request.body '$.age') 25}}   {{#fault type="http"}}     {       "error": 1234,       "message": "my error response"     }   {{/fault}} {{/eq}} The http fault type can have the following parameters: status - sets the HTTP response status code. Defaults to 500. reason - sets the HTTP response reason phrase e.g. Internal Server Error. By default it will set the phrase corresponding with the status code. contentType - sets the HTTP response content mime type. If not specified and the given response body starts and ends with {} or <> then "application/json" or "text/xml" will be set respectively, otherwise "text/plain" is set. body - sets the HTTP response body. The body, if any, can be set either between the fault tags (as in the example above) or as an attribute (see example below). The example below shows all the properties of the http fault set: {{fault type='http' status=549 reason'my reason' body='{"error":"101"}' contentType='application/json'}} The last fault type is the mock type which allows you to refer to another mock's response. It takes one mandatory parameter id which should be the universally unique identifier (UUID) of an existing mock. If the id does not match a mock, say the mock referenced has been deleted or you made a typo, then a HTTP 404 will be sent instead. An example of this fault can be seen below. {{fault type="mock" id="b3146b5d-e470-4090-b355-3d9a5dcae227"}} You can find the UUID of a mock just after the Mock Details label just above the Mock Name field as shown below.

JSON & XML

{
    id: "123",
    "details": {
        "name": "FooBar",
        "age": 36
    }
}

{{#parseJson 'parsedObj'}}
    {
        "name": "transformed"
    }
{{/parseJson}}

<foo>
    <bar>Some value</bar>
    <things>
        <item id="123456">Item One</item>
        <item id="654321">Item Two</item>
    </things>
</foo>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope/">
    <soap:Body>
        <m:person>
            <m:name>FooBar</m:name>
        </m:person>
    </soap:Body>
</soap:Envelope>

Date & time

Random value

Number, string & array

Encoding

Miscellaneous

Complex Mocking

If you need more complex mocking then you can take advantage of the mock engine's state machine using scenarios.
In the Mock Editor you can define a mock with a Scenario Name along with the Required Scenario State and New Scenario State - note the initial Required Scenario State must be set to 'Started'. When that mock is invoked the state moves to the New Scenario State and mocks with the same Scenario Name which are having that new state as the Required Scenario State will then respond when invoked. This allows you to create complex scenarios for one or more mocked services. It's probably better explained with a few examples.
Imagine a show tip service (GET /tip) that returns a different tip every time it’s invoked. For that you would create several mocks for the same endpoint Url but that has different Required Scenario State and New Scenario State along with different tip responses. The first mock response could have a Scenario Name of 'ShowTip' with the Required Scenario State as 'Started' and say a New Scenario State as 'SecondTip' as an example (it can be any string). The next mock with the same Url and Scenario Name would have the Required Scenario State and New Scenario State as 'SecondTip' and 'ThirdTip' respectively and so forth. The last mock in the scenario would set the New Scenario State back to 'Started' thereby resetting the state machine for that mock scenario and the tips will start over. In the example given we would go through the states as per below table.

Another example would be a todo list where you have a service to get todo items (GET /todo/items) and another to add todo items (POST /todo/items). For this you could start of by creating two GET /todo/items mocks with a Scenario Name of say 'Todo List'. The first mock would have the Required Scenario State as 'Started' (with a response of one todo item) and the second mock a Required Scenario State of 'Second item added' (with a response of two todo items). Note you do not set any New Scenario State for these as that will be handled by the add todo item mock. Lastly you then create a mock for POST /todo/items which has the same Scenario Name, a Required Scenario State of 'Started' and a New Scenario State set to 'Second item added'. This means that when the POST /todo/items is invoked it will switch the state and the GET /todo/items will return the other response with the second item added on the todo list. The table below shows the different values needed to make the example work.

[
    {
        "id": 1,
        "title": "delectus aut autem",
        "completed": false
    }
]

[
    {
        "id": 1,
        "title": "delectus aut autem",
        "completed": false
    },
    {
        "id": 2,
        "title": "quis ut nam facilis et officia qui",
        "completed": false
    }
]

These examples are relatively simple in order to explain the state machine concept, but once understood, does allow you to create some very realistic and complex scenarios.

Mocking Delays

To simulate calls over a network to an API, which can be delayed for many reasons like network congestion or excessive server load, EkkoProxy supports setting different types of delays on a per mock basis. Applications need to be resilient to these types of delays and they must be designed to cope with this inevitable variability, and tested to ensure they behave as expected when conditions aren't optimal.

You can use the settings detailed below to set a mock delay or if you need more control on when one or more delays should trigger then you can use the delay helper instead which gives you full programmatic control. See the Handlebars Helpers section for more details.

The below screenshot shows an example of a log-normal distributed delay.

The settings above would produce delays ranging in time (ms) as per below graph with a mean of 2166ms and mode of 1704ms.

The different delays are described below.

Note, any delays set in the response body using the handlebars delay helper will execute before a delay set here.

Mocking Faults

In the real world APIs communicate over networks which can fail in ways that can destabilise your application. These scenarios can be hard to test with an actual web service, which is why it is beneficial to use web service mocks when testing to inject this faulty behaviour that is otherwise difficult to get the real service to produce on demand. With EkkoProxy you can set various fault types and specify how often they should occur.

You can use the settings detailed below to set a mock fault or if you need more control on when various faults should trigger then you can use the fault helper instead which gives you full programmatic control. See the Handlebars Helpers section for more details.

The below screenshot shows an example of returning the response of another mock with a 503 HTTP status code and a 50% chance of this occurring at the time the mock is invoked.

The following fault types can be selected:

For the faults types listed above you can define a frequency for how often you want the fault to occur. The frequencies are:

Note, any faults set in the response body using the handlebars fault helper will execute before a fault set here.

JDBC mocking

JDBC ResultSet objects can be mocked with JSON responses by adding a mock for the particular JDBC request URL / command path. The command path is comprised of the JDBC object name followed by the method called on it e.g. /PreparedStatement/executeQuery. To setup a mock for this command path the proxy's mock path needs to be prefixed to it e.g. /sqlrequest/PreparedStatement/executeQuery assuming the mock path was /sqlrequest when you created the proxy. The JDBC commands are treated as HTTP POST requests with the SQL query as the request body and any SQL parameters as headers. The headers will have the SQL parameter index as key and the parameter value as the header value. This means you can setup mocks with different Body Patterns and/or Header matchers to respond with different results depending on the SQL query itself. The below screenshot shows a mock for the same.

ResultSet schema

To mock a ResultSet response you have to provide the response in JSON format following the below schema.

{
    "type": "object",
    "title": "The JDBC resultset schema",
    "description": "Contains the column metadata along with the actual row data.",
    "required": [
        "cols",
        "rows"
    ],
    "properties": {
        "cols": {
            "type": "array",
            "description": "The cols property contains the JDBC ResultSetMetaData information.",
            "items": {
                "type": "object",
                "description": "Contains the column metadata items.",
                "required": [
                    "catalogName",
                    "className",
                    "displaySize",
                    "name",
                    "precision",
                    "scale",
                    "schemaName",
                    "tableName",
                    "type",
                    "typeName"
                ],
                "properties": {
                    "catalogName": {
                        "type": "string",
                        "description": "The designated column's table's catalog name."
                    },
                    "className": {
                        "type": "string",
                        "description": "The fully-qualified name of the Java class whose instances are manufactured if the
                                        method ResultSet.getObject is called to retrieve a value from the column."
                    },
                    "displaySize": {
                        "type": "integer",
                        "description": "The designated column's normal maximum width in characters."
                    },
                    "name": {
                        "type": "string",
                        "description": "The designated column's name."
                    },
                    "precision": {
                        "type": "integer",
                        "description": "The designated column's specified column size."
                    },
                    "scale": {
                        "type": "integer",
                        "description": "The designated column's number of digits to right of the decimal point."
                    },
                    "schemaName": {
                        "type": "string",
                        "description": "The designated column's table's schema."
                    },
                    "tableName": {
                        "type": "string",
                        "description": "The designated column's table name."
                    },
                    "type": {
                        "type": "integer",
                        "description": "The designated column's SQL type."
                    },
                    "typeName": {
                        "type": "string",
                        "description": "The designated column's database-specific type name."
                    }
                }
            }
        },
        "rows": {
            "type": "array",
            "description": "The actual row data as per columns described in the cols property.",
            "items": {}
        }
    }
}

ResultSet example

The below shows a ResultSet JSON example response in full.

{
  "cols": [
    {
      "catalogName": "",
      "className": "java.lang.String",
      "displaySize": 15,
      "name": "GROUP_CODE",
      "precision": 15,
      "scale": 0,
      "schemaName": "",
      "tableName": "",
      "type": 12,
      "typeName": "VARCHAR2"
    },
    {
      "catalogName": "",
      "className": "java.lang.String",
      "displaySize": 50,
      "name": "GROUP_CODE_DESCRIPTION",
      "precision": 50,
      "scale": 0,
      "schemaName": "",
      "tableName": "",
      "type": 12,
      "typeName": "VARCHAR2"
    },
    {
      "catalogName": "",
      "className": "java.math.BigDecimal",
      "displaySize": 22,
      "name": "LOOKUP_ID",
      "precision": 10,
      "scale": 0,
      "schemaName": "",
      "tableName": "",
      "type": 2,
      "typeName": "NUMBER"
    },
    {
      "catalogName": "",
      "className": "java.math.BigDecimal",
      "displaySize": 22,
      "name": "LOOKUP_TYPE",
      "precision": 6,
      "scale": 0,
      "schemaName": "",
      "tableName": "",
      "type": 2,
      "typeName": "NUMBER"
    },
    {
      "catalogName": "",
      "className": "java.lang.String",
      "displaySize": 50,
      "name": "LOOKUP_VALUE",
      "precision": 50,
      "scale": 0,
      "schemaName": "",
      "tableName": "",
      "type": 12,
      "typeName": "VARCHAR2"
    }
  ],
  "rows": [
    [
      "FOO_BAR",
      "foo bar desc",
      1401,
      19203,
      "foo bar value"
    ],
    [
      "BAR_FOO",
      "bar foo desc",
      1395,
      null,
      "BAR_FOO_VALUE"
    ],
    [
      "HUBBA",
      "Hubba bubba",
      98372,
      null,
      "HUBBA_BUBBA Value"
    ],
    [
      "Ekko Proxy",
      "Service virtualization",
      59071,
      199,
      "EKKO"
    ],
    [
      "Tools",
      "Ekko tools",
      75987,
      null,
      "The best"
    ]
  ]
}