DEV Community: Kuruba Ramesh

Integrating Specmatic Contract Testing into Spring PetClinic REST: What a "Simple" DELETE Test Taught Me About Test Architecture

Kuruba Ramesh — Mon, 13 Jul 2026 05:24:42 +0000

Introduction

Hello, I am Kuruba Ramesh. As part of my ongoing work with the Specmatic Full Stack AI Engineering Internship, I integrated contract testing into spring-petclinic-rest — the official Spring team's REST version of the classic Petclinic sample, built with an API-first approach and a complete OpenAPI 3.0 spec.

This post covers four things: the architecture of the setup, exactly what I did step by step, the real gaps I found in Specmatic itself along the way (not just bugs in the application), and how I ultimately designed the CI pipeline around the one gap that couldn't be closed outright.

Repository: https://github.com/KRameshr/spring-petclinic-rest

Architecture

The application: A Spring Boot REST API (Java 17, Spring Data JPA, H2 in-memory database) managing a veterinary clinic — owners, pets, vets, visits, and specialties. 18 API paths, 36 operations, full CRUD.

The contract: The project already ships with an OpenAPI 3.0 spec (src/main/resources/openapi.yml) — a machine-readable document describing every endpoint, every request/response shape, and every possible status code. For example, here's what it declares for fetching a single owner:

/owners/{ownerId}:
  get:
    operationId: getOwner
    parameters:
      - name: ownerId
        in: path
        schema:
          type: integer
          minimum: 1
          maximum: 10
    responses:
      200:
        description: Owner details found and returned.
      404:
        description: Owner not found.

This single block is enough for Specmatic to generate multiple test scenarios: a valid request expecting 200, an out-of-range ID expecting 404, and so on — all without anyone writing a line of test code.

How Specmatic fits in: Specmatic reads the OpenAPI spec and generates test scenarios from it automatically — no test code written by hand. It sends real HTTP requests to the application (already running, on localhost:9966) and checks whether every response matches what the spec promises. This is contract testing: verifying the app honours its own documented contract, not just that it "works."

The configuration (specmatic.yaml, Config V3) ties it all together:

version: 3
specmatic:
  settings:
    test:
      schemaResiliencyTests: all
      maxTestRequestCombinations: 1
systemUnderTest:
  service:
    $ref: "#/components/services/petclinicService"
components:
  services:
    petclinicService:
      definitions:
        - definition:
            specs:
              - spec:
                  path: openapi.yml
      data:
        examples:
          - directories:
              - src/main/resources/openapi_examples
  runOptions:
    petclinicServiceTest:
      openapi:
        baseUrl: http://localhost:9966/petclinic/api

This points Specmatic at the spec file, the base URL of the running app, a folder of external examples for controlling test data, and enables schema resiliency testing — generating negative/edge-case variations, not just the happy path.

The wiring: a JUnit 5 test class (ContractTest.java) implements Specmatic's SpecmaticContractTest interface. Running mvn test -Dtest=ContractTest reads this configuration, loads the spec, generates scenarios, and runs them.

Step by Step: What I Did

1. Verified the existing setup actually worked.
The project already had specmatic.yaml (Config V3), a JUnit 5 test class, and external examples. First step was simply running it and getting a real, reproducible baseline: 221 scenarios, some passing, some not.

2. Investigated every failure — not just made the build green.
POST /visits failed for every generated request. Tracing it: the request schema was missing a required field (petId) that the database enforced. This was a real spec-vs-database mismatch, not a testing artifact.

3. Fixed the missing field.
Added a request-only schema (VisitCreate), a MapStruct mapping method, and a controller update:

// VisitMapper.java
@Mapping(target = "id", ignore = true)
@Mapping(source = "petId", target = "pet.id")
Visit toVisit(VisitCreateDto visitCreateDto);

Re-ran the suite — this failure was gone for good.

4. Confirmed schema resiliency testing was active.
This is what surfaced most of what follows — negative/edge-case variations catch mismatches the happy path alone never would.

