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 picked a second, well-known project for contract testing integration: 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.

Where my first project (a banking API) taught me how Specmatic's resiliency tests generate schema-valid data, this project taught me something more architectural: contract testing can expose limitations in your test infrastructure itself, not just your API.

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

Project Overview

Technology Stack

Java 17
Spring Boot
Spring Data JPA
H2 (in-memory database)
Specmatic 2.50.0 (JUnit 5 integration)

Spring PetClinic REST exposes a full CRUD API for owners, pets, vets, visits, and specialties, 18 paths, 36 operations. It already ships with an OpenAPI spec, external example files, and a specmatic.yaml (Config V3), so unlike a greenfield integration, my job was to get the existing setup fully working, find real gaps, and document them honestly.

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

schemaResiliencyTests: all is the setting that generates both the positive and negative schema variations, not just the hand-written examples — the same feature that ended up exposing the DELETE issue below.

Setting a Real Baseline

Running the existing contract test suite (SpecmaticContractTest via JUnit 5 and Maven):

221 scenarios generated, 214 passing, 7 failing.

Bug 1: A Missing Field That Broke Every Visit Creation

The first real failure was POST /visits. Every generated request failed with a DataIntegrityViolationException. The request schema (VisitFields) only declared date and description — but the Visit entity has a required foreign key to a pet (petId). Every contract-valid request Specmatic generated was, by definition, missing a field the database required.

Fix: introduced a request-only VisitCreate schema (date + description + petId) in the OpenAPI spec, wired through a new MapStruct mapping:

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

