llm-wiki/raw/official-docs/dx-testcontainers-java-best-practices.md

---
title: Testcontainers Java — best practice와 reuse / Singleton 패턴
source_type: official-doc
url: https://java.testcontainers.org/
archive_url:
status: raw
confidence: medium
tags: [developer-experience, testcontainers, integration-test, spring-boot, ca-skeleton, official-doc]
related_branches: [feature-developer-experience-contract, feature-test-taxonomy-fixture-contract, feature-ci-quality-gates-contract]
related_projects: [ca-skeleton]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Testcontainers Java — best practice와 reuse / Singleton 패턴

> Layer: `raw/official-docs/` — Testcontainers for Java 공식 페이지 + reuse / Spring 통합 보조 페이지 verbatim 발췌.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-developer-experience-contract]] | bootstrap 5단계 중 "(2) `docker compose up -d` (local dependencies via Testcontainers config 또는 별도 compose file)" 의 도구 근거. Spring Boot 3.1+ `@ServiceConnection` 도입 이후 Testcontainers 가 ca-tmpl 의 default integration test backend 가 될 수 있는지 평가 |
| [[raw/branch-notes/feature-test-taxonomy-fixture-contract]] | integration test taxonomy 가 Testcontainers 를 default backend 로 가질 수 있음 |
| [[raw/branch-notes/feature-ci-quality-gates-contract]] | integration test (default profile) gate — reuse opt-in 의 CI 정책 (off) 결정 근거 |

## 컨텍스트 / 왜 저장했는지

`feature-developer-experience-contract` bootstrap 5단계 중 "(2) `docker compose up -d` (local dependencies via Testcontainers config 또는 별도 compose file)" 의 도구 근거. Spring Boot 3.1+ 의 `@ServiceConnection` 도입 이후 Testcontainers 가 ca-tmpl 의 default integration test backend 가 될 수 있는지 raw 로 확보.

## 출처 / Source

- 원본 URL:
  - Testcontainers for Java — https://java.testcontainers.org/
  - Testcontainers reuse — https://java.testcontainers.org/features/reuse/
  - Testcontainers Spring Boot 통합 — https://java.testcontainers.org/modules/spring/ (및 Spring Boot 3.1+ `@ServiceConnection`)
  - Spring Boot Testcontainers support — https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.testing.testcontainers
- 저자 / 조직: AtomicJar (Docker 산하), Testcontainers community, Spring team
- 발행일: 공식 문서 (지속 갱신)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

**Testcontainers for Java 메인 페이지 — 2026-05-27 fetch 로 확인된 인용**:

> [§Core Definition (java.testcontainers.org)] "*Testcontainers for Java* is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container."

> [§Use Cases] "Testcontainers make the following kinds of tests easier: Data access layer integration tests, Application integration tests, UI/Acceptance tests"

> [§Functionality] "use a containerized instance of a MySQL, PostgreSQL or Oracle database to test your data access layer code for complete compatibility, but without requiring complex setup on developers' machines"

> [§Key Benefit] "safe in the knowledge that your tests will always start with a known DB state"

**보조 인용 (별도 페이지 — 본 fetch 로는 verbatim 미확인, 원래 raw 작성 시점 수집본 보존)**:

