Break the Chains of Database Dependencies: Leveraging Specmatic for JDBC Stubbing


To test our applications effectively on our local machines and in lower environments such as CI pipelines, we often need to isolate them from their database dependencies to make sure that the test environment is simple to set up and our tests themselves are quick to run. A few popular options that come to mind to achieve the same include in-memory databases and containerised databases. However, there are limitations to each of these approaches.

  1. In-memory DBs – They are database simulators and usually cannot handle syntax and data types that may be proprietary / vendor specific to your database. Legacy applications with stored procedures may be even harder to deal with.
  2. Containerised DBs – They are real databases and thereby also involve significant effort initially to achieve parity with your production database in terms of schema and data setup (Especially in legacy applications which lack automated DB deployment mechanisms).

To overcome these limitations we need a “Database Stub”.


Specmatic JDBC Stub is a completely wire-compatible setup that has none of the above limitations. It is able to seamlessly stub a JDBC datasource because of which your application thinks it is talking to a real database. This helps in creating a realistic test environment that can be quickly spun up in-memory.

Key features

  1. Eliminate Database Dependency: JDBC stubs allow us to isolate APIs from their database dependencies, enabling us to test without the need for a complex DB setup. By switching out the data source with a Specmatic JDBC stub, the API can communicate with the stub instead of the actual database.
  2. Define / Record and Replay Expectations: With Specmatic JDBC stub, we can set expectations for queries and their responses. These expectations can be written by hand or recorded based on actual interactions between the API and a real database. This allows you to verify that your application is only interacting with the database as intended by you.
  3. Stub vendor specific SQL syntax – Since Specmatic JDBC stub operates at the level of abstraction of a DataSource, you can effectively stub all types of interactions including stored procedure calls.
  4. Blazing Fast In-memory Setup – Super charge your tests (component, contract and API tests and more) with Specmatic’s fast in-memory JDBC stubbing capability that speeds up your overall test execution time thereby making for a great Developer Experience.

By leveraging Specmatic JDBC stubs, we can effectively test APIs, reduce dependencies, and ensure the reliability and integrity of our applications.

Check out the sample code

Sample project: Manual configuration
Sample project: Spring auto-configuration

Download Specmatic:

Available in the Pro plan or higher

Jdbc stubing production mode jdbc stubing test mode Redis Stubbing with Specmatic Contract Testing.

Benefits of Specmatic JDBC Stub: Replacing Real Data Sources & Enhancing the Testing Process

At the core of the testing process lies the ability to isolate the application from its database dependency. Specmatic JDBC stub achieves this by replacing the real data source with a Specmatic data source. By doing so, the API under test communicates with the Specmatic JDBC stub instead of the actual database. This allows developers to run different types of tests without the hassle of depending on a complex database setup. The Specmatic JDBC stub acts as a drop in replacement for  the database in your test environments, ensuring smooth communication and accurate test results.

Setting Expectations with Specmatic JDBC Stub for Contract-Based API Testing

To effectively use Specmatic JDBC stub, the first step is to set expectations with the stub regarding the queries that it can expect and the corresponding data it needs to respond with. These expectations can be manually written or recorded based on actual interactions between the API and a real database. Once the expectations are set, the real database is no longer required in the testing setup.

Code walkthrough: Specmatic JDBC Stub for Testing

Let’s delve into a concrete example to illustrate the power of the Specmatic JDBC stub. Consider an application that provides a wrapper for managing product entities. In its production configuration, it relies on a real database for data storage.

A screen shot showcasing Specmatic's JDBC stubbing capabilities to liberate from database dependencies.

However, for testing purposes, we want to isolate the application from the actual database. By disabling the data source auto-configuration, the application loses its ability to communicate with the real database.

A code editor with JDBC Stubbing capabilities.
Using Specmatic for JDBC Stubbing to break database dependencies in a web browser screenshot.

Instead, we configure the Specmatic JDBC stub as the data source for testing. This is achieved by adding the Specmatic JDBC dependency and setting up a bean for the data source, specifying the port and directory where the expectations are stored.

Leveraging Specmatic for JDBC Stubbing in a code editor screen of Adobe Acrobat.

Seamless Contract Testing with the Specmatic JDBC Stub and OpenAPI Specification

With the Specmatic JDBC stub in place, we can now run contract tests based on the OpenAPI specification of the API. These tests make HTTP requests to the application, which in turn communicates with the Specmatic data source.

The data source responds with the predefined data that was set up as part of the expectations.

Leveraging Specmatic for JDBC Stubbing in a code editor screenshot.

When Specmatic JDBC stub receives queries that it is not expecting, it throws errors to indicate the same thereby giving us feedback when our application code is making any additional calls to the database.

A screenshot of Specmatic, a Java script editor for breaking database dependencies by leveraging JDBC stubbing.

From the application’s perspective, it appears as if it is interacting with the real database. The application processes the data and returns it to the Specmatic contract test, which then validates if the response conforms to the schema described in the OpenAPI specification.

This seamless integration allows developers to confidently test their applications while eliminating the need for an actual database.

The Benefits of Utilising Specmatic JDBC Stub for Testing Applications with Database Dependencies

In conclusion, Specmatic JDBC stub provides a powerful solution for testing applications with database dependencies. By replacing the real data source with the Specmatic data source, developers can easily isolate their applications from complex database setups in their test environments and perform comprehensive tests including API, contract tests and more. For example, with Specmatic’s ability to generate contracts from OpenAPI specifications (API specifications as contract tests), developers can verify the correctness of their APIs without the need for an actual database instance.

By leveraging Specmatic JDBC stub, developers can streamline the testing process, increase test coverage, and ensure the reliability and stability of their applications.

Sample project: Manual configuration
Sample project: Spring auto-configuration

Download Specmatic:

Contact us to join the private beta.