ValueMeters Banking API — Specmatic Contract Testing

A full-stack online banking system with Specmatic contract testing integration.

• Java 17+
• MySQL 8.0
• Maven 3.8+

CREATE DATABASE banking_db;

# Default profile (JWT security enabled)
./mvnw spring-boot:run

# Test profile (security disabled for contract testing)
./mvnw spring-boot:run -Dspring-boot.run.profiles=test

Application URLs:

./mvnw test -Dtest=BankingContractTest

This project uses Specmatic to validate API contracts defined in OpenAPI specifications.

Features:

• OpenAPI-driven contract testing
• Automated provider verification
• Positive + negative resiliency test execution
• Externalized examples via examples/ directory
• GitHub Actions CI integration
• HTML coverage report generation
• Contract-first API validation
• Actuator-based endpoint discovery

Tests run: 96, Successes: 96, Failures: 0, WIP: 0, Errors: 0
100% API Coverage across all 13 endpoints

During provider testing, Specmatic's positive resiliency execution was generating random email values instead of using seeded test data, causing login and register tests to fail.

Root Cause: "format": "email" in the OpenAPI schema caused Specmatic to generate random valid emails during resiliency runs, which were not present in the seeded H2 test database.

Fix:

1. Removed "format": "email" from LoginRequest and RegisterRequest schemas
2. Added externalized example files in examples/ directory
3. Upgraded to Specmatic 2.48.0 with actuator-based coverage tracking
4. Added governance rules to enforce 100% coverage

examples/
├── auth_login_success.json
├── auth_login_400.json
├── auth_register_success.json
├── auth_register_400.json
├── account_user_success.json
├── account_user_404.json
├── account_by_number_success.json
├── account_by_number_404.json
├── transaction_deposit_success.json
├── transaction_deposit_400.json
├── transaction_deposit_404.json
├── transaction_withdraw_success.json
├── transaction_withdraw_400.json
├── transaction_withdraw_404.json
├── transaction_transfer_success.json
├── transaction_transfer_400.json
├── transaction_history_success.json  (auto-covered)
├── expense_add_success.json
├── expense_add_400.json
├── expense_add_404.json
├── expense_list_success.json
├── expense_summary_success.json
├── expense_summary_400.json
├── budget_set_success.json
├── budget_set_400.json
├── budget_get_success.json
└── budget_get_404.json

Contract tests, including schema resiliency scenarios, run automatically on every push via a single GitHub Actions job. Resiliency is not a separate test suite - it is the same Specmatic run with schemaResiliencyTests: all enabled in specmatic.yaml, so named examples and randomized negative/edge-case scenarios execute together in one pass.

The generated HTML report is uploaded as a GitHub Actions artifact on every run (the contract-report artifact attached to each workflow run), not published to GitHub Pages. This keeps the report tied to the exact commit that produced it, instead of a manually-published copy that can go stale.

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

Specmatic can be used as a mock server during frontend development.

java -jar specmatic.jar stub

This starts a mock server that returns responses directly from the OpenAPI contract without requiring the backend service.

• Contract-First Development with OpenAPI 3.0
• Specmatic 2.48.0 with Actuator Integration
• 13 Endpoints with Full Contract Coverage
• Positive and Negative Resiliency Test Coverage
• Externalized Examples for Predictable Test Data
• Governance Rules — 0 missed operations, 100% coverage enforced
• GitHub Actions Automation
• HTML Coverage Reporting
• Mock Server Support

https://dev.to/krameshr/how-i-integrated-specmatic-contract-testing-into-a-real-banking-api-valuemeters-cak