5. Added a dictionary for realistic test data.
Instead of random garbage strings for names and addresses, I wrote openapi_dictionary.yaml with real-looking values (names, cities, phone numbers).

6. Verified the dictionary — and found it wasn't actually being applied.
Specmatic's log confirmed it loaded the file:

Using dictionary file /usr/src/app/src/main/resources/openapi_dictionary.yaml

But checking an actual generated request showed the values were still random:

{
    "firstName": "v-Sc-YI",
    "lastName": "M.",
    "city": "XNPBY"
}

The dictionary keys (Owner, Vet) didn't match the real schema names (OwnerFields, VetFields) — a silent mismatch with no warning. Fixing the key names fixed it:

# before
Owner:
  firstName: [James, Mary, Robert, Patricia]

# after
OwnerFields:
  firstName: [James, Mary, Robert, Patricia]

Re-checked a generated request — real values now:

{
    "firstName": "Patricia",
    "lastName": "Johnson",
    "city": "Madison"
}

This unexpectedly exposed a second bug: POST /visits was returning 201 while the spec said 200. Fixed that too.

7. Found and fixed a caching feature the spec promised but the code never built.
The spec declared an ETag header for conditional GET requests. The app never sent one. Added one file:

@Configuration
public class ETagConfig {
    @Bean
    public Filter shallowEtagHeaderFilter() {
        return new ShallowEtagHeaderFilter();
    }
}

Verified real 304 Not Modified responses now work, with zero controller changes needed across any of the 18 endpoints.

8. Traced the remaining 6 DELETE failures to their root cause — five separate attempts.
Schema ID bounds, a named example, dedicated seed rows, coverage-focused 404 examples, and a dictionary override for the ID. Every attempt hit the same wall (detailed in the Gaps section below): SpecmaticContractTest runs all generated scenarios as a single dynamic JUnit 5 stream with no per-scenario reset hook, so once any scenario mutates real seed data — a DELETE that actually succeeds, for instance — every later scenario touching that row is exposed to the change:

API: DELETE /owners/(ownerId:number) -> 200
  >> RESPONSE.STATUS
      R0002: HTTP status mismatch
      Specification expected status 200 but response contained status 404

9. Closed the gap by designing around the constraint instead of fighting it.
Once the root cause was confirmed five separate ways, I stopped looking for a trick that would avoid it and instead rebuilt around it:

Made the seed data fully dense within its valid ID bounds — no gaps. A gap anywhere in a bounded range is exactly what schema-driven boundary and negative-mutation tests probe first, so it's a guaranteed eventual collision, not just a risk.
Split the resiliency-testing configuration into its own CI job. schemaResiliencyTests: all generates randomized boundary and negative-mutation tests across every operation, including DELETE, and is fundamentally incompatible with fixed, dedicated test records when there's no fixture isolation between scenarios — there's always some chance a random DELETE mutation targets the same row as a named example before that example gets its turn. So the pipeline now runs two jobs: contract-tests (named examples only, deterministic, required) and resilience-tests (full resiliency, continue-on-error: true, reports honestly without blocking the pipeline).

Result: contract-tests now passes 100%, reliably, confirmed across many repeated runs both locally and in CI.

10. Found a genuine Hibernate/JPA bug by refusing to accept "flaky" as an explanation.
While bringing the rest of the test suite (all unit and integration tests across all four ClinicService variants — H2/JDBC, HSQL/JDBC, JPA, Spring Data JPA) to a fully passing state, two of those variants had one test failing intermittently: deleting a PetType sometimes threw

TransientPropertyValueException: Persistent instance of 'Pet' references
an unsaved transient instance of 'PetType'

Tracing it instead of writing it off as test-order flakiness found this in the actual repository code:

public void delete(PetType petType) {
    this.em.remove(this.em.contains(petType) ? petType : this.em.merge(petType));
    // ... then, moments later:
    this.em.createQuery("DELETE FROM PetType WHERE id=" + petTypeId).executeUpdate();
}

