Migrating from WireMock¶
FastMock reads WireMock 3.x stub mappings, keeps their matching semantics where they exist in both tools, and reports what it cannot convert. A migration usually takes three steps: import the mappings, adapt the test code, and adjust the few behaviours that differ on purpose.
The field-by-field conversion table is on WireMock and MockServer import; this page is about the process.
- 1. Import the mappings
- 2. What behaves differently
- 3. Change the test code
- 4. Replace the WireMock container or server
- Checklist
1. Import the mappings¶
Mappings come from a WireMock project's mappings/ directory, or from a running WireMock with
GET /__admin/mappings. Body files from __files/ are uploaded separately with the same relative names.
export FASTMOCK=http://localhost:9090
# body files referenced by bodyFileName
(cd wiremock/__files && find . -type f | sed 's|^\./||' | while read -r f; do
curl -sf -X PUT "$FASTMOCK/__admin/files/$f" -H "Authorization: Bearer $FASTMOCK_TOKEN" \
-H 'content-type: application/octet-stream' --data-binary @"$f" >/dev/null || echo "failed: $f"
done)
# one mapping file at a time, all under one tag; check with dryRun first
for f in wiremock/mappings/*.json; do
curl -s -X POST "$FASTMOCK/__admin/import/wiremock" \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' \
-d "{\"mappings\": $(cat "$f"), \"tag\": \"wm-$(basename "$f" .json)\", \"dryRun\": true}" \
| jq -c '{file: "'"$f"'", stubs: (.stubs | length), warnings}'
done
Read every warning. They name the mapping and the part that was dropped, for example:
{"imported": 12, "removed": 12, "warnings": ["mapping #4: customMatcher (Java extension) is not supported and was ignored"]}
Then run the same loop without dryRun. Each import replaces the stubs of its tag, so the loop is safe to
re-run. POST /__admin/import detects the format automatically if you have mixed sources
(Importing).
For Kubernetes, put the mappings into a ConfigMap and let the operator import
them (MockApi.spec.wiremock); every change of the ConfigMap is re-imported.
2. What behaves differently¶
| Topic | WireMock | FastMock | What to do |
|---|---|---|---|
| Ports | Mocks and /__admin on one port |
Mocks on 8080, admin API on 9090 | Point admin clients to the admin port. |
| Admin authentication | Off by default | Always on, bearer tokens with roles | Create tokens (Security). |
| Admin API | /__admin/mappings, /__admin/requests... |
/__admin/stubs, /__admin/requests, /__admin/verify... |
See Admin API; the verification table maps the calls. |
| Extensions | Java extensions, custom matchers and transformers | No user code; plugins are compiled into FastMock | Express the logic with matchers, templates and scenarios, or ask for a plugin. |
| Response templating | Opt-in per stub (response-template) or global |
On by default for stub responses; "templated": false turns it off |
Imported stubs keep their WireMock setting. |
| Template data | request.path.[0], request.path.id, request.headers.X-Id, multi-valued request.query.x |
request.pathSegments.[0], request.pathParams.id, request.headers.[x-id] (lower case), request.queryAll.x / request.headersAll.[x-id] |
Converted on import (also inside webhooks' originalRequest); new stubs use the FastMock names (Templating). |
now and randomInt |
{{now}} has no milliseconds; randomInt excludes upper and starts at -2147483648 without lower |
{{now}} has milliseconds; randomInt includes upper and starts at 0 |
Imported templates are rewritten to WireMock's results (format='isoSeconds', upper minus one, explicit bounds). |
| Equal priority | The newest stub wins; POST /__admin/mappings/import adds a document from last to first, so its first mapping wins; URL specificity is not used |
Native stubs: the more specific URL, then the newest | Imported mappings keep WireMock's rule through an order field (Stub lifecycle). WireMock loading a mappings/ file with several mappings lets the last one win instead; if a file relies on that, give its mappings explicit priorities. |
| JSONPath | Jayway: =~, in, nin, length(), filters on objects |
RFC 9535 for native stubs; imported matchers use jsonPathDialect: "jayway" |
contains, subsetof, anyof, noneof are not supported: those mappings are skipped with a warning naming them (jsonPath). |
matchesJsonPath with equalToJson, matchesJsonSchema, equalToXml |
Applied to the selected node | jsonPath + valueBody |
Converted; a sub-matcher that cannot be converted skips the mapping rather than matching more. |
ignoreExtraElements |
Also allows extra array elements | Same (ignoreExtraArrayItems) |
Converted. |
fault: EMPTY_RESPONSE |
Closes the connection without a byte | Same | Converted. |
| Header arrays | One header line per value (two Set-Cookie lines) |
Same | Converted. |
| Empty imports | A document that yields no stub ({"mappings": 5}, a misspelled mappings key) answers 400 and changes nothing |
Read the error. | |
| Webhooks | Fire-and-forget from the JVM | Durable callbacks with retries, HMAC, correlation, egress policy | Callbacks to localhost are blocked by default: use service names (Callbacks). |
| Persistence | In memory unless persistent |
Every stub is stored; shared by all replicas in postgres mode |
Tag stubs per test and delete by tag in teardown. |
| Request journal | Synchronous | Written right after the response, asynchronously | Wait for requests (awaitRequests, /requests/count) instead of reading once. |
| Unmatched requests | 404 with a diff report in the body | 404 {"error":"no stub matched",...}; near misses through the admin API, or in the body with FASTMOCK_UNMATCHED_DETAILS=true |
Verification. |
| Proxy and recording | proxyBaseUrl, recorder |
response.proxy, /__admin/recordings/*, snapshots |
Responses, Recording. Proxy targets go through the egress policy. |
| Chunked dribble, faults, delays | Supported | Supported (chunkedDribbleDelay, faults, fixed/uniform/lognormal delays) |
Converted on import. |
| Scenarios | Started initial state, global names |
Same, plus templated names, TTLs and atomic transitions across replicas | Scenarios. |
| HTTPS | Keystore with generated certificate | PEM files (FASTMOCK_TLS_*), optional mTLS |
Configuration. |
3. Change the test code¶
Java¶
WireMock's DSL talks to /__admin/mappings. Replace it with the FastMock Java client, or keep
your existing JSON mappings and send them through importWireMock.
// WireMock
WireMock.configureFor("localhost", 8080);
stubFor(post(urlPathEqualTo("/sms"))
.withRequestBody(matchingJsonPath("$.to", matching("380\\d{9}")))
.willReturn(aResponse().withStatus(202).withHeader("Content-Type", "application/json")
.withBody("{\"id\":\"{{randomValue type='UUID'}}\"}")
.withTransformers("response-template")));
// ...
verify(1, postRequestedFor(urlPathEqualTo("/sms")));
WireMock.reset();
// FastMock
FastMock fastmock = FastMock.connect("http://localhost:9090", System.getenv("FASTMOCK_TOKEN"));
String tag = "sms-test-" + UUID.randomUUID();
fastmock.createStub(Stub.post("/sms")
.bodyJsonPath("$.to", Match.matches("380\\d{9}"))
.respond(202)
.jsonBody(Map.of("id", "{{uuid}}"))
.tag(tag));
// ...
fastmock.verifyExactly(new ObjectMapper().readTree("""
{"method": "POST", "urlPath": "/sms"}"""), 1);
fastmock.deleteStubsByTag(tag);
Differences to keep in mind:
Stub.post(path)uses a path template (/orders/{id}works); query strings are matched with.query(...).- Tag every stub a test creates and delete the tag in
@AfterEach; this keeps parallel tests and shared environments independent, which a globalreset()would not. - Use
awaitRequests/awaitCallbacksfor anything asynchronous.
Raw HTTP¶
| WireMock call | FastMock call |
|---|---|
POST /__admin/mappings |
POST /__admin/stubs (FastMock stub JSON) or POST /__admin/import/wiremock (WireMock JSON) |
POST /__admin/mappings/import |
POST /__admin/import/wiremock |
DELETE /__admin/mappings |
DELETE /__admin/stubs?tag=... (by tag), or delete all as admin |
POST /__admin/mappings/find-by-metadata, remove-by-metadata |
POST /__admin/stubs/find-by-metadata, /stubs/remove-by-metadata |
GET /__admin/requests, POST /__admin/requests/count, /requests/find |
same paths |
GET /__admin/requests/unmatched, /near-misses/... |
GET /__admin/requests/unmatched, POST /__admin/requests/near-misses |
POST /__admin/scenarios/reset |
DELETE /__admin/scenarios |
PUT /__admin/scenarios/{name}/state |
PUT /__admin/scenarios/{name} |
POST /__admin/reset |
POST /__admin/reset (journal, callbacks, scenarios; stubs stay) |
POST /__admin/recordings/start, stop, snapshot |
same paths (Recording) |
4. Replace the WireMock container or server¶
With Testcontainers, the FastMock image runs as a GenericContainer:
static final String TOKEN = "fm_test_" + UUID.randomUUID().toString().replace("-", "");
@Container
static final GenericContainer<?> FASTMOCK = new GenericContainer<>("registry.example.com/platform/fastmock:0.1.0")
.withEnv("FASTMOCK_STORAGE", "memory")
.withEnv("FASTMOCK_ADMIN_TOKENS", "tests:admin:" + sha256Hex(TOKEN))
.withExposedPorts(8080, 9090)
.waitingFor(Wait.forHttp("/readyz").forPort(9090));
Details and the sha256Hex helper are in the Java client guide.
In shared environments, replace the WireMock Deployment with the Helm chart or a
MockServer resource, and the mapping ConfigMaps with MockApi resources.
Checklist¶
- [ ] Mappings imported with
dryRun, every warning reviewed. - [ ] Body files uploaded.
- [ ] Java extensions replaced by matchers, templates, scenarios or a plugin.
- [ ] Admin clients use the admin port and a token.
- [ ] Webhook targets reachable under the egress policy (no
localhost). - [ ] Tests tag their stubs and wait for asynchronous effects.
- [ ] Unmatched-request diagnostics switched to near misses.