Build WireMock mappings fast from real traffic

I’m a big fan of service mocking. I’ve been working in and around software for about 25 years, and one thing never changes: when you sit down to work on your code, you almost never have everything available. The database, the third-party API, the message queue, the service two teams over. Something’s missing. So you’ve got to stub it out or mock it out and keep moving.

I’ve followed the WireMock project for years because of this. If you work in and around Java and microservices, you need a way to mock your dependencies, and WireMock is a great fit. It drops right into your unit tests, you can spin up a mock in seconds, and the mapping files live in your own repo next to the code they’re standing in for. The open source code lives in the wiremock/wiremock GitHub repo.

You already have the data

Here’s the part most people skip past. The hard work in a WireMock mapping is the data, not the syntax. You need the real endpoint that was called and the exact response the app sent back, and you need it to look like production rather than something you made up. If you’re running Speedscale, you already have all of it. We capture the real requests and responses flowing through your app, which is exactly what you’d otherwise sit and hand-write into a stub.

A friend at WireMock pointed this out to me at a conference and it stuck. We’d had a WireMock importer for a while, so if you’ve already got mappings we’ll pull them in. Going the other direction was the obvious missing half.

So we built the exporter

In the latest version of Speedscale you can take recorded traffic and write it straight out as WireMock mappings:

proxymock export wiremock --in ./proxymock --out mappings.json

Each eligible complete HTTP or HTTPS pair becomes a stub after filtering. The method, path, and recorded query values form the default matcher; the recorded status, response headers, and body form the response. I left request headers out of the matching on purpose so a stub doesn’t get pinned to whatever auth token you happened to record that day. You want it to match and serve.

From there it’s plain WireMock:

docker run -d -p 8080:8080 wiremock/wiremock
curl -X POST http://localhost:8080/__admin/mappings/import --data @mappings.json

I didn’t want to ship a format that only looks right on paper, so I ran it against the real wiremock/wiremock Docker image, not a fake one. Recorded four endpoints off our banking demo’s API gateway (accounts, transactions, a profile lookup, a login), exported them, loaded them, and every call came back with the recorded response. WireMock even stamps a Matched-Stub-Id header so you can see which stub it hit. A path I never recorded gave back a 404, which is exactly right.

Try it yourself

That whole run is a script in the public wiremock export demo. All you need is Docker.

git clone https://github.com/speedscale/demo
cd demo/wiremock-export-demo
./run-demo.sh

It exports a bundled recording to WireMock mappings, starts the real wiremock/wiremock container, loads the mappings through the admin API, and replays those four banking endpoints to check each one comes back with the recorded body. The last thing it does is hit a path that was never recorded so you can watch WireMock return a 404.

To do it with your own service instead, record some traffic and point the exporter at it:

proxymock record -- your-app-command
proxymock export wiremock --in ./proxymock --out mappings.json

Then load mappings.json into WireMock the same way the demo does.

If you’re already keeping WireMock mappings in your repo, this is just a faster way to write them. Record the real thing once and let it generate the stubs instead of guessing at them by hand.

And if you’re still deciding where WireMock fits next to the other mocking tools, I wrote up how I think about the alternatives a while back. This is the piece that makes the recording part easy.

Thanks for the nudge.

Frequently asked questions

Can I keep editing the generated WireMock mappings?

Yes. The output is a standard WireMock mappings document. Add request-body matching, priorities, templating, or stateful behavior when the scenario requires it, and validate the edited result in WireMock. Keep generated output separate from reviewed custom changes or merge them deliberately: re-exporting a recording does not preserve edits made only to the previous output file.

How are credentials and dynamic values handled?

Omitting request-header matchers prevents a recorded Authorization header from constraining a stub; it does not sanitize the recording or response. Query values, response headers, and bodies can still contain sensitive or changing data. Inspect the generated document, redact before sharing, and add deliberate matchers or templates. Different request bodies can otherwise select the same loosely matched stub.

Which requests are eligible for export?

The exporter uses complete HTTP or HTTPS request/response pairs, with inbound traffic selected by default. Use the service, direction, and limit filters for the intended dependency. This is not a generic export of every recorded protocol. Inspect the mappings count and matching fields, particularly duplicate paths, repeated query parameters, and requests distinguished by their bodies.

Sources: Speedscale WireMock export, WireMock request matching, Stateful mock scenarios, Capture redaction rules.