Declarative Testing
Use @DataSet and @ExpectedDataSet annotations to define test data setup and verification.
DB TesterDatabase Testing Framework
Annotation-driven data preparation and state verification for JUnit, Spock, and Kotest
Skip to content
Convention over Configuration
The framework discovers datasets based on test class and method names.
Multiple Frameworks
Full support for JUnit Jupiter, Spock, and Kotest with Spring Boot integration.
Flexible Data Formats
CSV and TSV support with scenario filtering for sharing datasets across multiple tests.
Database Operations
Supports CLEAN_INSERT, INSERT, UPDATE, DELETE, TRUNCATE, and more with customizable table ordering.
Extensible Architecture
Service Provider Interface (SPI) for custom data loaders, comparators, and operation handlers.
Quick Start
Installation
kotlin
dependencies {
// Using BOM (recommended)
testImplementation(platform("io.github.seijikohara:db-tester-bom:VERSION"))
// JUnit
testImplementation("io.github.seijikohara:db-tester-junit")
// Or Spock
testImplementation("io.github.seijikohara:db-tester-spock")
// Or Kotest
testImplementation("io.github.seijikohara:db-tester-kotest")
}groovy
dependencies {
// Using BOM (recommended)
testImplementation platform('io.github.seijikohara:db-tester-bom:VERSION')
// JUnit
testImplementation 'io.github.seijikohara:db-tester-junit'
// Or Spock
testImplementation 'io.github.seijikohara:db-tester-spock'
// Or Kotest
testImplementation 'io.github.seijikohara:db-tester-kotest'
}xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.seijikohara</groupId>
<artifactId>db-tester-bom</artifactId>
<version>VERSION</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<!-- JUnit -->
<dependency>
<groupId>io.github.seijikohara</groupId>
<artifactId>db-tester-junit</artifactId>
<scope>test</scope>
</dependency>
<!-- Or Spock -->
<dependency>
<groupId>io.github.seijikohara</groupId>
<artifactId>db-tester-spock</artifactId>
<scope>test</scope>
</dependency>
<!-- Or Kotest -->
<dependency>
<groupId>io.github.seijikohara</groupId>
<artifactId>db-tester-kotest</artifactId>
<scope>test</scope>
</dependency>
</dependencies>Basic Usage
java
package com.example;
@ExtendWith(DatabaseTestExtension.class)
@DataSet // Loads test data from CSV
@ExpectedDataSet // Verifies database state
class UserRepositoryTest {
@Test
void shouldCreateUser() {
userRepository.create(new User("john", "john@example.com"));
}
@Test
void shouldUpdateUser() {
userRepository.update(1L, new User("john", "john.doe@example.com"));
}
}groovy
package com.example
@DatabaseTest
@DataSet // Loads test data from CSV
@ExpectedDataSet // Verifies database state
class UserRepositorySpec extends Specification {
def "should create user"() {
when:
userRepository.create(new User("john", "john@example.com"))
then:
noExceptionThrown()
}
def "should update user"() {
when:
userRepository.update(1L, new User("john", "john.doe@example.com"))
then:
noExceptionThrown()
}
}kotlin
package com.example
@DataSet // Loads test data from CSV
@ExpectedDataSet // Verifies database state
class UserRepositorySpec : AnnotationSpec() {
init {
extensions(DatabaseTestExtension(registryProvider = { registry }))
}
@Test
fun shouldCreateUser() {
userRepository.create(User("john", "john@example.com"))
}
@Test
fun shouldUpdateUser() {
userRepository.update(1L, User("john", "john.doe@example.com"))
}
}Directory Structure
text
src/test/resources/
└── com/example/UserRepositoryTest/
├── users.csv # DataSet data with [Scenario] column
└── expected/
└── users.csv # Expected state with [Scenario] columntext
src/test/resources/
└── com/example/UserRepositorySpec/
├── users.csv # DataSet data with [Scenario] column
└── expected/
└── users.csv # Expected state with [Scenario] columntext
src/test/resources/
└── com/example/UserRepositorySpec/
├── users.csv # DataSet data with [Scenario] column
└── expected/
└── users.csv # Expected state with [Scenario] columnValidation Output
DB Tester outputs detailed YAML-formatted error messages when expectation verification fails:
yaml
Assertion failed: 2 differences in USERS
summary:
status: FAILED
total_differences: 2
tables:
USERS:
differences:
- path: row_count
expected: 3
actual: 2
- path: "row[0].EMAIL"
expected: john@example.com
actual: john@test.com
column:
type: VARCHAR(255)
nullable: falseTIP
The output is valid YAML. Standard YAML libraries parse this output for CI/CD integration.
See Error Handling for more details.