[JUnit5] @EnabledIfEnvironmentVariable 이해하기

인트로

테스트 코드를 AI에게 받아 실행해 보았는데 자꾸만 실행이 되지 않았다.

IDE에서는 테스트가 skipped 상태로 표시되고, 터미널에서 `./gradlew test --tests "파일명"` 으로 실행하면 정상 동작하는 상황이었다. 열받아.. 테스트.. 너까지 날 무시해!!

원인을 찾아보니 코드에 붙어 있던 @EnabledIfEnvironmentVariable 어노테이션 때문이었다...(잘알지도 모르는거 쓰지말기..)

 

“왜 IDE에서는 실행되지 않고 터미널에서는 실행될까?“라는 의문이 생겨서 이번에 정리해 본다.

 

---

1. 어노테이션의 역할

 

@EnabledIfEnvironmentVariable 은 JUnit 5에서 제공하는 조건부 실행 어노테이션이다.

테스트 실행 시 특정 환경 변수가 지정된 값과 일치할 때만 해당 테스트가 실행되도록 제어할 수 있다.

@EnabledIfEnvironmentVariable(named = "ENV", matches = "local")
@Test
void onlyRunOnLocalEnv() {
    System.out.println("로컬 환경에서만 실행되는 테스트")
}

위 코드는 ENV=local 환경 변수가 있을 경우에만 실행되며, 조건이 충족되지 않으면 테스트는 실행되지 않고 skipped 상태로 표시된다.

 

 

---

1-1. IDE와 터미널 차이가 나는 이유

• IDE에서 실행할 때는 IDE 런 설정(run configuration)에 등록된 환경 변수만 인식한다.
• 반면 터미널에서 ./gradlew 로 실행할 때는 운영체제 셸에 설정된 환경 변수를 그대로 가져간다.

 

 

즉, 터미널에서는 이미 ENV 같은 값이 셸에 세팅돼 있었기 때문에 조건이 충족되어 테스트가 실행된 것이고,

IDE에서는 해당 값이 없어서 조건 불충족 → skipped 처리된 것이다.

 

따라서 IDE에서도 동일하게 실행하려면 Run Configuration에 환경 변수를 명시적으로 등록해야 한다.

 

 

 

---

 

2. 환경 변수(Environment Variable)란

 

환경 변수는 운영체제 차원에서 관리하는 설정 값으로, 프로세스가 실행될 때 외부에서 주입되는 값이다.

(자바를 사용해본사람이라면 한번쯤은 설정해본 환경변수 설정ㅋㅋ)

 

예를 들어 다음과 같은 값들이 있다.

 

• JAVA_HOME=/usr/lib/jvm/java-17
• ENV=local
• DB_URL=jdbc:mysql://localhost:3306/test

 

환경 변수를 활용하면 코드 내부에 하드코딩하지 않고 환경별로 다른 설정 값을 주입할 수 있어, 실행 환경에 따른 설정 분리에 유리하다.

 

 

---

3. 환경 변수를 설정하는 이유와 시점

 

환경 변수는 보통 다음과 같은 상황에서 설정된다.

 

• 환경 구분: 로컬, 개발, 운영 환경을 구분하기 위해 ENV=local, ENV=dev, ENV=prod 와 같은 값을 설정
• 민감 정보 관리: 데이터베이스 비밀번호, API 키 등은 코드에 직접 포함하지 않고 환경 변수로 관리
• 빌드/배포 파이프라인: GitHub Actions, Jenkins 같은 CI/CD 도구에서 자동으로 세팅
• 컨테이너/클라우드 환경: Docker, Kubernetes, Cloud Run 등에서 -e VAR=value 방식으로 주입

 

---

4. 확인 및 동작 방식

 

JUnit은 내부적으로 System.getenv("ENV") 값을 읽어와 @EnabledIfEnvironmentVariable 어노테이션의 조건과 비교한다.

 

 

4-2. 환경 변수 확인 방법

• Mac/Linux

echo $ENV

 

• Windows PowerShell

echo $env:ENV

 

• Java 코드

System.out.println(System.getenv("ENV"))

 

 

조건이 일치하면 테스트가 실행되고, 그렇지 않으면 skipped 처리된다.

 

---

 

정리

• @EnabledIfEnvironmentVariable 은 환경 변수 조건에 따라 실행 여부를 제어하는 JUnit 5 어노테이션!
• 환경 변수는 실행 환경마다 달라지는 설정 값을 관리하는 수단
• 설정은 OS, IDE 실행 설정, CI/CD, 컨테이너 환경 등에서 이루어짐
• 확인은 터미널이나 System.getenv() 호출을 통해 가능

 

다음 포스팅~

Spring Boot의 @ActiveProfiles 과 의 비교 !!