Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,9 @@ Its source is preserved only on the historical `codex/rust-port` branch; see
**Development status:** a compatibility port under active construction, not a
complete drop-in replacement. The pinned reference is **WireMock 4.0.0-beta.40**. Upstream is a beta release;
BreakMock exposes its implemented messaging features by default, without a beta flag. See [COMPATIBILITY.md](docs/COMPATIBILITY.md)
for tested coverage and known gaps. Performance and compatibility are separate
for tested coverage and known gaps. We intentionally correct [five upstream bugs](docs/UPSTREAM_BUG_FIXES.md),
including matcher and JSON-template errors, so those cases differ from Java.
Performance and compatibility are separate
claims; neither is inferred from the implementation language.

## Why refactor WireMock to Go?
Expand Down
12 changes: 12 additions & 0 deletions docs/COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,18 @@ This repository does **not** claim compatibility with every possible mapping,
extension or transport configuration. Checked-in differential reports document a
bounded corpus; a passing fixture is not proof of an entire feature's equivalence.

## Intentional upstream bug corrections

BreakMock now corrects five confirmed upstream bugs by default, covering XPath
predicates, JSONPath empty-array absence, null JSON serialization, the trailing-slash
docs route and the scenario-state OpenAPI operation. See [the corrections and
migration notes](UPSTREAM_BUG_FIXES.md). These differences are not byte parity.
The affected differential cases are listed in `testdata/intended_differences.json`:
for each, the suite requires Java to still return its documented upstream result
**and** BreakMock to return its documented corrected result, exactly. Every other
case is still compared for equality, and a listed case fails if either side
changes, including if the two sides start to match.

## Implemented and exercised

- HTTP mappings, priorities, insertion ordering, scenarios, text/JSON/binary/file
Expand Down
58 changes: 58 additions & 0 deletions docs/UPSTREAM_BUG_FIXES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Corrections to upstream WireMock bugs

BreakMock corrects these confirmed bugs by default. These are intentional
behavior differences from the pinned Java WireMock 4.0.0-beta.40 reference,
not claims that every response remains byte-identical to Java.

