llm-wiki/raw/official-docs/junit5-conditional-env-variable-user-guide.md

---
title: "JUnit 5 User Guide — Conditional Test Execution: Environment Variable Conditions & Custom Conditions"
source_type: official-doc
url: https://docs.junit.org/current/user-guide/
archive_url:
vendor: junit.org / JUnit Team
related_branches: [feature-contract-verification-test-suite]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, testing, junit5, conditional-test-execution]
created: 2026-06-15
---

# JUnit 5 User Guide — Conditional Test Execution: Environment Variable Conditions & Custom Conditions

> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-contract-verification-test-suite]] | D3: optional adapter contract test 는 adapter enabled env matrix 에서만 실행 (skipped, not failed) — JUnit 5 `@EnabledIfEnvironmentVariable` / `@DisabledIfEnvironmentVariable` 의 named+matches 속성, undefined 시 DISABLED(SKIPPED) 동작, 5.6+ repeatable 특성이 그 공식 근거 |

## 출처 / Source

- 원본 URL: https://docs.junit.org/current/user-guide/ (301 redirect → https://docs.junit.org/current/user-guide/ resolved)
- 검증 버전: JUnit 5 / JUnit Jupiter 5.11.0 (user-guide 및 Javadoc 기준)
- 상세 Javadoc URL (직접 인용):
  - `@EnabledIfEnvironmentVariable`: https://docs.junit.org/5.11.0/api/org.junit.jupiter.api/org/junit/jupiter/api/condition/EnabledIfEnvironmentVariable.html
  - `@DisabledIfEnvironmentVariable`: https://docs.junit.org/5.11.0/api/org.junit.jupiter.api/org/junit/jupiter/api/condition/DisabledIfEnvironmentVariable.html
  - `@EnabledIf`: https://docs.junit.org/5.11.0/api/org.junit.jupiter.api/org/junit/jupiter/api/condition/EnabledIf.html
- 저자 / 조직: JUnit Team
- 발행일: ongoing (JUnit 5.11.0 release)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

`feature-contract-verification-test-suite` D3 결정("optional adapter contract test 는 adapter enabled env matrix 에서만 실행")의 공식 JUnit 5 근거로 보관. `@EnabledIfEnvironmentVariable` 의 undefined-variable → DISABLED(SKIPPED) 보장, repeatable 속성(5.6+), `named` + `matches` regex 속성이 ca-skeleton 의 adapter-env-matrix 조건부 테스트 게이트 구현을 직접 정당화한다.

## 핵심 인용 / Key quotes (verbatim, 3~5문장)

> [§ User Guide §2.9.5 — Environment Variable Conditions] "A container or test may be enabled or disabled based on the value of the `named` environment variable from the underlying operating system via the `@EnabledIfEnvironmentVariable` and `@DisabledIfEnvironmentVariable` annotations. The value supplied via the `matches` attribute will be interpreted as a regular expression."

> [§ Javadoc — EnabledIfEnvironmentVariable] "@EnabledIfEnvironmentVariable is used to signal that the annotated test class or test method is only enabled if the value of the specified environment variable matches the specified regular expression."

> [§ Javadoc — EnabledIfEnvironmentVariable — undefined behavior] "If the specified environment variable is undefined, the annotated class or method will be disabled."

> [§ User Guide §2.9.5 — Repeatability] "As of JUnit Jupiter 5.6, `@EnabledIfEnvironmentVariable` and `@DisabledIfEnvironmentVariable` are repeatable annotations."