An entity-level em.remove() and a bulk JPQL DELETE on the same row, in the same method. Bulk JPQL statements force an intermediate flush of the persistence context, and if any other Pet still held an in-memory reference to that PetType, Hibernate correctly refused to proceed rather than silently corrupting state. The fix: remove the redundant em.remove() call — the bulk delete already does the job. The exact same bug existed in both the JPA and Spring Data JPA repository implementations, likely copy-pasted at some point in the project's history.

11. Documented everything, including what didn't work and why.
The README covers every fix, the failed attempts, and the final CI design — with actual log excerpts, not just summaries.

Specmatic Gaps I Found

This is the part I think is most useful to share — not application bugs, but real limitations in Specmatic itself (open-source edition) that I ran into.

Gap 1: No hook to reset state between dynamically generated scenarios.
SpecmaticContractTest / SpecmaticJUnitSupport generates all scenarios as a single dynamic JUnit 5 test stream. Standard JUnit lifecycle hooks like @BeforeEach only apply to individual @Test methods and cannot attach to this stream. configureTest() runs once, for the entire suite — not per scenario. I confirmed this five separate ways — schema bounds, a named example, dedicated seed rows, coverage-focused 404 examples, and a dictionary override — all reproducing the identical cascade once a real ID could be targeted. Full fixture isolation between scenarios is an Enterprise-only feature; in the open-source tier, the correct response is to design your data and CI gates so the constraint can't cause a false failure — dense, gap-free ID ranges plus a separate, non-blocking job for resiliency testing — rather than keep searching for a way around it.

Gap 2: Dictionary key mismatches fail silently.
If a dictionary's top-level key doesn't exactly match the OpenAPI schema name, Specmatic doesn't apply those values — and doesn't warn you either. It simply falls back to random generation, while the log still reports the dictionary file as "loaded." This cost real debugging time, since "loaded successfully" reads like confirmation that it's working.

Gap 3: Dictionary values don't apply to path parameters.
I tried forcing a specific ID via the dictionary to make a DELETE scenario target a known-safe row. Confirmed this doesn't work — dictionary overrides only apply to schema body fields, not path parameters.

Gap 4: Automatic dictionary generation is Enterprise-only.
Specmatic can generate a dictionary automatically from a spec and existing examples — but only in the Enterprise edition. The open-source edition requires writing dictionaries by hand.

Gap 5: The --filter CLI option isn't available through the JUnit5/Maven integration.
Specmatic's CLI supports excluding specific operations (e.g. --filter="!(METHOD='DELETE')") from a run, which would have been a clean way to skip DELETE from resiliency testing specifically. That option isn't exposed through SpecmaticJUnitSupport. I tried passing it as a system property (-DFILTER=...); it had no effect on the JUnit run, and in one test actually correlated with more failures rather than acting as a no-op — worth knowing before assuming it will transfer over from CLI usage.

Gap 6: Writing a reliable 304/ETag example is hard when the underlying value is dynamic.
Even after fixing the app to genuinely support ETags, writing a Specmatic example for the 304 case is awkward — the ETag is a hash of the response body, so it changes whenever seed data is mutated elsewhere in the same test run. A hardcoded example expires the moment other tests touch the same data.

Key Learnings

"The log says it loaded" is not the same as "it's being used." Always verify against an actual generated request, not just the tool's own status message.

Fixing one bug can unmask another. The POST /visits status mismatch was invisible until the dictionary fix let requests actually reach the server.

Repeat an experiment before trusting the conclusion. Five independent attempts at the same DELETE problem, all failing identically, is what turned a guess into a documented, confident root cause.

"Intermittent" is a description of the symptom, not a diagnosis. Both the dictionary key mismatch and the later Hibernate flush-order bug looked like tooling flakiness right up until they were traced to a specific, deterministic line of code.

Some limitations are real and should be designed around, not endlessly worked around. Once a constraint is confirmed — not assumed — the better use of time is building around it honestly (a continue-on-error resiliency job alongside a fully deterministic required gate) rather than continuing to search for a trick that avoids it.

