How does OutMock work?

OutMock allows you to create a fake or 'mock' implementation of your external REST API's that can be programmed to behave the way you like. In Service Center (only on dev) you then configure your application to no longer point to the real API endpoint, but to call the mock endpoint instead. 

During normal operation, all requests to this mock will forward the requests to the actual, real API.

During tests (when the mock receives requests with the header "X-Test-Id") the mock will not forward to the real API but will only respond with preconfigured responses that you can program from within your tests.

In your test you can then program the mock to respond with specific data given a specific request, before calling your application code that will call the external API.

This would, for example, look something like this:

• Setup
  • In the setup you make sure your application will send an X-Test-Id header in all outgoing requests to your external REST API that you are mocking. Check the demo and OutMock demo test forge component to see how this can be done using the CallContext Forge component.
• "Given Products API returns 5 products"
  • In this step you would program the mock to respond with 5 products. 
  • You do this by calling a Service Action on your mock module that calls OutMock's RegisteredMock_Create action to register a mock response, given a specific input.
• "When I get my list of products"
  • In this step you call your application.
  • If the setup was done correctly, your application will not call the real REST API, but your mock. The mock will see the X-Test-Id header and will respond with the registered response set in the given step. 
• "Then I get 5 products"
  • We can assert that we get the same number of products as were returned from the mock.
• "Then I called the Products API with the correct inputs"
  • We can use OutMock's GetRegisteredInvocations action to get information (request + response) on the requests that were handled by the mock, and the data that was received and returned.

Setting up your mock

To set up your mock, create a Service module that exposes a REST API with the same endpoints as the API you want to mock.

So for each endpoint (path) on your real API, add an endpoint on your mock.

Don't worry about query parameters or request body, they will be mapped automatically. There is no need to define them in your mock. Just focus on the Path, the path parameters and the HTTP method (GET, POST, ...). Return your response as Text. No need to map it to a structure.

Inside of each endpoint of your mock, call OutMock's MockRequest server action. That will handle all the mocking and forwarding for you. Just return the response as Text.

In the demo, in module ProductsAPI_Mock this looks like this:

Notice that as inputs only the path parameters are mentioned.

As output, all responses are of type Text.

In each endpoint, call MockRequest, like this:

Now for testing convenience, create the following Service Actions for each endpoint:

• <my_endpoint>_When
  • This will be used in your test to register responses on the mock for this endpoint.
• <my_endpoint>_GetInvocations 
  • This will be used in your test to return invocations done on the mock on this endpoint.

Example from the demo:

Adapting your application to pass X-Test-Id

In order for the mock to know whether or not it is running inside a BDD Test, you need to send the header "X-Test-Id" on outgoing requests to the mock. You can do that in the OnBefore of your _IS module that calls the external REST API, like so:

See OnBeforeRequest in Products_IS in the demo:

Testing using the mock

Check the OutMock Demo - BDD Tests Forge component for an example on how to test the demo.

It shows how to set a TestId on CallContext, so that mocking is activated. And how to prepare in the given steps and verify the mock in the then steps in the BDD framework.