Skip to content
Skills Library
Programming · Testing

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.

Licence
Apache-2.0
Last repository change
29.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

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

  1. Steps
  2. One database container for the whole suite
  3. Repository tests
  4. Round trips
  5. Transactions in tests
  6. Slices: @DataJpaTest, @DataJdbcTest, @JdbcTest
Original SKILL.md headings · 95 lines, 876 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.