A bug duplicated across two files is a strong signal of copy-paste history. Finding the identical flush-order mistake in both JpaPetTypeRepositoryImpl and SpringDataPetTypeRepositoryImpl was a good reminder to check sibling implementations whenever a bug turns up in one.

Current Status

Specmatic ContractTest: 254 scenarios, 100% deterministic pass on the required contract-tests CI gate; a separate resilience-tests job runs full schema resiliency testing and reports honestly, non-blocking.
Full mvn verify: 491/491 tests passing — every REST controller test, all four ClinicService variants, plus config and validator tests — with JaCoCo coverage checks passing.
API contract coverage: 60%, up from 42% at the start of this work.
All three GitHub Actions workflows (Specmatic Contract Tests, Java CI, Docker Hub build) are green.

Full technical detail — including exact log excerpts for every experiment above, the complete list of bugs fixed, and the CI design decisions — is in the repository README.

Conclusion

The most valuable part of this project wasn't fixing the obvious bugs — it was the discipline of verifying tool behaviour instead of trusting it, confirming a root cause multiple times before accepting it, and then, once a real limitation was confirmed, designing around it honestly instead of continuing to chase a workaround. That discipline is what turned six unexplained DELETE failures into a fully deterministic, 100%-passing required test gate, and what turned an "intermittent" test into a genuine, fixed Hibernate bug duplicated across two files.

Repository: https://github.com/KRameshr/spring-petclinic-rest

Contract Testing a Spring Boot Banking API with Specmatic: A Complete Implementation Guide

Kuruba Ramesh — Fri, 12 Jun 2026 19:37:56 +0000

Introduction

I'm Kuruba Ramesh, a Full Stack Developer specializing in the MERN stack and Java Spring Boot. As part of the Specmatic Full Stack AI Engineering Internship Assessment, I completed a hands-on project focused on spec-first engineering and contract-driven API development.

The assessment asked me to:

Complete the Specademy course on Spec-First Engineering
Integrate Specmatic into a real-world Spring Boot application
Configure automated contract testing and CI
Document the implementation, the challenges, and what I learned

For this, I integrated Specmatic into my banking API project, ValueMeters, and automated provider contract testing with GitHub Actions.

Portfolio: krameshdev.vercel.app

This article walks through the full implementation — what contract testing actually is, how I wired Specmatic into a JWT-secured Spring Boot app, the schema resiliency failures that taught me the most, and how the CI pipeline is structured today.

What Is Contract Testing, and Why Does It Matter?

Before taking the Specademy course, I knew unit testing and integration testing well, but contract testing was new to me. One idea from the course stuck with me:

Contract testing is compiler safety for API calls.

In a monolithic application, the compiler catches a type mismatch the moment you try to build. You cannot ship code that calls a function with the wrong arguments — the build simply fails.

In a distributed system, services talk to each other over HTTP instead of function calls. If one service changes a field name, a data type, or a status code, there's no compiler to catch it. The mismatch only surfaces at runtime — often in production, and often at the worst possible time.

Specmatic closes that gap. It reads your OpenAPI specification and turns it into an executable contract. Using the Specmatic documentation as a reference, I set it up to automatically validate, on every test run:

Request and response schemas
HTTP status codes
Response headers and content types
Whether every documented endpoint is actually implemented

If the running application ever drifts from what the OpenAPI spec promises, the test fails immediately — the same way a compiler error stops a bad build before it ships.

Project Overview: ValueMeters Banking API

For this assessment, I used my banking API project, ValueMeters.

Technology Stack

Backend

Java 17
Spring Boot 2.7.18
Spring Security with JWT authentication
Spring Data JPA
MySQL
Specmatic 2.48.0

Frontend

React 18
Vite
Tailwind CSS

API Documentation

SpringDoc OpenAPI 3.0

API Surface

The application exposes 13 REST endpoints across five feature areas:

