JUnit 테스트 오류로 삽질 중인 당신을 위한 2026년판 환경 설정 체크리스트

자바 프로그램은 잘 돌아가는데 JUnit 테스트만 안 될 때 해결법

분명 어제까지는 멀쩡하게 실행되던 코드인데, 오늘 갑자기 테스트 코드만 돌리면 시뻘건 에러 메시지를 뿜어낼 때가 있죠? 사실 이 부분이 개발하면서 가장 번거롭고 맥 빠지는 순간이 아닐까 싶습니다. 메인 로직은 잘 돌아가니 "뭐가 문제겠어" 싶다가도, 테스트가 통과 안 되면 배포조차 못 하는 상황이 오니까요.

 

단순히 라이브러리 문제일 수도 있고, 설정 한 끗 차이로 꼬여버린 경우도 많습니다. 17년 넘게 자바와 씨름하면서 겪었던 테스트 환경 꼬임 문제들을 2026년 최신 IDE 환경 기준으로 깔끔하게 정리해 드릴게요. 억지로 해결하려고 삽질하기 전에 이 순서대로 체크해 보시기 바랍니다.

1단계: 빌드 도구와 IDE의 동기화 상태 점검

가장 흔한 원인은 IntelliJ나 Eclipse 같은 IDE와 Gradle/Maven 빌드 도구 간의 설정이 따로 노는 경우입니다. 실행은 IDE 내부 런너가 돌려주는데, 테스트는 Gradle 래퍼가 돌리도록 설정되어 있으면 환경 변수나 의존성 참조가 엇갈릴 수 있거든요.

 

특히 2026년 현재 최신 버전의 인텔리제이를 쓰신다면, 'Build, Execution, Deployment > Build Tools > Gradle' 메뉴에서 'Run tests using' 항목을 확인해 보세요. IntelliJ IDEA로 설정되어 있다면 Gradle로, 혹은 그 반대로 바꿔보는 것만으로도 해결되는 경우가 70% 이상입니다.

 

개인적으로는 팀 프로젝트라면 모두가 동일한 결과를 얻기 위해 'Gradle'로 통일하는 걸 권장합니다. 직접 경험해 보니 IDE 런너는 가끔 캐시를 제대로 못 비워서 로컬에서만 성공하고 서버(CI/CD)에서는 실패하는 괴상한 일을 만들더라고요.

2단계: 클래스 패스와 의존성 스코프 확인

"메인 소스는 보이는데 왜 테스트에서는 클래스를 못 찾지?"라는 의문이 든다면 의존성 스코프(Scope)를 살펴야 합니다. 자바 프로젝트 구조에서 src/main과 src/test는 엄격하게 분리되어 있습니다.

• implementation: 메인과 테스트 모두 사용 가능
• testImplementation: 테스트 코드에서만 사용 가능
• runtimeOnly: 실행 시에만 필요하고 컴파일 시에는 불필요

간혹 외부 라이브러리를 추가하면서 실수로 스코프를 잘못 지정하면 실행은 되는데 테스트 컴파일 자체가 안 되는 상황이 벌어집니다. 이건 마치 요리는 다 됐는데 시식용 포크만 안 가져온 꼴이죠. 빌드 파일(build.gradle 등)을 열어 최근에 추가한 의존성이 test 관련 키워드로 묶여 있는지 꼭 체크하세요.

📌 사람들이 가장 많이 물어보는 질문

Q: 테스트 실행 시 'No tests found' 메시지가 뜨면 어떻게 하나요?

이건 기술적 오류보다 설정 오류일 확률이 높습니다. 테스트 클래스 이름이 'Test'로 끝나지 않거나, 메서드 위에 @Test 어노테이션이 빠졌는지 보세요. 주관적인 경험상, JUnit 4와 JUnit 5(@Test 패키지명이 다름)를 섞어 쓰다가 어노테이션 임포트가 꼬였을 때 이 메시지를 가장 자주 봤습니다.

3단계: 환경 변수와 설정 파일(application.yml)의 차이

실행(Main) 시에는 로컬 DB에 접속하는데, 테스트(Test) 시에는 H2 임베디드 DB를 쓰도록 설정하셨나요? 만약 테스트용 설정 파일인 src/test/resources/application-test.yml (혹은 properties)이 제대로 로드되지 않으면 테스트는 실패할 수밖에 없습니다.

 

테스트 코드 상단에 @ActiveProfiles("test") 같은 설정이 빠졌는지 확인하세요. 직접 해보니 설정 파일 오타 하나가 하루치 삽질을 부르더군요. 특히 2026년 클라우드 네이티브 환경에서는 환경 변수 주입 방식이 복잡해서, 로컬 머신에 설정된 시스템 변수가 테스트 환경까지 전달 안 되는 경우도 허다합니다.

해결 방법	소요 시간	성공 확률
IDE 캐시 삭제 후 재시작	5분 내외	중
Gradle/Maven 재빌드	2분 내외	고
@Test 어노테이션 패키지 확인	1분 내외	고

표를 보시면 아시겠지만, 의외로 기본적인 재빌드나 어노테이션 체크만으로도 대부분의 문제가 풀립니다. 괜히 로직을 뜯어보기 전에 환경부터 다시 정렬하는 게 시간을 아끼는 비법입니다.

상황별 최종 가이드: 당신은 어떤 케이스인가요?

솔직히 말씀드리면, 모든 상황에 맞는 정답은 없습니다. 하지만 아래 기준에 맞춰 우선순위를 정해보면 금방 답이 나올 겁니다.

• 컴파일 에러가 나는 경우: 빌드 도구 의존성(gradle.build) 스코프와 라이브러리 버전을 먼저 의심하세요.
• 컴파일은 되는데 '런타임 에러'가 나는 경우: 테스트용 DB 설정이나 프로퍼티 파일 로드 여부를 확인해야 합니다.
• 아무 반응 없이 종료되는 경우: IDE의 'Invalidate Caches'를 실행하고 완전히 껐다 켜보세요. (대형마트 오픈런 할 때 셔터 올리는 기분으로 말이죠)

현장에서 주니어 동료들이 이런 문제로 고생할 때 제가 가장 먼저 해주는 조언은 "일단 clean test부터 돌려봐"입니다. 터미널에서 직접 빌드 명령어를 때려봤을 때 성공한다면 그건 100% IDE 설정 문제입니다. 반대로 터미널에서도 안 된다면 그건 코드나 설정 파일의 구조적 결함이고요.

 

너무 스트레스받지 마세요. 테스트가 안 된다는 건 내 코드가 나쁜 게 아니라, 내 환경이 조금 피곤한 상태일 뿐입니다. 잠깐 커피 한 잔 마시고 돌아와서 다시 보면 의외로 오타 하나가 눈에 띌지도 모릅니다. 건승을 빕니다!

VSCode 디버깅 안 될 때 답답하시죠? 현직 개발자가 정리한 5분 체크리스트