llm-wiki/raw/official-docs/test-taxonomy-testcontainers-official.md

---
title: Testcontainers — 공식 introduction
source_type: official-doc
url: https://testcontainers.com/guides/introducing-testcontainers/
archive_url:
status: raw
confidence: high
related_branches: [feature-test-taxonomy-fixture-contract]
related_projects: [ca-skeleton]
tags: [testcontainers, integration-test, test-taxonomy, ca-skeleton, official-doc]
created: 2026-05-25
last_reviewed: 2026-05-27
---

# Testcontainers — 공식 introduction

> Layer: `raw/official-docs/` — Testcontainers 공식 introduction guide 발췌. `feature-test-taxonomy-fixture-contract` 의 "integration test 부터 Testcontainers 강제" 결정의 1차 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-test-taxonomy-fixture-contract]] | "integration test 부터 Testcontainers 강제, unit/contract/architecture 는 금지" 분기 정책의 공식 근거 (real services vs in-memory) |

특정 branch 없이 foundational 조사로 수집한 경우:

- [[raw/project-notes/ca-skeleton-operational-contract]] — Test Contract (§12) 의 integration level 도구 선택 baseline

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

ca-tmpl 결정 중 "Testcontainers 는 integration test 부터 강제. unit/contract/architecture test 는 Testcontainers 금지" 는 **테스트 단계 분리의 핵심 규칙** 이다. 공식 입장이 이 규칙과 정합한지, 그리고 in-memory DB(H2 등) 대신 real container 를 쓰는 이유의 원문이 필요했다.

## 출처 / Source

- 원본 URL: https://testcontainers.com/guides/introducing-testcontainers/
- 아카이브 URL: (미수집)
- 저자 / 조직: Testcontainers / AtomicJar (Docker)
- 발행일: 지속적으로 갱신
- 마지막 확인일: 2026-05-27

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

> [§What is Testcontainers?] "Testcontainers is a testing library that provides easy and lightweight APIs for bootstrapping integration tests with real services wrapped in Docker containers."

> [§Opening paragraph] "the bulk of the application code might still be in integrating with those external services"

> [§What is Testcontainers?] "you can write tests talking to the same type of services you use in production without mocks or in-memory services"

> [§What problems does Testcontainers solve?] "You can run your integration tests right from your IDE, just like you run unit tests."

> [§What problems does Testcontainers solve?] "In-memory services may not have all the features of your production service...you might be using advanced features of Postgres/Oracle databases in your application. But H2 might not support all those features"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| TC-OFFICIAL-C1 | Testcontainers 는 Docker container 로 감싼 real service 로 integration test 를 부트스트랩하는 가벼운 테스팅 라이브러리 | [§What is Testcontainers?] "Testcontainers is a testing library that provides easy and lightweight APIs for bootstrapping integration tests with real services wrapped in Docker containers." | `official-vendor-doc` | Testcontainers 의 자체 정의 | Testcontainers 가 unit test 에도 적합하다는 뜻은 아님 — "integration tests" 명시 |
| TC-OFFICIAL-C2 | 애플리케이션 코드의 상당 부분이 외부 서비스와의 통합에 있음 (테스트 필요성의 배경) | [§Opening paragraph] "the bulk of the application code might still be in integrating with those external services" | `official-vendor-doc` | integration test 의 필요성 정당화 | 모든 프로젝트에서 통합 코드가 다수라는 보편 사실 주장 아님 — Testcontainers 채택 정당화 맥락 |
| TC-OFFICIAL-C3 | mock / in-memory service 없이 production 과 동일한 type 의 서비스로 테스트 작성 가능 | [§What is Testcontainers?] "you can write tests talking to the same type of services you use in production without mocks or in-memory services" | `official-vendor-doc` | real-dep integration test 도구 선택 | "production 과 동일한 version" 까지 보장한다는 뜻은 아님 — "same type" |
| TC-OFFICIAL-C4 | IDE 에서 unit test 처럼 integration test 를 직접 실행 가능 | [§What problems does Testcontainers solve?] "You can run your integration tests right from your IDE, just like you run unit tests." | `official-vendor-doc` | 개발자 워크플로 (CI 없이 로컬 실행) | unit test 와 동일한 실행 속도라는 주장은 아님 — 실행 가능성만 |
| TC-OFFICIAL-C5 | in-memory service 는 production service 의 모든 feature 를 갖지 않을 수 있음 (예: Postgres/Oracle 고급 기능을 H2 가 미지원) | [§What problems does Testcontainers solve?] "In-memory services may not have all the features of your production service...you might be using advanced features of Postgres/Oracle databases in your application. But H2 might not support all those features" | `official-vendor-doc` | H2 등 in-memory DB 의 한계 인지 | "H2 가 항상 모든 케이스에 부적합" 이라는 일반화는 아님 — 일부 기능 미지원만 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `TC-OFFICIAL-C1`: Testcontainers 의 self-definition (real services, integration test 부트스트랩)
  - `TC-OFFICIAL-C3`: real-dep test 가 mock/in-memory 없이 가능하다는 공식 입장
  - `TC-OFFICIAL-C4`: IDE 에서 직접 실행 가능 (개발자 경험)
  - `TC-OFFICIAL-C5`: H2 같은 in-memory DB 가 production feature 모두를 보장 못 한다는 공식 입장