Endpoint	Method	Description
/auth/register	POST	Register a new user
/auth/login	POST	Log in and receive a JWT
/account/user/{userId}	GET	Get an account by user ID
/account/{accountNumber}	GET	Get an account by account number
/transaction/deposit/{accountId}	POST	Deposit money
/transaction/withdraw/{accountId}	POST	Withdraw money
/transaction/transfer/{fromAccountId}	POST	Transfer money between accounts
/transaction/history/{accountId}	GET	Get transaction history
/expense/add/{accountId}	POST	Add an expense
/expense/list/{accountId}	GET	List all expenses
/expense/summary/{accountId}	GET	Get an expense summary
/budget/set/{accountId}	POST	Set budget limits
/budget/get/{accountId}	GET	Get budget limits

Since the project already used SpringDoc OpenAPI, generating a spec was straightforward, which made ValueMeters a good candidate for Specmatic integration.

Setting Up Specmatic

Adding the Dependency

I added the Specmatic JUnit 5 support dependency (version 2.48.0) along with Spring Boot Actuator, which Specmatic uses to auto-discover every registered endpoint and enforce coverage governance.

Writing the OpenAPI Specification

I wrote an OpenAPI spec describing every endpoint's:

Request schema
Response schema
Path parameters
Status codes (200, 400, 404)
Error response shapes

This spec became the single source of truth that both the application and Specmatic are validated against.

Configuring `specmatic.yaml`

version: 3
systemUnderTest:
  service:
    definitions:
      - definition:
          source:
            filesystem:
              directory: .
          specs:
            - spec:
                path: openapi.json
                type: openapi
    runOptions:
      openapi:
        type: test
        baseUrl: "http://localhost:9000"
        actuatorUrl: "http://localhost:9000/actuator/mappings"
        filter: "PATH!='/api-docs,/swagger-ui'"
    data:
      examples:
        - directories:
            - examples

specmatic:
  settings:
    test:
      schemaResiliencyTests: all
  governance:
    successCriteria:
      maxMissedOperationsInSpec: 0
      minCoveragePercentage: 100
      enforce: true

Three settings do most of the work here:

actuatorUrl — Specmatic queries Spring Actuator to discover every registered endpoint, so nothing gets silently skipped from coverage.
examples directory — externalized, deterministic test data instead of relying purely on generated values.
schemaResiliencyTests: all together with governance — this is what actually generates the negative and boundary-mutation scenarios, and then enforces that 100% of operations are covered with zero missed operations. Resiliency isn't a separate testing phase bolted on afterward — it's the same Specmatic run, driven by this one setting.

The Biggest Challenge: JWT Authentication

ValueMeters uses JWT authentication — every endpoint expects a valid token in the Authorization header. When Specmatic fired its test requests, Spring Security rejected them before they ever reached a controller, well before Specmatic could evaluate the contract at all.

Solution: A Separate Test Security Profile

Rather than weakening production security, I used Spring profiles to swap in a test-only configuration.

@Profile("!test")
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    // Production JWT configuration — untouched
}

@Configuration
@Profile("test")
public class TestSecurityConfig {
    @Bean
    public SecurityFilterChain testFilterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth.anyRequest().permitAll());
        return http.build();
    }
}

This keeps production security completely untouched while giving Specmatic full access to exercise the API during the test profile only.

Writing the Contract Test

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
@ActiveProfiles("test")
@Sql(scripts = "/data.sql", executionPhase = ExecutionPhase.BEFORE_TEST_METHOD)
public class BankingContractTest extends SpecmaticJUnitSupport {
}

Two details here cost me real debugging time, and are worth calling out explicitly:

Use DEFINED_PORT, not RANDOM_PORT. With RANDOM_PORT, Spring Boot starts on a random port, but Specmatic connects to the port declared in the OpenAPI spec. Since those never match, every single test fails with "Connection refused" — and the error gives no hint that the port is the actual problem.

Reseed the database before every test method with @Sql. Provider tests need predictable state. Without a consistent reseed, resiliency's randomized requests can land on data that was mutated by a previous test, producing flaky, order-dependent failures.

The Most Valuable Debugging Session: Schema Resiliency Failures

The most useful thing I learned from this whole assessment came from debugging why Specmatic's schema resiliency run was failing tests that had nothing wrong with them.

The Problem

