Service Virtualisation Tools

WireMock handles 90% of HTTP dependency stubbing needs. But service virtualisation is a broader discipline that covers scenarios WireMock cannot: simulating stateful multi-step conversations, replaying captured real traffic, stubbing non-HTTP protocols, and virtualising third-party systems you cannot control at all. This lesson maps the landscape so you can choose the right tool for each situation.

Where simple stubs stop working

Most microservice component tests need nothing more than WireMock returning a fixed JSON body. But three categories of real-world dependencies push past what a stateless HTTP stub can handle.

Stateful multi-step conversations: a payment API has three steps — POST /payments/initiate returns a session token, POST /payments/confirm (with that token in the request body) charges the card, and GET /payments/{id} returns the final status. A simple WireMock stub can simulate each endpoint independently, but it cannot enforce that step 2 must supply the exact token returned from step 1. Service virtualisation tools maintain state across requests — they remember what happened in earlier calls and can vary their responses accordingly.

Capture and replay: an external shipping carrier API is expensive to call in testing, rate-limited, and returns responses with formats that are difficult to predict accurately from documentation alone. Service virtualisation tools let you capture real traffic once by proxying through them, then replay that captured traffic in tests — deterministic, free, and unaffected by rate limits. You stub based on what the API actually returns, not what the documentation says it returns.

Non-HTTP protocols: a legacy billing system speaks SOAP over JMS. A logistics system uses SFTP for batch file transfers. WireMock is HTTP-only; if your microservices integrate with non-HTTP protocols in any meaningful part of their flow, you need a tool with broader protocol coverage.

The tool landscape

WireMock (HTTP, free, open-source)

• Best for: straightforward HTTP/HTTPS request-response stubbing
• Strengths: easy setup, excellent Java integration, flexible request matchers, outstanding documentation, active community
• Use when: 90% of cases — simple HTTP stubs in component and integration tests
• Limitation: stateless by default (WireMock has a basic scenario state machine, but it is limited and does not model multi-request token flows)

Hoverfly (HTTP/HTTPS, free, open-source, capture-replay)

• Best for: capturing real API traffic from a third-party service and replaying it deterministically
• Three modes: capture (acts as a transparent HTTP proxy, recording all requests and responses), simulate (replays captured interactions without touching the real API), and modify (replays but allows transformation of responses mid-flight)
• Use when: a third-party API is too complex or unpredictable to stub manually, but you can capture one real session against a sandbox
• Example: capture one real Stripe payment flow in the Stripe sandbox, export the simulation, and replay it deterministically in every subsequent test run

Mountebank (HTTP, HTTPS, TCP, SMTP — multi-protocol, free, open-source)

• Best for: when you need protocol coverage beyond HTTP
• Runs as a standalone server and is configured entirely via its REST API, making it easy to script from any language
• Supports complex predicate matching, response injection with JavaScript, and full state machines called imposters
• Use when: your services integrate with SMTP email delivery services, raw TCP services, or a mixed-protocol legacy layer

WireMock Cloud / enterprise tools

• Best for: large teams that need collaboration on shared virtual services, persistent virtual service catalogs, or virtualisation of mainframe and SAP systems
• Managed, collaborative, and expensive — appropriate when the self-hosted open-source tools create more operational overhead than the licensing cost justifies

Capture-replay with Hoverfly: a practical walkthrough

Hoverfly's capture-replay cycle is straightforward once you understand that it acts as an HTTP proxy sitting between your application and the real third-party API:

# Step 1: Start Hoverfly in capture mode (acts as HTTP proxy)
hoverfly -capture
 
# Step 2: Run your app with Hoverfly as the HTTP proxy
export HTTPS_PROXY=http://localhost:8500
export HTTP_PROXY=http://localhost:8500
./run-your-app.sh  # makes real calls to the third-party API, Hoverfly records them
 
# Step 3: Export captured interactions to a simulation file
hoverfly export stripe-simulation.json
 
# Step 4: In tests, start Hoverfly in simulate mode
hoverfly -simulate -import stripe-simulation.json
# Now your app calls localhost:8500 and gets the pre-recorded responses

In a Node.js test suite, the Hoverfly SDK wraps this lifecycle cleanly:

const hoverfly = new Hoverfly();
await hoverfly.start();
await hoverfly.importSimulation('./stripe-simulation.json');
// Your test code here — all HTTP calls return captured responses
await hoverfly.stop();

The simulation file is a JSON document that records every request URL, method, headers, and the corresponding response. Inspect it after capture to understand exactly what your application sent and received — this is often more informative than reading the API documentation.

Choosing the right tool

The decision is straightforward if you match the tool to the concrete gap you need to fill:

• Default to WireMock — it covers the majority of microservice HTTP stubbing needs with minimal setup and maintenance overhead
• Add Hoverfly when you need capture-replay for a complex third-party API where manual stubbing is error-prone or where the API evolves faster than you can maintain stubs manually
• Consider Mountebank when your services use non-HTTP protocols in their integration points and you need realistic simulation of those protocols in tests
• Evaluate enterprise tools only when you have mainframe integrations, teams large enough to need shared collaborative virtual service catalogs, or compliance requirements for virtualisation documentation

⚠️ Common mistakes

• Over-investing in service virtualisation when WireMock stubs suffice. Service virtualisation tools add setup overhead, a new process to manage, and maintenance cost when APIs change. If your tests only need simple request-response HTTP stubs, WireMock is the right tool. Reach for Hoverfly or Mountebank only when you have a concrete gap that WireMock demonstrably cannot fill.
• Capturing real traffic that includes credentials or PII. Hoverfly capture mode records the full request and response, including authorization headers, API keys, and any personally identifiable information in response bodies. Always sanitise exported simulation files before committing them to source control — a captured session token in a public repository is a real security incident waiting to happen.
• Treating a captured simulation as permanent truth. Third-party APIs evolve. A captured Stripe response from six months ago may no longer match the current API's response format, field names, or error codes. Re-capture periodically against the vendor sandbox, or supplement captured simulations with schema validation tests run against the live sandbox to detect drift before it reaches your test suite.

🎯 Practice task

1. Identify one dependency in your system that is genuinely hard to stub manually — an external payment provider, a complex CRM, or a legacy SOAP service. Write down specifically what makes it hard: is it stateful across multiple requests? Does it use a non-HTTP protocol? Are its response formats too varied to predict from documentation?
2. Set up WireMock's scenario state feature for a two-step stateful interaction — for example, a payment initiation that returns a token, followed by a confirmation that must supply that token. Write a test that verifies the state transitions correctly. What does this pattern solve that a simple independent stub cannot?
3. Install Hoverfly locally (brew install hoverfly on macOS, or download from hoverfly.io). Run it in capture mode against a public API such as jsonplaceholder.typicode.com. Export the simulation file and inspect its JSON structure. How does it compare in structure to a WireMock stub mapping — what information does it capture that a hand-written stub would typically omit?
4. Research Mountebank's imposter concept at mbtest.org. Write the JSON configuration for an imposter that simulates the same two-step payment flow you implemented in WireMock in step 2. What does Mountebank's state machine model offer that WireMock's scenario model does not?
5. For your system, write a one-page service virtualisation strategy: list every external or cross-service dependency that needs to be virtualised in tests, identify which tool you would use for each dependency, and explain the specific reason that tool is the right choice over the alternatives.

The next lesson covers contract testing with Pact — the mechanism that keeps your stubs honest by verifying them against the real providers.