- **이 자료가 증명하지 않는 것**:
  - "5분 unit test budget" 같은 정량 기준 — 본 페이지는 시간 예산 명시 안 함
  - "unit/contract/architecture test 에서 Testcontainers 사용 금지" — 본 페이지는 integration 에 권장만, 다른 level 금지는 ca-tmpl 의 별도 결정
  - Testcontainers 가 모든 외부 서비스 (특정 IBM Mainframe 등) 를 지원한다는 보장
  - container start time 의 구체 비용
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl unit budget (5분) 을 Testcontainers 가 깨뜨리는지 — 실제 측정 필요 (container start cost)
  - CI 환경 (GitHub Actions 등) 에서 Docker-in-Docker 정책 — 본 자료는 IDE 만 언급
  - testcontainers-java 의 JUnit 5 통합 + Spring Boot 통합의 구체 설정 (별도 가이드 페이지 필요)

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

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

- 공식 입장 = "real services in Docker" (`TC-OFFICIAL-C1`, `TC-OFFICIAL-C3`). H2 같은 in-memory DB 는 SQL 방언 차이로 false-pass 를 만든다는 것이 핵심 논거 (`TC-OFFICIAL-C5` 가 직접 지지).
- ca-tmpl 의 "unit/contract/architecture test 에서 Testcontainers 금지" 는 **5분 budget** 보호 결정과 정합하지만, 이 budget 자체는 본 자료가 증명하지 않음 — 별도 결정.
- 따라서 5min budget 을 깨지 않으면서도 real-dep 신뢰도를 확보하는 분기 = "integration 부터" — 본 자료가 직접 부합하는 부분은 "real services for integration", "금지" 결정은 별도.

## Related / 관련

- 같은 주제 다른 official-doc / 자료:
  - [[raw/official-docs/test-taxonomy-practical-pyramid-fowler]] — narrow vs broad integration 정의
  - [[raw/official-docs/verification-approvaltests-snapshot-official]] — contract level (Testcontainers 미사용) 의 대안
  - [[raw/official-docs/verification-pact-cdc-official]]
  - [[raw/official-docs/verification-spring-cloud-contract-official]]
- 인용하는 branch:
  - [[raw/branch-notes/feature-test-taxonomy-fixture-contract]]
- canonical contract 섹션:
  - [[raw/project-notes/ca-skeleton-operational-contract]] (Test Contract §12)
- 대안 그룹: **Group G-G — Skeleton Governance** (test taxonomy)
- 본 source 의 위치: **ca-tmpl 채택안 baseline 근거** — Testcontainers 공식 "real services, no H2"
- 인용하는 wiki: (미작성)