| Upstream issue | Correction |
| --- | --- |
| [#3510](https://github.com/wiremock/wiremock/issues/3510) | A scalar `matchesXPath` predicate uses XPath boolean conversion: false, zero, NaN and empty strings do not match. Node-set matching and explicitly nested value matchers retain their behavior. |
| [#3159](https://github.com/wiremock/wiremock/issues/3159) | `matchesJsonPath` with `absent` does not match a present empty array selected by a definite path such as `$.foo`. Empty wildcard/filter selections and missing properties still count as absent. Near-miss distance agrees with the corrected match. |
| [#3282](https://github.com/wiremock/wiremock/issues/3282) | `toJson` emits the literal `null` for null/missing input, producing valid JSON when used as a value. Existing non-null serialization is unchanged. |
| [#3332](https://github.com/wiremock/wiremock/issues/3332) | GET and HEAD on `/__admin/docs/` work like `/__admin/docs`, including absolute links to the specification and Swagger UI. |
| [#3319](https://github.com/wiremock/wiremock/issues/3319) | The bundled OpenAPI specification documents `PUT /__admin/scenarios/{name}/state`, its optional body/reset behavior, and its 200/404/422 responses. The endpoint implementation is unchanged. |

## Compatibility and migration

Mappings that relied on false XPath expressions matching, or an empty array being
absent, will select differently. Templates that relied on null `toJson` input
rendering no characters now receive `null`. Use an explicit conditional when an
empty output is required. There is no legacy-bug compatibility switch.

Changing the served specification necessarily changes its response bytes. The
original upstream asset hash is retained in `internal/adminassets/PROVENANCE.json`,
with the modified specification hash recorded separately.

The live Java differential suites pin each affected case in
`testdata/intended_differences.json` (via `scripts/intended_differences.py`). A
listed case passes only when Java returns its documented upstream result and
BreakMock returns the documented corrected result, both exactly: `matched` versus
`unmatched` for #3159, an empty body versus `null` for #3282, and the original
versus modified OpenAPI document (SHA-256 recorded in
`internal/adminassets/PROVENANCE.json`) for #3319. Nothing else is filtered or
normalized, and the Java reference is not rewritten. If upstream fixes a bug, or
BreakMock loses a correction, the case fails. A build without these corrections
fails exactly these five cases.

Captured Java matcher fixture results are retained. Two cases now also record
an explicit `breakmockMatches: false` expectation for #3159, which Go unit tests
assert. The live Java comparison continues to compare actual server results.

Regression tests in `pkg/breakmock/upstream_bug_regression_test.go` cover positive
and negative predicates, empty-array versus empty-selection semantics, valid null
JSON, HTTP routing, documentation links and the OpenAPI operation. Run:

```sh
go test -race ./...
go vet ./...
python3 scripts/verify.py --jar /tmp/wiremock.jar --output-dir /tmp/compatibility
```

## Validation results

Go unit/race tests, vet, all 11 Toxiproxy executable integration checks and the
Docker build pass. After merging current `main` (2026-10-13), `scripts/verify.py`
passes all 20 suite runs against the pinned JAR, with the five intended
differences above verified on both sides. The earlier run before the registry,
which reported them as failures, is kept in
[the validation summary](../testdata/reports/upstream-bug-fixes/validation.json).
8 changes: 7 additions & 1 deletion internal/adminassets/PROVENANCE.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,5 +40,11 @@
"assets/swagger-ui/swagger-ui-dist/swagger-ui.js.map": "e94e33402dac546894ee2e2a13c76d9e0e2b1dc2e78d5c9fadd90bd2b3397159",
"doc-index.html": "2109bc58585f8b73aa37dc419340ba3282eb6b3a6ac31a32a85e94cc3aff70a7",
"swagger/wiremock-admin-api.json": "4306cf1dada9455ad6b41e1344552f0dd6980edb3cf2471395a14dd8fee64d97"
},
"localModifications": {
"swagger/wiremock-admin-api.json": {
"sha256": "e66006261d3dd75b25f33e9b2c92d7dced6020221492a6e151eecd35c7d74f0c",
"reason": "Document PUT /__admin/scenarios/{name}/state (WireMock issue #3319). Original upstream asset hash remains in files."
}
}
}
}
62 changes: 62 additions & 0 deletions internal/adminassets/swagger/wiremock-admin-api.json
Original file line number Diff line number Diff line change
Expand Up @@ -1228,6 +1228,68 @@
}
}
},
"/__admin/scenarios/{name}/state": {
"put": {
"operationId": "setScenarioState",
"summary": "Set or reset the state of a scenario",
"tags": [
"Scenarios"
],
"description": "Sets an existing scenario to a state referenced by its mappings. An empty request body resets it to Started.",
"parameters": [
{
"name": "name",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Scenario name"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"description": "A state referenced by this scenario’s mappings"
}
}
},
"example": {
"state": "Done"
}
}
}
},
"responses": {
"200": {
"description": "State changed or reset",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {}
}
}
},
"404": {
"description": "Scenario does not exist"
},
"422": {
"description": "Invalid JSON or unsupported/missing state"
}
}
}
},
"/__admin/scenarios/reset": {
"post": {
"operationId": "resetAllScenarios",
Expand Down
2 changes: 1 addition & 1 deletion pkg/breakmock/admin_assets.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ func serveAdminAsset(w http.ResponseWriter, r *http.Request) bool {
p := strings.TrimPrefix(r.URL.Path, "/__admin/")
name := ""
switch p {
case "docs":
case "docs", "docs/":
name = "doc-index.html"
case "docs/swagger":
name = "swagger/wiremock-admin-api.json"
Expand Down
33 changes: 30 additions & 3 deletions pkg/breakmock/matcher.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"encoding/json"
"fmt"
"io"
"math"
"math/big"
"mime"
"mime/multipart"
Expand Down Expand Up @@ -517,6 +518,11 @@ func matchJSONPath(expected any, actual string) bool {
return matchValue(nested, string(raw), true)
}
if len(array) == 0 {
// A definite path can select a present empty array. An indefinite
// path with zero results instead means no nodes were selected.
if _, absent := nested["absent"].(bool); absent && matcherJSONPathDefinite(expression) {
return false
}
return matchValue(nested, "", false)
}
for _, v := range array {
Expand Down Expand Up @@ -547,6 +553,17 @@ func matcherJSONValueString(v any) string {
return string(raw)
}

// XPath object syntax may contain only expression/namespace metadata, without
// a nested value matcher. It then has the same predicate semantics as a string.
func xpathHasValueMatcher(pattern map[string]any) bool {
for key := range pattern {
if key != "expression" && key != "xPathNamespaces" {
return true
}
}
return false
}

func matchXPath(expected any, p map[string]any, actual string) bool {
expression, ok := expected.(string)
nested := map[string]any(nil)
Expand Down Expand Up @@ -584,8 +601,18 @@ func matchXPath(expected any, p map[string]any, actual string) bool {
}
evaluation := compiled.Evaluate(xmlquery.CreateXPathNavigator(doc))
if _, ok := evaluation.(*xpath.NodeIterator); !ok {
if nested == nil {
return true
if !xpathHasValueMatcher(nested) {
// XPath 1.0 boolean conversion applies to scalar predicates too.
switch value := evaluation.(type) {
case bool:
return value
case float64:
return value != 0 && !math.IsNaN(value)
case string:
return value != ""
default:
return false
}
}
return matchValue(nested, fmt.Sprint(evaluation), true)
}
Expand All @@ -595,7 +622,7 @@ func matchXPath(expected any, p map[string]any, actual string) bool {
if node.Type == xmlquery.ElementNode || node.Type == xmlquery.DocumentNode {
rendered = strings.TrimPrefix(node.OutputXMLWithOptions(xmlquery.WithOutputSelf(), xmlquery.WithIndentation(" "), xmlquery.WithEmptyTagSupport()), "\n") + "\n"
}
if nested == nil || matchValue(nested, rendered, true) {
if !xpathHasValueMatcher(nested) || matchValue(nested, rendered, true) {
return true
}
}
Expand Down
20 changes: 14 additions & 6 deletions pkg/breakmock/matcher_compat_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,26 @@ func TestJavaMatcherFixtures(t *testing.T) {
t.Fatal(err)
}
var cases []struct {
Name string
Pattern map[string]any
Body string
Matches bool
Name string
Pattern map[string]any
Body string
Matches bool
BreakMockMatches *bool `json:"breakmockMatches"`
}
if err = json.Unmarshal(raw, &cases); err != nil {
t.Fatal(err)
}
for _, c := range cases {
t.Run(c.Name, func(t *testing.T) {
if got := MatchRequest(c.Pattern, Request{Method: "POST", URL: "/test", Body: []byte(c.Body)}); got != c.Matches {
t.Fatalf("got %v, Java reference %v", got, c.Matches)
want := c.Matches
// Keep the captured Java result, but assert corrected semantics for
// explicitly documented upstream bugs. Live differential checks still
// compare the original Java and Go bytes without exemptions.
if c.BreakMockMatches != nil {
want = *c.BreakMockMatches
}
if got := MatchRequest(c.Pattern, Request{Method: "POST", URL: "/test", Body: []byte(c.Body)}); got != want {
t.Fatalf("got %v, want %v (Java reference %v)", got, want, c.Matches)
}
})
}
Expand Down
5 changes: 4 additions & 1 deletion pkg/breakmock/matcher_distance_path.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ func jsonPathMatchDistance(expected any, actual string) float64 {
switch v := value.(type) {
case nil:
case []any:
if _, absent := nested["absent"].(bool); absent && len(v) == 0 && matcherJSONPathDefinite(expression) {
return ValueMatchDistance(nested, "[]", true)
}
if _, jsonEqual := nested["equalToJson"]; jsonEqual {
values = append(values, matcherJSONValueString(v))
} else {
Expand All @@ -57,7 +60,7 @@ func jsonPathMatchDistance(expected any, actual string) float64 {
}
func xpathMatchDistance(expected any, p map[string]any, actual string) float64 {
nested, ok := expected.(map[string]any)
if !ok {
if !ok || !xpathHasValueMatcher(nested) {
if matchXPath(expected, p, actual) {
return 0
}
Expand Down
2 changes: 1 addition & 1 deletion pkg/breakmock/template.go
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ func renderTemplateContext(source string, request Request, parameters map[string
})
add("toJson", func(o *raymond.Options) any {
if o.Param(0) == nil {
return ""
return "null"
}
return templatePrettyJSON(templateOmitNulls(o.Param(0)), 0)
})
Expand Down
Loading
Loading