When the blue pill is good enough: create the mock service
Wiremock is an HTTP server that is designed to be easily configurable so that it acts as a mock server. I love it. In fact I started writing my own (Lefkogeia) and stopped when I found Wiremock since it was so obviously exactly what I needed.
It’s very easy to run standalone (they also have also a not-free cloud service, well worth its money). Follow these steps:
- Install Java (the JRE is enough) if you don’t have it already
- Inside our base directory GraubFinanceMockService, create an empty folder, say wiremock.
- Download the jar from this page using the link “Once you have downloaded the standalone JAR“. Save it in the wiremock folder.
- With a text editor, create a file named start-wiremock.cmd (or whatever script extension your OS has) and paste the following (assuming java is somewhere in the path):
java -jar wiremock-standalone-2.25.1.jar --global-response-templating --port 8888
Check the jar file name to match whatever you downloaded. You can also change the port to whatever you like.
To test that everything works, run the script and then open a browser and navigate to http://localhost:8888 . In the command window you should have the Wiremock logo and a few details, and in the browser you should get “HTTP ERROR 403 Problem accessing /__files/. Reason: Forbidden”. If so, it all works correctly. If not, well, check the error message in the command window. To stop the service just close the window.
Now let’s configure it.
In the wiremock folder, create two subfolders “mappings” and “__files” (if you ran it, they will have been created already). In the mappings folder you will put the service definitions and in the __files folder any necessary attachments like image, xml or json files.
So create a text file in mappings, name it “base.json” and paste the following:
{
"request": {
"method": "GET",
"url": "/servicehealth"
},
"response": {
"status": 200,
"body": "Service is up and running!",
"headers": {
"Content-Type": "text/plain"
}
}
}
Now run the script and navigate your browser to http://localhost:8888/servicehealth . That’s what you should see:
Now that we got the basics working, let’s create the mock service. We’ll create a new json file in the mappings folder -you can have as many as you want, they’re combined. Let’s call the new file CustomerTrust.json.
Remember we need to respond to GET and POST for the url http://HOSTNAME/api/1.0/CustomerTrust/ID right? A first try for the GET could be like this:
{
"request": {
"method": "GET",
"urlPattern": "/api/1.0/CustomerTrust/([a-zA-Z0-9-.]{1,})"
},
"response": {
"status": 200,
"bodyFileName": "CustomerTrustInfo.json"
}
}
Notice that with urlPattern, the accepted path is now a regular expression –which gives you a lot of flexibility.
In the __files folder, create a text file named CustomerTrustInfo.json with the following content (remember we just convert stuff from our swagger file):
{
"name": "GlarusAdvertising AG",
"taxid": "CHE-123.456.789",
"trustlevel": "OK"
}
Run the script again and navigate your browser to http://localhost:8888/api/1.0/CustomerTrust/123 . You should get the contents of CustomerTrustInfo.json.
Now, obviously, the tax id we gave in the url (123) doesn’t match the taxid in the json (CHE-123.456.789). But Wiremock can take data from the request and use it in the response: it’s called response templating. Remember the –global-response-templating in the script? It enables exactly this behavior.
So to get the tax id from the request path, change CustomerTrustInfo.json as follows:
{
"name": "GlarusAdvertising AG",
"taxid": "{{request.requestLine.pathSegments.[3]}}",
"trustlevel": "OK"
}
The double brackets {{ … }} tell wiremock that this part should be substituted. The expression request.requestLine.pathSegments.[3] tells it to get the 4rd part (it counts from zero) of the url’s path. The path part of url is /api/1.0/CustomerTrust/(taxid) so the tax id is in the 4th place.
So start the script and navigate to http://localhost:8888/api/1.0/CustomerTrust/CHE-12345. You should get:
{
"name": "GlarusAdvertising AG",
"taxid": "CHE-12345",
"trustlevel": "OK"
}
Ok, but what about authentication? As OAuth 2.0 dictates, our request has to have a valid JWT token in the header named “Authorization” with content “Bearer (token)”. E,g,
Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42
Now for our example let’s keep it relatively simple. We won’t validate anything except that the header is there. If not, we’ll return HTTP 401. Let’s add a 404 “not found” for good measure as well. So change the CustomerTrustInfo.json as follows:
{
"mappings": [
{
"priority": 10,
"request": {
"method": "GET",
"urlPattern": "/api/1.0/CustomerTrust/([a-zA-Z0-9-.]{1,100})",
"headers": {
"Authorization": {
"contains": "Bearer"
}
}
},
"response": {
"status": 200,
"bodyFileName": "CustomerTrustInfo.json"
}
},
{
"priority": 90,
"request": {
"method": "ANY",
"urlPattern": "/api(.*)",
"headers": {
"Authorization": {
"contains": "Bearer"
}
}
},
"response": {
"status": 404,
"body": "Server path {{request.path}} not found",
"headers": {
"Content-Type": "text/plain"
}
}
},
{
"priority": 99,
"request": {
"method": "ANY",
"urlPattern": "/api(.*)"
},
"response": {
"status": 401,
"body": "401 Unauthorized",
"headers": {
"Content-Type": "text/plain"
}
}
}
]
}
Notice the priorities. If the request matches the one in the first priority 10 (with the correct path and the Authorization header) the json is returned. If the request matches the one in priority 90 (under/api with Authorization header), 404 is returned. If the request matches priority 99 (under /api but without the Authorization header), the 401 is returned.
This done, let’s also create the POST part. This could be like that (we’ll put in the mappings section with the rest):
{
"priority": 20,
"request": {
"method": "POST",
"urlPattern": "/api/1.0/CustomerTrust/([a-zA-Z0-9-.]{1,})",
"headers": {
"Authorization": {
"contains": "Bearer"
}
}
},
"response": {
"status": 200,
"bodyFileName": "ReportStatus.json"
}
}
In the __files folder, create a text file named ReportStatus.json with the following content:
{
"reportid": "{{jsonPath request.body '$.reportid'}}",
"status": "OK"
}
Let’s test it. As this is a POST, we can’t test it with a browser. We’ll need curl for that, so install it if don’t have it already. In the wiremock folder, create a file named CustomerTrustReport.json, which we’ll use to test the service:
{
"reportid": "edbf8395-ac62-4c8c-95c3-d59a488dee7e",
"reporttaxid": "CHE-123.456.789",
"taxid": "CHE-555.456.789",
"trustlevel": "WARN"
}
Then in a command window enter:
curl -X POST "http://localhost:8888/api/1.0/CustomerTrust/CHE-123.456.789" -H "accept: */*" -H "Authorization: Bearer 1234" -d @CustomerTrustReport.json
You should get the following:
{
"reportid": "edbf8395-ac62-4c8c-95c3-d59a488dee7e",
"status": "OK"
}
Of course, if you omit the Authorization header in curl (the -H “Authorization: Bearer 1234” part) you’ll get the 401 error.
So we have a working mock service! That’s how the complete mapping file CustomerTrust.json looks like:
{
"mappings": [
{
"priority": 10,
"request": {
"method": "GET",
"urlPattern": "/api/1.0/CustomerTrust/([a-zA-Z0-9-.]{1,})",
"headers": {
"Authorization": {
"contains": "Bearer"
}
}
},
"response": {
"status": 200,
"bodyFileName": "CustomerTrustInfo.json"
}
},
{
"priority": 20,
"request": {
"method": "POST",
"urlPattern": "/api/1.0/CustomerTrust/([a-zA-Z0-9-.]{1,100})",
"headers": {
"Authorization": {
"contains": "Bearer"
}
}
},
"response": {
"status": 200,
"bodyFileName": "ReportStatus.json"
}
},
{
"priority": 90,
"request": {
"method": "ANY",
"urlPattern": "/api(.*)",
"headers": {
"Authorization": {
"contains": "Bearer"
}
}
},
"response": {
"status": 404,
"body": "Server path {{request.path}} not found",
"headers": {
"Content-Type": "text/plain"
}
}
},
{
"priority": 99,
"request": {
"method": "ANY",
"urlPattern": "/api(.*)"
},
"response": {
"status": 401,
"body": "401 Unauthorized",
"headers": {
"Content-Type": "text/plain"
}
}
}
]
}
Of course we can -and in reality should- add a lot more. Especially useful would be to verify that the json provided by the POST has the correct attributes in place. One way to do that would be to check the json via further request matching on the POST, and then have a second POST section with lower priority (say, 50) that does not verify the json. This second POST then should return HTTP 400 (Bad Request) and a message like “Invalid JSON”.
But let’s stick with this for now (this post is arguably too long already) and start working on deploying the mock service. It’s docker time!
Dot Jim 
2 thoughts on “Design by contract Tutorial, part 2/6: [Wiremock] Mock your interfaces using Swagger, Wiremock, Docker, Azure Devops, Terraform and Azure”