id is deliberately ignored (it's server-generated), and petId on the incoming DTO maps straight onto the JPA relationship (pet.id) MapStruct needs to build the entity. Once petId flowed through the request correctly, this failure disappeared for good — replaced by a far more interesting one.

Bug 2: DELETE Never Succeeds

Six DELETE operations were failing with 404 instead of the expected 200. Here's the actual output from one of them:

Testing scenario "Delete an owner by ID. Response: Owner details found and returned."
API: DELETE /owners/(ownerId:number) -> 200

  >> RESPONSE.STATUS

      R0002: HTTP status mismatch
      Documentation: https://docs.specmatic.io/rules#r0002
      Summary: The HTTP status code does not match the expected status code
      defined in the specification

      Specification expected status 200 but response contained status 404

The obvious diagnosis: their ID path parameters had no minimum/maximum bounds in the spec — unlike their sibling GET/PUT operations for the same resource — so Specmatic generated a fully random int32, which almost never matched a real seeded row.

The fix looked trivial: add the same bounds the GET/PUT operations already had. I tried it.

It made things worse.

With valid bounds, Specmatic now generated an ID that did exist in the database — and the DELETE call actually succeeded, permanently removing a real row (and its dependent pets/visits). That cascaded into 20+ unrelated failures later in the same test run, because other scenarios still expected that data to exist.

So I tried a second approach: a named example tying one specific ID to the DELETE scenario. Same cascade — the delete still went through for real.

Third attempt: dedicated "throwaway" seed rows that no other test depended on, specifically for DELETE to target. By the time the DELETE scenario ran, an earlier POST scenario in the same test run had already filled that "safe" slot with real data.

Three independent experiments, three identical failure modes.

The Actual Root Cause

None of this was a schema bug. ContractTest runs its dynamically generated scenarios against a live, already-running Spring Boot instance over plain HTTP, with no reset between scenarios. Any test that successfully mutates data can affect any other test that runs later in the same suite — and the open-source SpecmaticContractTest JUnit 5 interface has no documented hook to reset application/database state between individual generated scenarios.

I confirmed this wasn't fixable at the schema level. It required test-infrastructure changes (per-scenario database reset) that are out of scope for a contract-testing pass — this is a genuine, separate piece of work.

Verifying the Setup Was Actually Correct

Along the way, a peer review caught two real issues worth mentioning:

schemaResiliencyTests had drifted between local and committed config — my local file correctly had all, but the committed specmatic.yaml on GitHub still said none. That one config file had simply never been committed.
Six Java files with real exception-handling fixes (returning proper 4xx instead of 500 for malformed requests) had also been sitting uncommitted locally for a while — this was silently causing CI to report 125 failures instead of the expected 7, because CI only sees what's actually pushed.

Both were fixed and pushed, bringing CI back in line with local results.

Key Learnings

1. A "simple" schema fix can hide a cascading side effect.
Adding minimum/maximum bounds looked like the obvious, safe fix for random-ID failures. It was correct in isolation — but the moment a DELETE could succeed for real, it exposed the lack of test isolation. The fix wasn't wrong; the environment it ran in wasn't ready for it.

2. Repeat the experiment before you trust the result.
The DELETE-cascade problem wasn't obvious after one attempt — it took three independent approaches (schema bounds, named examples, dedicated seed rows) hitting the identical failure mode before I was confident it was architectural, not incidental.

3. Local ≠ committed ≠ CI.
The schemaResiliencyTests drift is a reminder that "it works on my machine" isn't the same as "it's actually in the repository." Regularly diffing local state against git status and CI output catches this kind of silent gap.

4. Contract testing can find bugs in the test suite, not just the API.
This was the most valuable lesson from this project. Specmatic didn't just validate the OpenAPI contract — running it honestly, without forcing a green build, surfaced a structural limitation in how the tests themselves are built.

Current Status

221 tests, 214 passing, 7 known and root-cause-documented failures — CI now consistently matches local results (it still reports failure because of those 7 documented cases, which is expected, not a regression). Full write-up, including the three-experiment DELETE investigation, in the repository README.

Conclusion

Where my first Specmatic project taught me that schema constraints are testing instructions, this one taught me that a contract test suite is only as reliable as the infrastructure it runs on. Fixing the app's contract violations was straightforward; discovering — and clearly documenting, rather than papering over — a genuine gap in test isolation was the harder and more useful part of the work.

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

Integrating Specmatic Contract Testing into a Spring Boot Banking API: My Experience

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

Introduction

Hello, I am Kuruba Ramesh, a Full Stack Developer specialising in the MERN Stack and Java Spring Boot. As part of the Specmatic Full Stack AI Engineering Internship Assessment, I completed a hands-on assignment focused on Spec-First Engineering and contract-driven API development.

The assessment required 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 my implementation, challenges, and learnings.

For this assignment, I integrated Specmatic into my Banking API project (ValueMeters) and automated provider contract testing using GitHub Actions.

Portfolio: https://krameshdev.vercel.app/

This article explains my implementation journey, the challenges I encountered, how I solved them, and the practical lessons I learned while working with Specmatic.

What is Specmatic?

Before taking the Specademy course, I was familiar with unit testing and integration testing, but contract testing was completely new to me.

One concept from the course immediately stood out:

Contract testing is compiler safety for API calls.

In a monolithic application, a compiler catches type mismatches before the application runs. In distributed systems and microservices, applications communicate over HTTP. If one service changes a request or response structure, another service may break without warning. These issues often appear only during runtime.

Specmatic solves this problem by turning API specifications into executable contracts.

Using an OpenAPI specification, Specmatic automatically validates:

Request structures
Response schemas
Status codes
Headers
Endpoint implementations

If the implementation does not match the contract, the test fails immediately.

Project Overview

For this assessment, I used my Banking API project called ValueMeters.

Technology Stack

Backend

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

Frontend

React 18
Vite
Tailwind CSS

Documentation

SpringDoc OpenAPI 3.0

The application exposes 13 REST APIs:

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

Since the project already used SpringDoc OpenAPI, it was an ideal candidate for Specmatic integration.

Setting Up Specmatic

Adding the Dependency

I added the Specmatic JUnit support dependency (version 2.48.0) and Spring Boot Actuator, which Specmatic uses to discover all registered endpoints and enforce coverage governance.

Creating the OpenAPI Specification

I created an OpenAPI specification describing:

Request schemas
Response schemas
Path parameters
Status codes (200, 400, 404)
Error responses

This specification became the single source of truth for contract validation.

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

Key additions:

actuatorUrl — Specmatic discovers all registered endpoints via Spring Actuator
examples directory — externalized test examples for deterministic data
governance — enforces 100% coverage and zero missed operations

The Biggest Challenge: JWT Authentication

My Banking API uses JWT authentication. When Specmatic generated requests, Spring Security rejected them before they reached the controllers.

Solution: Separate Test Security Configuration

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

@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();
    }
}

