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

title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, created

title	source_type	url	archive_url	vendor	related_branches	related_projects	tags	created
JUnit 5 User Guide — Conditional Test Execution: Environment Variable Conditions & Custom Conditions	official-doc	https://docs.junit.org/current/user-guide/		junit.org / JUnit Team	feature-contract-verification-test-suite	ca-skeleton	official-doc ca-skeleton testing junit5 conditional-test-execution	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]]