> [§ User Guide §2.9.6 — Custom Conditions] "As an alternative to implementing an `ExecutionCondition`, a container or test may be enabled or disabled based on a condition method configured via the `@EnabledIf` and `@DisabledIf` annotations."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| JUNIT5-ENV-C1 | `@EnabledIfEnvironmentVariable` 는 지정된 환경 변수 값이 `matches` regex 와 일치할 때만 테스트를 enabled 상태로 실행한다 | [§ Javadoc] "@EnabledIfEnvironmentVariable is used to signal that the annotated test class or test method is only enabled if the value of the specified environment variable matches the specified regular expression." | `official-vendor-doc` | JUnit Jupiter 5.1+ / JUnit 5 Jupiter 테스트 클래스 및 메서드 | matches 조건이 일치했을 때 테스트가 실제로 통과(pass)함을 보장하지 않는다 — enabled 여부만 보장 |
| JUNIT5-ENV-C2 | 지정된 환경 변수가 정의되지 않은(undefined) 경우, `@EnabledIfEnvironmentVariable` 이 붙은 컨테이너/메서드는 disabled(skipped)된다 | [§ Javadoc — EnabledIfEnvironmentVariable] "If the specified environment variable is undefined, the annotated class or method will be disabled." | `official-vendor-doc` | JUnit Jupiter 5.1+ | 환경 변수가 존재하지만 빈 문자열("")인 경우의 동작은 별도로 명시되지 않음. CI에서 변수 미설정 시에도 이 계약이 적용됨을 별도 검증 권장 |
| JUNIT5-ENV-C3 | `@EnabledIfEnvironmentVariable` 과 `@DisabledIfEnvironmentVariable` 은 5.6부터 repeatable annotations 이므로 같은 요소에 여러 번 선언할 수 있다 | [§ User Guide §2.9.5] "As of JUnit Jupiter 5.6, `@EnabledIfEnvironmentVariable` and `@DisabledIfEnvironmentVariable` are repeatable annotations." | `official-vendor-doc` | JUnit Jupiter 5.6+ | 복수 조건의 논리 결합 방식(AND vs OR)은 user guide 본문에서 별도 명시가 없으므로 Javadoc 또는 실험으로 확인 필요 |
| JUNIT5-ENV-C4 | `@DisabledIfEnvironmentVariable` 은 환경 변수가 undefined 인 경우에는 아무 효과가 없으며(테스트 enabled 유지), 변수가 정의되고 matches regex 일치 시에만 disabled 된다 | [§ Javadoc — DisabledIfEnvironmentVariable] "If the specified environment variable is undefined, the presence of this annotation will have no effect on whether or not the class or method is disabled." | `official-vendor-doc` | JUnit Jupiter 5.1+ | `@EnabledIfEnvironmentVariable` 과 조합 시의 우선순위 규칙은 별도 확인 필요 |
| JUNIT5-ENV-C5 | `@EnabledIf` / `@DisabledIf` 는 조건 메서드(boolean return) 를 참조하는 커스텀 조건 어노테이션이며, 5.7부터 도입되었고 repeatable 이 아니다 | [§ User Guide §2.9.6] "As an alternative to implementing an `ExecutionCondition`, a container or test may be enabled or disabled based on a condition method configured via the `@EnabledIf` and `@DisabledIf` annotations." + [§ Javadoc — @EnabledIf since: 5.7, not repeatable] | `official-vendor-doc` | JUnit Jupiter 5.7+ | 환경 변수 기반 조건이 아닌 임의 Java 표현식(Spring property 등)에 적용하는 메커니즘. `@EnabledIfEnvironmentVariable` 보다 나중에 도입되었으므로 환경 변수만 필요한 경우 `@EnabledIfEnvironmentVariable` 우선 권장 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `JUNIT5-ENV-C2`: 환경 변수가 undefined 이면 `@EnabledIfEnvironmentVariable` 붙은 테스트는 DISABLED(JUnit 리포트 상 SKIPPED)된다 — 절대 FAILED 가 아님. ca-skeleton D3 "optional adapter contract test 는 adapter enabled env matrix 에서만 실행 (skipped, not failed)" 의 핵심 공식 근거.
  - `JUNIT5-ENV-C1`: `named` + `matches` 조합으로 adapter-enabled 환경 변수의 이름과 기대값 패턴을 정확히 지정할 수 있음.
  - `JUNIT5-ENV-C3`: 복수 환경 변수 조건을 같은 테스트에 반복 선언 가능 (5.6+) — adapter matrix 가 복수 env 를 게이트로 사용할 때 활용 가능.
- 이 자료가 증명하지 않는 것:
  - ca-skeleton 의 실제 adapter enabled property key 이름 (예: `ADAPTER_ASYNC_ENABLED=true` 등) — 구현 단계에서 결정
  - 환경 변수가 존재하지만 빈 문자열일 때의 동작
  - 복수 `@EnabledIfEnvironmentVariable` 선언의 논리 결합(AND vs OR)
  - Spring `@EnabledIf` (Spring-specific 표현식 기반) 와의 혼용 시 우선순위
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - adapter enabled 환경 변수의 실제 키 명명 규칙 (ca-skeleton 구현 단계)
  - CI/CD 에서 adapter env 변수 미설정 시 SKIPPED 로 보고되는지 실 smoke 확인
  - JUnit 5 버전이 ca-skeleton 의 실제 사용 버전과 일치하는지 (5.6 이상이어야 repeatable 사용 가능)

## 메모 / Notes

- 본 자료는 순수 JUnit 5 공식 조건부 실행 API (Jupiter) 를 다룬다. Spring 의 `@EnabledIf`(org.springframework.test.context.junit.jupiter.EnabledIf) 와 JUnit Jupiter 의 `@EnabledIf`(org.junit.jupiter.api.condition.EnabledIf) 는 별개 어노테이션이므로 혼동 주의.
- D3 의 기존 보완 근거 `spring-framework-test-enabledif-jupiter-annotation` 은 Spring Environment property placeholder 기반 — 환경 변수 직접 바인딩이 아님. 본 자료는 OS 환경 변수 직접 참조 방식으로 더 단순하고 Spring 의존성 없는 alternative 를 제공.
- `@EnabledIfEnvironmentVariable` 은 `since: 5.1`, `@EnabledIf`(JUnit) 는 `since: 5.7` 임을 기억.
- 추가로 봐야 할 동일 출처 페이지:
  - JUnit 5 User Guide §2.9 전체 (Operating System / Java / JRE / System Property 조건 등 다른 conditional 어노테이션)
  - Javadoc for `@DisabledIfEnvironmentVariable` (C4 근거 원본)

## Related / 관련

- D3 의 보완 근거 (Spring property 방식): [[raw/official-docs/spring-framework-test-enabledif-jupiter-annotation]]
- 본 자료를 인용하는 branch: [[raw/branch-notes/feature-contract-verification-test-suite]]
- 추후 wiki 요약 (생성 시): `[[wiki/concepts/junit5-conditional-test-execution]]`