> [Testcontainers reuse docs — needs-confirmation] "Container reuse is an opt-in feature, controlled by the `testcontainers.reuse.enable` property. When enabled, containers with the same configuration hash are reused across test runs, significantly reducing test startup time. … Reuse must not be enabled in CI." *(2026-05-27 fetch 에서 verbatim 미확인 — https://java.testcontainers.org/features/reuse/ 재fetch 필요. Reuse 가 opt-in 인 점은 사실로 알려져 있으나 정확한 property 명 / "must not be enabled in CI" 표현 검증 필요)*

> [Spring Boot reference docs — needs-confirmation] "Spring Boot's `@ServiceConnection` annotation, introduced in Spring Boot 3.1, automatically configures the connection details (JDBC URL, credentials, host, port) of a Testcontainers-managed service to the Spring `ApplicationContext`. This removes most boilerplate configuration." *(`@ServiceConnection` 도입 사실은 Spring Boot 3.1 release notes 로 확인되나, 본 인용의 정확한 verbatim 은 Spring Boot reference docs 재fetch 필요)*

> [Testcontainers Java docs — paraphrased, needs-confirmation] "The recommended pattern for sharing a container across multiple test classes is the singleton container pattern: declare the container as a `static` field and start it manually. JUnit's `@Testcontainers` lifecycle should not be combined with the singleton pattern." *(원래 raw 자체에 "요약" 으로 표시됨 — verbatim 아님. 정확한 공식 표현 재확인 필요)*

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| TC-CORE-C1 | Testcontainers for Java 는 JUnit test 를 지원하는 Java library 로서, 공통 DB / Selenium 브라우저 / Docker container 에서 실행 가능한 무엇이든 lightweight + throwaway instance 를 제공 | [§Core Definition (java.testcontainers.org)] "*Testcontainers for Java* is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container." | `official-vendor-doc` | JUnit + Docker 사용 가능한 환경 | "JUnit 외 다른 test framework (TestNG, Spock) 도 1급 지원" 은 본 인용 범위 밖 |
| TC-CORE-C2 | Testcontainers 가 쉽게 만드는 test 카테고리: data access layer integration tests / application integration tests / UI/Acceptance tests | [§Use Cases] "Testcontainers make the following kinds of tests easier: Data access layer integration tests, Application integration tests, UI/Acceptance tests" | `official-vendor-doc` | 위 3가지 test 카테고리 | unit test 의 mock 대체로 쓰는 것은 본 인용으로 권장되지 않음 (use case 목록에 없음) |
| TC-CORE-C3 | containerized DB instance (MySQL / PostgreSQL / Oracle) 를 사용해 dev machine 의 복잡한 설정 없이 data access layer code 의 완전한 호환성을 test 가능 | [§Functionality] "use a containerized instance of a MySQL, PostgreSQL or Oracle database to test your data access layer code for complete compatibility, but without requiring complex setup on developers' machines" | `official-vendor-doc` | MySQL / PostgreSQL / Oracle 사용 시 | 다른 DB (SQL Server, MongoDB 등) 의 지원 수준은 본 인용 범위 밖 (별도 module 페이지 참조) |
| TC-CORE-C4 | test 가 항상 알려진 DB state 로 시작한다는 보장 | [§Key Benefit] "safe in the knowledge that your tests will always start with a known DB state" | `official-vendor-doc` | container per-test or per-class lifecycle 사용 시 | "container reuse 가 활성화된 상태에서도 동일 보장" 은 본 인용으로 직접 증명 안 됨 — reuse 는 state 가 누적될 수 있음 |
| TC-REUSE-C1 | Container reuse 는 opt-in feature 로, `testcontainers.reuse.enable` property 로 제어. 활성화 시 동일 configuration hash 의 container 가 test run 간 재사용되어 startup time 을 크게 단축. CI 에서는 활성화 금지 | [Testcontainers reuse docs] "Container reuse is an opt-in feature, controlled by the `testcontainers.reuse.enable` property. When enabled, containers with the same configuration hash are reused across test runs, significantly reducing test startup time. … Reuse must not be enabled in CI." | `needs-confirmation` *(원 raw 수집본; 2026-05-27 fetch 에서 verbatim 미확인. 사실 자체는 알려진 동작이나 정확한 property 명과 "must not be enabled in CI" 표현 재검증 필요)* | reuse 활성화 결정 | 활성화 시 state 누적의 정확한 영향 (test isolation 깨짐 정도) 은 본 인용 범위 밖 |
| TC-SPRING-C1 | Spring Boot 3.1 의 `@ServiceConnection` annotation 은 Testcontainers-managed service 의 connection detail (JDBC URL / credentials / host / port) 을 Spring `ApplicationContext` 에 자동 구성. 대부분의 boilerplate 제거 | [Spring Boot reference docs] "Spring Boot's `@ServiceConnection` annotation, introduced in Spring Boot 3.1, automatically configures the connection details (JDBC URL, credentials, host, port) of a Testcontainers-managed service to the Spring `ApplicationContext`. This removes most boilerplate configuration." | `needs-confirmation` *(Spring Boot 3.1 release notes 로 도입 사실 확인. 본 인용의 정확한 verbatim 은 Spring Boot reference 재fetch 필요)* | Spring Boot 3.1+ 사용 시 | 지원되는 container module 범위 (모든 module vs 일부 module 만) 는 본 인용 범위 밖 |
| TC-SINGLETON-C1 | 여러 test class 간 container 공유의 권장 패턴은 singleton container pattern: container 를 `static` field 로 선언하고 수동 start. JUnit `@Testcontainers` lifecycle 과 결합 금지 | [Testcontainers Java docs — paraphrased] "The recommended pattern for sharing a container across multiple test classes is the singleton container pattern: declare the container as a `static` field and start it manually. JUnit's `@Testcontainers` lifecycle should not be combined with the singleton pattern." | `needs-confirmation` *(원 raw 에서 "요약" 표기됨 — verbatim 아님. 정확한 공식 표현 재확인 필요)* | 여러 test class 가 같은 container 를 공유해야 할 때 | 단일 container 의 state isolation 전략 (truncate vs drop/recreate vs DI 격리) 은 본 인용 범위 밖 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `TC-CORE-C1~C4`: Testcontainers 의 정의 + 권장 use case (integration test 3종) + DB compatibility 보장 + known DB state 보장
- **이 자료가 증명하지 않는 것 (verbatim 미확인)**:
  - reuse 의 정확한 property 명 / "CI 에서 금지" 의 공식 표현 (`TC-REUSE-C1` 은 `needs-confirmation`)
  - `@ServiceConnection` 의 정확한 reference doc 인용 (`TC-SPRING-C1` 은 `needs-confirmation`)
  - singleton container pattern 의 정확한 공식 표현 (`TC-SINGLETON-C1` 은 `needs-confirmation`)
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - reuse property 명 / CI 정책: https://java.testcontainers.org/features/reuse/ 재fetch
  - `@ServiceConnection` reference: Spring Boot reference docs 재fetch
  - singleton pattern: Testcontainers Java docs 의 정확한 표현 재fetch
  - Apple Silicon (arm64) 환경의 image emulation 비용 — 본 raw 인용 범위 밖, 별도 module 페이지 참조 필요

## 메모 / Notes (내 프로젝트 해석 — PRESERVED)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- ca-tmpl bootstrap 5단계의 (2) 를 Testcontainers 로 구현하면 *test* lifecycle 과 *bootstrap* lifecycle 이 서로 다르다는 점 주의:
  - bootstrap: 사람이 로컬에서 한 번 띄우는 dependency → `docker compose up -d` 가 더 적합.
  - integration test: JUnit 안에서 격리 → Testcontainers + `@ServiceConnection`.
- 즉 branch note 의 "Testcontainers 또는 local dependency 대체 기준" 은 두 경로를 *둘 다* 명시해야 함. 한쪽만 두면 test 와 bootstrap 중 하나가 누락.
- reuse 옵션은 CI 에서는 금지 (본 raw 의 `TC-REUSE-C1` 는 `needs-confirmation` — 원 표현 재검증 필요). 로컬 dev 속도 향상용. CI 에서는 매번 fresh container 를 띄워야 contract test 의 isolation 보장.
- 함정: Apple Silicon (arm64) 환경에서 일부 image 는 emulation 필요 → bootstrap 시간 증가. OS 매트릭스 "macOS Apple Silicon 우선" 과 충돌 가능, 본 raw 에서만 메모.

## Related / 관련

- 인용하는 branch:
  - [[raw/branch-notes/feature-developer-experience-contract]] — bootstrap 5단계 + Testcontainers/local dep 결정
  - [[raw/branch-notes/feature-test-taxonomy-fixture-contract]] — integration test taxonomy 가 Testcontainers 를 default backend 로 가질 수 있음
  - [[raw/branch-notes/feature-ci-quality-gates-contract]] — integration test (default profile) gate
- 적용 contract:
  - [[raw/project-notes/ca-skeleton-operational-contract]] (Developer Experience 그룹)
- 인용하는 wiki: (미작성)