My first positive test passed. But the resiliency run then generated a login request with a random, schema-valid email like ahgtg@vismx.com instead of the seeded test@example.com. The API correctly rejected it with 400 Invalid credentials — but Specmatic's example expected 200, so it flagged the mismatch as a failure.

Root Cause

Schema resiliency doesn't just replay your examples — it actively mutates fields based on the constraints declared in the schema. My email field had "format": "email" in the OpenAPI schema, so Specmatic generated random-but-valid email addresses on each resiliency pass. My seeded H2 test database only had one real user, so anything else correctly failed login — which is exactly what a real client hitting the real API would experience, but not what the fixed example expected.

The Fix

Before:

"email": {
  "type": "string",
  "format": "email",
  "example": "test@example.com"
}

After:

"email": {
  "type": "string",
  "example": "test@example.com"
}

Removing "format": "email" stopped Specmatic from generating random email-shaped values during resiliency runs, so it fell back to the example value instead — which matched the seeded test data.

Importantly, this did not weaken validation anywhere that matters: Spring's @Email and @Valid annotations still enforce email format at runtime, in production. The schema change only affects how Specmatic generates test data, not how the application validates real requests.

The Register Endpoint Needed the Same Treatment

The register endpoint also needed its own externalized example file (examples/auth_register_success.json). Without one, Specmatic logged a warning that it was ignoring the inline spec example and falling back to fully random schema-based data — which hit the same problem as the email field.

Expanding to Full API Coverage

With the JWT and resiliency issues resolved, I expanded the OpenAPI spec to cover all 13 endpoints — account, transaction, expense, and budget — not just auth.

For each endpoint, I:

Tightened request schemas, removing loosely-typed optional fields that caused unpredictable resiliency mutations
Documented the real response codes (200, 400, 404) instead of only the happy path
Added externalized positive and negative example files under examples/
Fixed service-layer exceptions to map to the correct HTTP status — AccountNotFoundException → 404, InsufficientBalanceException → 400

Final result: 96/96 tests passing, 100% API coverage across all 13 endpoints.

GitHub Actions CI Integration

Once the tests were solid locally, I automated them with GitHub Actions so every push gets contract-tested automatically, with no manual step required.

How the Pipeline Is Structured

Contract tests and schema resiliency are not two separate test suites — resiliency is just schemaResiliencyTests: all inside the same Specmatic run described above. So the CI pipeline runs everything as a single job:

name: Specmatic CI
on:
  push:
  pull_request:
jobs:
  contract-tests:
    name: Contract Tests (with schema resiliency)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: "17"
          distribution: "temurin"
      - name: Make mvnw executable
        run: chmod +x mvnw
      - name: Run Contract Tests
        run: ./mvnw test -Dtest=BankingContractTest -Dspring.profiles.active=test
        continue-on-error: true
      - name: Upload Contract Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: contract-report
          path: build/reports/specmatic/

Every run of this job:

Boots the app in the test profile with TestSecurityConfig active
Runs the full contract test class, which exercises named examples and the schema resiliency mutations together
Enforces governance — zero missed operations, 100% coverage
Generates a Specmatic HTML report and uploads it as a GitHub Actions artifact, attached directly to that workflow run

I deliberately upload the report as a workflow artifact rather than publishing it to GitHub Pages. An artifact is tied to the exact commit and run that produced it, so the report you're looking at always matches the code you're looking at — there's no separate, manually-published copy that can quietly go stale while the code moves on.

Issues I Fixed to Get CI Green

mvnw not executable on Linux. Windows creates mvnw without the executable bit set. GitHub Actions runs on Ubuntu, so CI failed with exit code 126 until I added chmod +x mvnw as an explicit step.

Wrong Specmatic version. Version 0.28.0 isn't published on Maven Central — CI failed with a dependency resolution error. I checked Maven Central directly and pinned to 2.48.0.

RANDOM_PORT vs DEFINED_PORT. Same issue as locally, but CI made it impossible to ignore — Specmatic couldn't connect at all until I switched to DEFINED_PORT.