Creating 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 {
}

Important Lessons

Use DEFINED_PORT instead of RANDOM_PORT — With RANDOM_PORT, Spring Boot starts on a random port while Specmatic expects the port defined in the OpenAPI specification.

Use @Sql to reseed test data before each test method — this ensures deterministic state for all provider test scenarios.

The Most Interesting Debugging Challenge: Resiliency Test Failures

The most valuable learning from this assignment came from debugging Specmatic's positive resiliency test failures.

The Problem

My first positive provider test passed successfully. However, the second positive resiliency execution sent a randomly generated email such as ahgtg@vismx.com instead of test@example.com, causing the provider to correctly return 400 Invalid credentials instead of the expected 200.

Root Cause

Specmatic's positive resiliency tests don't just replay example values — they actively generate randomised but schema-valid data for each field. Since my email field had "format": "email" in the schema, Specmatic generated random but structurally valid emails. My database only contained the seeded test@example.com, so login correctly returned 400, but Specmatic expected 200.

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-format values during resiliency runs. The example value was then used instead, which matched the seeded test data.

Important: This did not weaken validation. Spring's @Email and @Valid annotations still enforce email format at runtime. The schema change only affects how Specmatic generates test data.

Register Endpoint Fix

The register endpoint also needed a dedicated externalized example file (examples/auth_register_success.json). Without it, Specmatic logged a warning that it was ignoring the inline example, and fell back to fully random schema-based data.

Expanding to Full API Coverage

After the initial fixes, I expanded the OpenAPI specification to cover all 13 endpoints — including account, transaction, expense, and budget APIs.

For each endpoint I:

Defined correct request schemas (removing optional fields that caused resiliency mutation failures)
Added appropriate response codes (200, 400, 404)
Created externalized positive and negative example files in examples/
Fixed service layer exceptions to return correct HTTP status codes (AccountNotFoundException → 404, InsufficientBalanceException → 400)

Final result: 96/96 tests passing, 100% API Coverage

GitHub Actions CI Integration

After completing the local integration, I automated contract testing using GitHub Actions.

The workflow:

Builds the Spring Boot application
Starts the application in the test profile
Executes all contract and resiliency tests
Enforces governance — 0 missed operations, 100% coverage
Generates Specmatic HTML reports
Publishes reports to GitHub Pages

Key Learnings

1. Schema Constraints Drive Resiliency Test Data

format: email in OpenAPI tells Specmatic to generate random valid-looking emails during resiliency tests. Removing the format constraint pins generation to the example value. Schema constraints and application-level validation serve different purposes.

2. Every Endpoint Needs Its Own Positive Example

Without an externalized example, Specmatic falls back to fully random schema-based data that may not match seeded test data.

3. Correct Exception Types Matter

RuntimeException → 500, AccountNotFoundException → 404, IllegalArgumentException → 400. Using the correct exception types is essential for contract test accuracy.

4. Governance Enforces Quality Gates

Specmatic's governance configuration enforces 100% coverage and zero missed operations, making it impossible to accidentally leave endpoints untested.

5. Provider Testing Requires Deterministic Test Data

Provider tests are highly dependent on predictable application state. @Sql reseeding before each test method is essential.

Future Improvements

Consumer-driven contract testing
Advanced Specmatic provider examples
Mock server generation for frontend development
Expanded error scenario coverage

Conclusion

This assignment gave me practical experience with Spec-First Engineering and contract-driven API development.

Before working with Specmatic, I viewed OpenAPI primarily as documentation. Through this project, I learned how an OpenAPI specification can become an executable contract that continuously validates API behaviour throughout development and CI/CD.

I successfully integrated Specmatic 2.48.0 into a Spring Boot application, achieved 96/96 tests passing with 100% API coverage across 13 endpoints, and implemented governance rules that enforce quality gates on every push.

The most valuable lesson was understanding how Specmatic's resiliency tests work — they actively mutate data based on schema constraints, not just examples. This insight transformed how I think about OpenAPI specifications: every constraint is a testing instruction, not just documentation.

Final Resources

Portfolio: https://krameshdev.vercel.app/

GitHub Repository: https://github.com/KRameshr/valuemeters-specmatic

GitHub Actions: https://github.com/KRameshr/valuemeters-specmatic/actions