WireMock is easy to like when it is local.
You create a few stub mappings, start the server, point your application at it, and get predictable responses. For a single developer, JSON files and the Admin API are often enough.
The interesting problems start when the same WireMock instance becomes shared infrastructure.
Now several developers are changing mappings. The number of stubs grows. Multiple mappings can target the same endpoint. Someone changes a priority. Someone else changes the same mapping. A runtime change works, but nobody is sure whether it has been persisted.
At that point, the problem is no longer just creating mocks. It is managing shared state.
That is the problem I wanted to explore with StubDeck.
StubDeck is an independent open-source project. It does not replace WireMock and is not affiliated with the WireMock project. It acts as a management layer around an existing WireMock environment.
The point where JSON stops being enough
A normal WireMock mapping is simple:
{
"request": {
"method": "GET",
"urlPath": "/api/customer/123"
},
"response": {
"status": 200,
"jsonBody": {
"name": "John"
}
}
}
With a small local setup, I would not add another tool. Editing the file directly is faster.
A shared environment creates a different set of questions:
- How many mappings are registered right now?
- Which endpoints already have stubs?
- Why did this request hit that mapping?
- Are several mappings competing for the same request?
- Which priorities are configured?
- Who changed this mapping?
- Does it have a pending runtime change?
- Has the current runtime state been persisted?
Those questions are not about JSON syntax. They are about visibility, coordination, and state management.
Making overlapping mappings visible
One of the first areas I focused on was overlapping mappings.
POST /api/payments
POST /api/payments
POST /api/payments
The same method and URL do not automatically mean the mappings are equivalent. Headers, body matchers, query parameters, and other request criteria can make them intentionally different.
But this is still a useful place to look for ambiguity.
WireMock has a priority mechanism for this. A lower numeric value means a higher priority. If multiple matching stubs have the same priority, the most recently added matching stub takes precedence.
StubDeck groups mappings by method and URL on a Conflicts page so these areas can be inspected directly instead of discovered by searching through files.
POST /api/payments
Priority 1 Payment declined by risk
Priority 5 Payment approved
Priority 10 Default payment response
When a mapping is saved, StubDeck can apply a conflict strategy: BLOCK, WARN, or ALLOW.
A form when it helps, raw JSON when it does not
For common changes, a form is convenient:
Method: POST
URL: /api/payments
Status: 200
Priority: 5
But a WireMock mapping can be much richer than a fixed form. I did not want the UI to hide WireMock itself.
The editor therefore supports both a form for common request/response fields and a Raw JSON view. JSON can be validated before it is saved, and templates provide starting points for common REST and error scenarios.
Pending changes become ownership
The next problem appears only when several people use the same server.
StubDeck tracks runtime changes that have not yet been persisted or discarded. A pending change has an owner. While that pending change exists, another user cannot silently overwrite or delete the same mapping.
Pending change by: Ivan Petrov
This is deliberately simpler than a distributed collaborative editing model. It solves a practical problem: make ownership of an unfinished runtime change visible and prevent accidental overwrites.
Runtime state is not persisted state
This matters especially in containerized shared environments.
WireMock exposes an Admin API for changing mappings at runtime and an operation for persisting mappings. Treating runtime state and persisted state as the same thing can produce a surprise after a restart.
StubDeck makes the distinction explicit and exposes two high-level actions:
Save to disk
Discard changes
The goal is not to invent a new persistence model. It is to make the existing lifecycle visible.
Who changed this mapping?
Once a mock server becomes shared, this question appears sooner or later.
StubDeck keeps a changelog for CREATE, UPDATE, and DELETE operations, including the user, mapping, and timestamp.
2026-11-07 15:42
UPDATE
ivan.petrov
POST /api/payments
That does not turn StubDeck into a version control system, but it is enough to answer a common debugging question quickly.
Two ways to connect
StubDeck supports two mapping sources:
- File system for direct work with mapping JSON files.
- Admin API for an already running WireMock instance.
StubDeck does not proxy mocked application traffic. It sits next to WireMock as a management layer.
Why not just keep editing JSON?
You should, when that is the simplest solution.
If one developer owns a small local WireMock setup, adding a management UI can be unnecessary overhead.
The tool starts to make sense when several conditions appear together:
- many mappings
- shared WireMock
- multiple developers
- overlapping endpoints
- runtime changes
That is the distinction I care about. StubDeck is not an attempt to make JSON prettier. It is an attempt to manage a shared WireMock environment.
Current state and limitations
The current project uses Java 25 and Spring Boot 4.0.5. The local development environment uses WireMock 3.13.2 through Docker Compose, together with a test LDAP server.
There are also intentional limitations in the first public version:
- one WireMock instance is managed at a time;
- StubDeck itself must run as a single application replica;
- a production Docker image for StubDeck is not provided yet;
- multi-instance and multi-replica support are roadmap items.
The single-replica restriction is not a throughput limitation. Pending-change ownership and the changelog currently depend on local application state. Multiple replicas would need shared state and coordination to preserve consistent behavior.
What I want to build next
The first major direction is multi-instance support.
The second direction is change management. Instead of recording only individual actions, I want to treat a group of changes as a unit:
Change set #42
+ CREATE POST /payments
~ UPDATE GET /accounts/*
- DELETE GET /legacy/user
[View diff] [Apply] [Discard]
That naturally leads to diffs, rollback, review, and eventually promotion of a change set between environments.
Why I am publishing it
I am publishing StubDeck because I want to understand how common this problem is outside the environments I have worked with.
I am especially interested in teams that:
- have hundreds or thousands of mappings;
- share one WireMock instance across developers or teams;
- run separate DEV, QA, or integration environments;
- need an audit trail for mapping changes;
- regularly deal with overlapping stubs and priority questions.
GitHub: https://github.com/SlavaDenisenko/stubdeck
If that sounds familiar, I would like to hear how you manage it today and which part is the most painful.
Technical references
- WireMock stubbing and priority: https://wiremock.org/docs/stubbing/
- WireMock Administration API: https://wiremock.org/docs/standalone/administration/
- WireMock Admin API reference: https://wiremock.org/docs/standalone/admin-api-reference/



Top comments (0)