Debugging Mocks & Generating Reports

Integration tests fail. It happens. The frustration usually comes from asking: "Why did WireMock reject this request? It looks exactly the same!"

StableMock provides two powerful tools to solve this: Diagnostic Logging (for immediate fixes) and Recording Reports (for documentation).

Tool 1: Detailed Matching Diagnostics

If your test is failing with a 404 Not Found from the mock server, it means the request didn't match any recorded stub. You can enable verbose matching logic to see exactly why.

Enabling showMatches

Add the system property stablemock.showMatches=true to your test run.

./gradlew test -Dstablemock.showMatches=true

What You See

StableMock will print a detailed diff to the console, showing the closest match and the specific field that failed.

Closest Match:
URL: /api/users/1 (MATCHED)
Method: POST (MATCHED)
Body Path '$.timestamp': 
  Expected: "2023-01-01T10:00:00"
  Actual:   "2023-05-20T14:30.00" <-- MISMATCH!

This immediately tells you that you need to ignore the timestamp field.

Tool 2: Recording Reports

Sometimes you want to see the "big picture": What APIs did my test actually call?

When you run tests in RECORD mode, StableMock automatically generates a report file.

Report Location

After running your tests, look for: src/test/resources/stablemock/recording-report.html

What's Inside?

• Summary: Total requests recorded, total duration.
• Interaction Log: Full request/response bodies for every mocked call.
• Dynamic Field Hints: Highlighted fields that changed during recording.

Verifying Report Generation

You generally don't write assertions against the report itself, but you can verify it exists if you are building tooling around it.

@Test
void testReportExists() {
    File report = new File("src/test/resources/stablemock/recording-report.json");
    
    // In RECORD mode, this file is created/updated
    if (isRecordMode()) {
       assertTrue(report.exists());
    }
}

Conclusion

Between showMatches for fixing broken tests and recording-report for understanding behavior, StableMock gives you full visibility into the black box of your mocks.