Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

12 KiB

Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_branches, related_projects, created, last_reviewed

title

source_type

url

archive_url

status

confidence

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 에서만 메모.

인용하는 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: (미작성)

12 KiB Raw Blame History