Tirthal's Tech Cafe - Java Platform and Software Engineering related blogs and articles: WireMock - A simple standalone HTTP server for service virtualization

I hope, you have already read "Preface" of my java power tools series. In this post, I intend to introduce WireMock tool.

Straight from the horse's mouth

WireMock

Mock your APIs for fast, robust and comprehensive testing using WireMock (a simulator for HTTP-based APIs / service virtualization tool / mock server)
Enables you to stay productive when an API you depend on doesn't exist or isn't complete
Supports testing of edge cases and failure modes that the real API won't reliably produce
Features = HTTP response stubbing, request verification, proxy/intercept, record/playback of stubs and fault injection
Flexible deployment options - run it from within your Java application, JUnit test, Servlet container or as a standalone process
Powerful Request Matching - Match request URLs, methods, headers cookies and bodies using a wide variety of strategies & first class support for JSON and XML
Record and Playback - Get up and running quickly by capturing traffic to and from an existing API

My Personal Feedback

I witnessed that WireMock's is extremely easy to setup and harness. This tool can benefit appreciably in MicroServices Architecture. Let me explain two scenarios, where I could take advantage of WireMock.

(1) Create quick prototypes of REST APIs

Many times, services are not implemented by REST server apps or made available by external vendors. Still, there is a pressing need to develop REST client app beforehand, may be for demo purpose or meeting deliverable goals or due to any other business need. Well, WireMock can help here to create prototypes of agreed APIs quickly, which can be consume by client apps even without realizing these are stubbed APIs instead of real. See running wiremock as a standalone process option.

(2) Record real external services and playback

At times, client app needs to consume third-party or external services over internet or network. However, there are frequent connectivity issues or high latency problem or only limited requests are supported per day due to chargeable services, specifically while accessing these services in Development. Obviously, this may result in high developer productivity loss. Well, WireMock has unique ability to record real services (requests and responses) without a need of single line of coding and playback those in even offline mode automatically. WireMock's this record/playback of stubs feature can greatly boost developer productivity. See record and playback option.

Other scenarios you might want to consider WireMock for:

Testing mobile apps that depend on third-party REST APIs
Injecting otherwise hard-to-create errors in 3rd party services
Any unit testing of code that depends on a web service

All in all, WireMock is a Java-based flexible library with a JSON API that can be used to virtualize, mock, and stub web services.

Try WireMock Practically

Now let's understand fundamental ability of WireMock by running it as a standalone HTTP server and stubbing web services. Let's see practically how effortless it is.

ABC of WireMock standalone server

Download WireMock jar latest version @ http://repo1.maven.org/maven2/com/github/tomakehurst/wiremock-standalone/

To POST data to WireMock's REST endpoint (i.e. http://localhost:9999/__admin/), you can use curl or postman tool or any other choice of tool.

Start wiremock as a standalone server: java -jar wiremock-standalone-2.6.0.jar --port 9999 --verbose true
This would create "__files" and "mappings" folders (in the same folder where wiremock jar exists) to store stubbed services. To see what all service stubs exist on WireMock server (within "__files" and "mappings" folders), open admin console in browser: http://localhost:9999/__admin/
To stop wiremock, just kill the process or post a request with an empty body to this REST endpoint: http://localhost:9999/__admin/shutdown
For more detail, see @ http://wiremock.org/docs/running-standalone/.

Stubbing Services / Create REST APIs Prototypes

A core feature of WireMock is the ability to return canned HTTP responses for requests matching criteria. These criteria can be defined in terms of URL, headers and body content.

Post a stub mapping via the JSON API to this REST endpoint (not persisted, so will lose this after restarting server): http://localhost:9999/__admin/mappings/new
Stub mappings which have been created can be persisted to the mappings directory via a POST request with an empty body to this REST endpoint: http://localhost:9999/__admin/mappings/save
Open admin console in browser to validate the added stub mappings: http://localhost:9999/__admin/
Access mock REST services in browser: http://localhost:9999/hello-world
To reset all mock request url mapping and response data, just delete all files from "mappings" and "__files" folders.

For more detail, see @ http://wiremock.org/docs/stubbing/

Record external services and Playback

WireMock has the ability to create stub mappings by recording them while you send requests. This can be used to quickly capture a collection of responses from a real service then use them offline in your tests.

For Example, run this command to record and playback Github Developer APIs:

Run WireMock server to proxy all requests of Github: java -jar wiremock-standalone-2.6.0.jar --proxy-all="https://api.github.com" --port="9999" --record-mappings
Access Github APIs via WireMock: http://localhost:9999/users/tirthalpatel

For any requested REST service request (i.e. http://localhost:9999/users/tirthalpatel), first of all WireMock would check, if corresponding stub mapping exists in "mappings" folder or not. If existing, then don't hit real service rather serve recorded data from "mappings" and "__files" folders. If not existing, then WireMock calls external real service (i.e. https://api.github.com/users/tirthalpatel) followed by records stub mapping followed by returns response to the client. That means, we can expect WireMock to playback all recorded stub mappings even if internet is unavailable.