spring-testing-persistence
/spring-testing-persistence
Test the persistence layer of Spring Boot apps - Spring Data repositories, derived and custom queries, JPA mappings, database constraints, schema migrations and transactions - with Testcontainers and @ServiceConnection, @DataJpaTest/@DataJdbcTest/@JdbcTest, @Sql and TestEntityManager. Use when adding or changing repositories, queries, entities or migrations, or when Spring tests need a database.
- Author
- Kehrlann ↗
- Repository
- spring-boot-testing-skills ↗
- Licence
- Apache-2.0
- Last repository change
- 29.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Test the persistence layer of Spring Boot apps - Spring Data repositories, derived and custom queries, JPA mappings, database constraints, schema migrations and transactions - with Testcontainers and @ServiceConnection, @DataJpaTest/@DataJdbcTest/@JdbcTest, @Sql and TestEntityManager. Use when adding or changing repositories, queries, entities or migrations, or when Spring tests need a database.
Original author description
Test the persistence layer of Spring Boot apps - Spring Data repositories, derived and custom queries, JPA mappings, database constraints, schema migrations and transactions - with Testcontainers and @ServiceConnection, @DataJpaTest/@DataJdbcTest/@JdbcTest, @Sql and TestEntityManager. Use when adding or changing repositories, queries, entities or migrations, or when Spring tests need a database.
How it works
- Steps
- One database container for the whole suite
- Repository tests
- Round trips
- Transactions in tests
- Slices: @DataJpaTest, @DataJdbcTest, @JdbcTest
SKILL.md preview
---
name: spring-testing-persistence
description: Test the persistence layer of Spring Boot apps - Spring Data repositories, derived and custom queries, JPA mappings, database constraints, schema migrations and transactions - with Testcontainers and @ServiceConnection, @DataJpaTest/@DataJdbcTest/@JdbcTest, @Sql and TestEntityManager. Use when adding or changing repositories, queries, entities or migrations, or when Spring tests need a database.
---
# Testing persistence
Test what Spring Data builds from *your* declarations: derived query method names, `@Query` JPQL or SQL, custom repository implementations, entity mappings (relationships, cascades, converters, embeddables), database constraints, and migrations. Plain `save` / `findById` is Spring Data's own code; flow tests exercise it.
## Steps
1. **Inventory** the repositories and entities you touched: queries, mappings, constraints, migrations.
2. **Run against the production engine** with a Testcontainers database shared by the whole suite (below).
3. **Write repository tests in the suite's shared `@SpringBootTest`**: autowire the repositories, reset data in `@BeforeEach`. Use a data slice only in a large, slow-starting app (load `spring-testing-strategy`).
4. **Per query**: data that must match, and look-alike data that must not (boundary dates, case differences, nulls, another user's rows). Assert ordering and paging when the query declares them.
5. **Per mapping**: save, then reload from the database (see **Round trips**) and assert every mapped field and association.
6. **Per constraint**: violate it and expect `DataIntegrityViolationException`.
Done when every derived or custom query has a matching and a non-matching case, every mapping is asserted after a reload from the database, every constraint has a violation test, and the suite's context starts against the production engine with its migrations applied.
## One database container for the whole suite
Dependencies (test scope): `org.springframework.boot:spring-boot-testcontainers` and the Testcontainers module for the engine, such as `org.testcontainers:testcontainers-postgresql` (Testcontainers 2).
```java
import org.testcontainers.postgresql.PostgreSQLContainer;
@TestConfiguration(proxyBeanMethods = false)
public class TestcontainersConfiguration {
@Bean
@ServiceConnection
PostgreSQLContainer postgres() {
return new PostgreSQLContainer("postgres:17-alpine");
}
}
```
- `@ServiceConnection` points the datasource at the container; no URL or credential properties needed. The container starts with the context and stops when the context closes.
- `@Import(TestcontainersConfiguration.class)` from the suite's shared meta-annotation, so every class shares one context and one container (load `spring-testing-fast`).
- Starting the context runs Flyway or Liquibase against the container, so `contextLoads()` proves the migrations apply to the real engine.
- **Tie the container's lifecycle to the context, as above.** A `static @Container` field under `@Testcontainers` is stopped by JUnit after its class, while the cached context still points at it: the next class that reuses that context fails with connection errors. Its `@DynamicPropertySource` method also gives each class its own cache key.
- To run the app locally against the same container, add a `main` in `src/test`: `SpringApplication.from(MyApplication::main).with(TestcontainersConfiguration.class).run(args)`.
## Repository tests
```java
@AppTest // the suite's shared meta-annotation, importing TestcontainersConfiguration
class CityRepositoryTests {
@Autowired CityRepository cityRepository;
@BeforeEach
void setUp() {
cityRepository.deleteAll();
}
@Test
void findsByNamePrefixIgnoringCase() {
cityRepository.saveAll(List.of(city("Paris"), city("Parma"), city("Lyon")));
var cities = cityRepository.findByNameStartingWithIgnoreCase("par");
assertThat(cities).extracting(City::getName).containsExactlyInAnyOrder("Paris", "Parma");
}
}
```
- **Reset order**: with foreign keys, delete children before parents, or `JdbcTestUtils.deleteFromTables(jdbcTemplate, "selection", "city")` in child-to-parent order.
- **SQL fixtures**: `@Sql("/fixtures/cities.sql")` on the class or a method runs before each test; `executionPhase = AFTER_TEST_METHOD` for cleanup scripts. `@Sql` doesn't change the cache key.
- Repository tests assert on repositories; behaviour tests elsewhere assert through HTTP and services.
## Round trips
JPA's persistence context hands back the object you saved, not what the database holds, so a test that saves and reads in one transaction proves nothing about the mapping.
- **Without a test transaction** (the shared `@SpringBootTest` default), each repository call commits on its own, and `findById` after `save` reads from the database. Lazy associations then throw `LazyInitializationException` outside a transaction, as they would in production: read them inside a `TransactionTemplate`, or through the fetch-join query the app uses.
- **Inside a test transaction** (`@DataJpaTest`, or a `@Transactional` test), flush and clear before reading: `TestEntityManager.persistFlushFind(entity)`, or `entityManager.flush(); entityManager.clear();`.
- Constraints fire when SQL runs. In a transaction, use `saveAndFlush(...)` so the violation surfaces inside the test.
## Transactions in tests
`@Transactional` on a test class or method rolls back after each test. Keep it to repository-level tests. In flow tests it changes what runs:
- With `MockMvcTester`, the controller runs on the test thread inside the test's transaction: lazy loading that fails in production succeeds, and commit-time failures never happen.
- With `RANDOM_PORT` or `@Async` code, other threads can't see the test's uncommitted data, and the rollback doesn't undo what they wrote.
For flow tests, reset data in `@BeforeEach` instead. To test a `@Transactional` service's rollback, keep the test non-transactional: make a collaborator throw (`doThrow` on a `@MockitoBean`, or a `@MockitoSpyBean`), call the service, then assert the repository is unchanged.
## Slices: `@DataJpaTest`, `@DataJdbcTest`, `@JdbcTest`
Only for a large, slow-starting app (load `spring-testing-strategy`). If the suite already has `@SpringBootTest` classes, autowire repositories there instead: you reuse the cached context and pay no second startup.
- `@DataJpaTest` (`org.springframework.boot.data.jpa.test.autoconfigure`, starter `spring-boot-starter-data-jpa-test`) loads entities, repositories, the datasource, migrations and a `TestEntityManager`. `@DataJdbcTest` does the same for Spring Data JDBC, `@JdbcTest` for `JdbcTemplate`.
- Every test is `@Transactional` and rolled back. Opt out with `@Transactional(propagation = Propagation.NOT_SUPPORTED)` on the class or method.
- `@AutoConfigureTestDatabase` (default `replace = NON_TEST`) swaps the datasource for an embedded H2, HSQLDB or Derby *unless* it already points at a test database: a `@ServiceConnection` container, a `@DynamicPropertySource` URL, or a Testcontainers JDBC URL. `@Import(TestcontainersConfiguration.class)` therefore keeps the real engine. Without one, the embedded database must be on the test classpath.
- An embedded database can't run engine-specific SQL: native queries, and migrations that use the engine's types or functions.
- `properties = …` and each slice annotation change the cache key, as on `@SpringBootTest`.
Versions
The database has no other skills named spring-testing-persistence.
Database snapshot: 13.11.2026 · package version 84f7ad00708e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100spring-data-jpa
Add JPA persistence to an existing Spring Boot 4 Maven project — entities, repositories, auditing, Flyway migrations, and Testcontainers integration tests. Use when asked to add a database, JPA entities or repositories, or Flyway migrations. Assumes a feature-sliced layout like… - 100spring-boot-data-access
Optimize JPA, Hibernate, and database interactions in Spring Boot. Use when implementing JPA entities, repositories, or database access in Spring Boot. - 100322-frameworks-spring-boot-testing-integration-tests
Use when you need to write or improve integration tests — including Testcontainers with @ServiceConnection, @DataJdbcTest persistence slices, TestRestTemplate or MockMvcTester for HTTP, data isolation, and container lifecycle management for Spring Boot 4.0.x. This should trigger… - 100spring-data-jpa
Use when generating or refactoring Spring Boot 4 JPA entities, repositories, queries, projections, persistence tests, entity relationships, embeddables, IDs, or Hibernate mappings. Covers Jakarta Persistence 3.2 imports, Hibernate 7 entity modeling, new-state detection, N+1… - 100spring-data-jpa
Spring Data JPA for database access in Spring Boot applications. Covers repositories, entities, relationships, queries, pagination, and auditing. Based on production patterns from castellino and gestionale-presenze projects. USE WHEN: user mentions "JPA", "repository", "entity",… - 100spring-data-jpa
Use when generating JPA entities, repositories, queries, or anything touching the persistence layer. Covers entity conventions, N+1 prevention, projections, and query patterns.