Two CI jobs doing the same work. Early on, I had contract-tests and resiliency-tests as two separate GitHub Actions jobs, both running the exact same command. Since resiliency is just a setting inside one Specmatic run, not a distinct test type, this duplicated the same execution and produced two nearly-identical reports for no benefit. Consolidating to the single job above cut CI time roughly in half and matches what's actually true about how Specmatic runs.

CI is green on every push: github.com/KRameshr/valuemeters-specmatic/actions

Key Learnings

1. Schema constraints drive resiliency test data, not just documentation. format: email tells Specmatic to generate random valid-looking emails during resiliency. Removing the format constraint pins generation back to your example. Schema constraints and runtime validation serve different purposes — don't confuse the two.

2. Every endpoint needs its own positive example. Without an externalized example, Specmatic falls back to fully random schema-based data, which may not match your seeded test state.

3. Exception types drive contract accuracy. RuntimeException → 500, AccountNotFoundException → 404, IllegalArgumentException → 400. Getting these right at the service layer is what makes the contract accurate, not just the code.

4. Governance turns coverage into a gate, not a metric. Enforcing minCoveragePercentage: 100 and maxMissedOperationsInSpec: 0 makes it structurally impossible to quietly ship an untested endpoint.

5. Provider testing needs deterministic state. Reseeding with @Sql before every test method removed an entire category of flaky, order-dependent failures.

6. Resiliency testing and contract testing are the same thing, not two pipelines. This was the biggest process lesson from this assessment. Schema resiliency is a setting on your contract test run, not a separate suite that needs its own job, its own report, or its own place in your CI. Treating it as separate — as I initially did with two CI jobs — just duplicates work and reporting for no additional signal.

What's Next

Consumer-driven contract testing
Deeper Specmatic provider examples for edge cases
Using Specmatic as a mock server for the React frontend during local development
Expanding negative-scenario coverage further

Conclusion

Before this project, I thought of OpenAPI mainly as documentation — something Swagger UI renders nicely, not something that actively enforces behavior. Working through this assessment changed that. An OpenAPI spec, run through Specmatic, becomes an executable contract that continuously checks the real application against what was promised, on every single push.

I integrated Specmatic 2.48.0 into a JWT-secured Spring Boot application, reached 96/96 tests passing with 100% API coverage across 13 endpoints, wired schema resiliency and governance into a single CI job, and learned — the hard way, through a failing test — that every schema constraint is an instruction to Specmatic's test generator, not just a documentation detail.

That last point is the one I keep coming back to: contract testing is compiler safety for API calls, and Specmatic is what makes that safety net actually executable instead of aspirational.

Resources

Specmatic: specmatic.io
Specmatic Documentation: docs.specmatic.io
Portfolio: krameshdev.vercel.app
GitHub Repository: github.com/KRameshr/valuemeters-specmatic
GitHub Actions (live CI): github.com/KRameshr/valuemeters-specmatic/actions

DEV Community: Kuruba Ramesh

Integrating Specmatic Contract Testing into Spring PetClinic REST: What a "Simple" DELETE Test Taught Me About Test Architecture

Introduction

Architecture

Step by Step: What I Did

Specmatic Gaps I Found

Key Learnings

Current Status

Conclusion

Contract Testing a Spring Boot Banking API with Specmatic: A Complete Implementation Guide

Introduction

What Is Contract Testing, and Why Does It Matter?

Project Overview: ValueMeters Banking API

Technology Stack

API Surface

Setting Up Specmatic

Adding the Dependency

Writing the OpenAPI Specification

Configuring specmatic.yaml

The Biggest Challenge: JWT Authentication

Solution: A Separate Test Security Profile

Writing the Contract Test

The Most Valuable Debugging Session: Schema Resiliency Failures

The Problem

Root Cause

The Fix

The Register Endpoint Needed the Same Treatment

Expanding to Full API Coverage

GitHub Actions CI Integration

How the Pipeline Is Structured

Issues I Fixed to Get CI Green

Key Learnings

What's Next

Conclusion

Resources

Configuring `specmatic.yaml`