Github Actions 으로 CI 테스트 자동화 중 겪은 이슈 정리 (Embedded Redis, Profile, Spring Rest Docs)

210개의 테스트 코드와 99% 테스트 커버리지

숙소 예약 플랫폼을 개발하며 총 210여 개의 테스트 코드를 작성하고, 99% 테스트 커버리지를 달성했습니다. 하지만 코드에 변경 사항이 있을 때마다 전체 테스트를 수동으로 실행해야 했고, 이는 점점 불편한 작업이 되었습니다.

 

그래서 CI/CD 툴인 GitHub Actions를 도입하여 push 또는 pull_request가 발생할 때 자동으로 테스트가 실행되도록 설정했습니다.

 

GitHub Actions를 선택한 이유

GitHub Actions를 선택한 이유는 단순합니다.

• Jenkins처럼 별도의 서버를 구축할 필요가 없으며,
• 단순히 .github/workflows 디렉토리에 YAML 파일만 작성하면 바로 동작하기 때문입니다.
• 또한 Groovy와 같은 새로운 문법을 배울 필요 없이 빠르게 요구 사항을 충족할 수 있었습니다.

즉, 간단히 설정하고 바로 실행할 수 있었습니다.

 

GitHub Actions에서 전체 테스트 실패

로컬 환경에서 테스트를 실행했을 때는 모든 테스트가 성공했지만, GitHub Actions에서는 전체 테스트 중 70개나 실패했습니다.

./gradlew build 시 Github Actions 에서 보여지는 기존 log

기존에 ./gradlew build를 실행했을 때 GitHub Actions에서 출력되는 로그는 한 줄씩 간단히 표시되어 문제의 원인을 파악하기에 부족했습니다. 그래서 ./gradlew test --stacktrace 명령어를 사용해 더 많은 로그를 출력하여 문제를 분석했습니다.

 

문제 1. Embedded Redis 이슈

원인 분석

./gradlew test --stacktrace로 로그를 확인한 결과, 다음과 같은 에러가 발생했습니다.

Caused by: org.springframework.boot.context.config.ConfigDataResourceNotFoundException at ConfigDataResourceNotFoundException.

 

테스트용 DB로는 내장 H2와 Embedded Redis를 사용하고 있었는데, 일부 테스트만 실패했으며, 그중 Redis 관련 테스트만 실패한 것으로 보아 문제는 H2가 아닌 Redis에 있는 것으로 판단했습니다.

Embedded Redis를 테스트 환경에서 사용하도록 설정했지만, 제대로 적용되지 않은 것으로 보였습니다. 이에 Embedded Redis 설정을 다시 점검하고 수정하기로 했습니다.

 

발생 원인

테스트 환경에서 사용하던 application-test.yml 파일에 잘못된 설정이 포함되어 있었습니다:

  data:
    redis:
      port: 6379
      host: localhost

 

이 설정으로 인해, build.gradle 에 Embedded Redis 라이브러리를 넣었음에도, Embedded Redis가 아닌 로컬 컴퓨터의 도커로 띄워진 개발용 Redis를 참조하고 있었습니다. 로컬에서는 Docker Redis가 실행 중이었기 때문에 테스트가 성공했지만, GitHub Actions에서는 Redis가 없어서 실패한 것입니다.

 

해결 방법

1. application-test.yml 수정

• 테스트에서 Embedded Redis를 사용할 수 있도록 test.yml 에서 Redis 설정을 제거했습니다.

2. Embedded Redis 설정 추가

• Embedded redis 설정 관련 유명한 글인 https://jojoldu.tistory.com/297 참고해서 작성합니다. 코드에 대한 설명은 향로님의 글을 참고해주세요!

@Slf4j
@TestConfiguration
public class EmbeddedRedisConfig {

    private final int port = 6379;

    private RedisServer redisServer;

    @PostConstruct
    public void postConstruct() throws IOException {
        int port = isRedisRunning() ? findAvaliablePort() : this.port;
        this.redisServer = new RedisServer(port);
        redisServer.start();
    }

    @PreDestroy
    public void preDestroy() throws IOException {
        if (redisServer != null) {
            redisServer.stop();
        }
    }

    private int findAvaliablePort() throws IOException{
        for (int port = 10000; port <= 65535; port++) {
            Process process = executeGrepProcessCommand(port);
            if (!isRunning(process)) {
                return port;
            }
        }
        throw new IllegalArgumentException("Not Found Available port: 10000 ~ 65535");
    }

    private boolean isRedisRunning() throws IOException{
        return isRunning(executeGrepProcessCommand(this.port));
    }

    private boolean isRunning(Process process) {
        String line;
        StringBuilder pidInfo = new StringBuilder();

        try (BufferedReader input = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
            while ((line = input.readLine()) != null) {
                pidInfo.append(line);
            }
        } catch (Exception e) {}

        return StringUtils.hasLength(pidInfo.toString());
    }

	// mac, linux 전용
    private Process executeGrepProcessCommand(int port) throws IOException {
        String command = String.format("netstat -nat | grep LISTEN|grep %d", port);
        String[] shell = {"/bin/sh", "-c", command};
        return Runtime.getRuntime().exec(shell);
    }

	// window 전용
    private Process executeGrepProcessCommand(int port) throws IOException {
        String command = String.format("netstat -nao | find \"LISTEN\" | find \"%d\"", port);
        String[] shell = {"cmd.exe", "/y", "/c", command};
        return Runtime.getRuntime().exec(shell);
    }
}

 

향로님의 원본 글과 달리 저는 @TestConfiguration 어노테이션을 붙였습니다.

@TestConfiguration 은 테스트에만 적용되는 설정 어노테이션입니다. 하지만, 이 @TestConfiguration 은 @Configuration 과 다르게 컴포넌트 스캔의 대상이 되지 않기 때문에 임베디드 레디스 설정을 사용하는 곳에서 @Import 를 해줘야 합니다.

 

* 참고

- stackoverflow: Spring Boot: @TestConfiguration Not Overriding Bean During Integration Test

- why prefering @TestConfiguration than @Configuration in src/test

 

추가로, @Configuration은 테스트 시에도 컴포넌트 스캔의 대상이 되어 자동으로 빈에 등록됩니다. 일반적으로 Redis 설정 클래스에는 @Configuration을 붙이는데, 이는 테스트 환경에서도 빈으로 등록되기 때문에 문제가 발생할 수 있습니다. 예를 들어, 테스트용 내장 Redis를 설정하는 @TestConfiguration의 빈과 실제 Redis 설정 클래스의 빈 이름이 중복된다면 빈의 이름 중복 문제가 발생합니다. 이를 간단히 해결하려면, 실제 Redis 설정 클래스에 @Profile("!test")를 추가해 테스트 환경에서는 해당 설정이 적용되지 않도록 설정하면 됩니다

 

문제 2. 외부 설정 이슈 (@Configuration 에 대한 오해)

해당 오류는 외부 설정이 잘못되어 발생하는 오류입니다. (예: application.yml 설정 오류)

Caused by: java.lang.IllegalArgumentException at PropertyPlaceholderHelper.java:180

 

저는 결제 API와 이메일 API를 사용하면서, 외부에 노출되어서는 안 되는 값들을 관리하기 위해 application-secret.yml 파일을 별도로 생성해 테스트에 사용했습니다. 이러한 값들을 참조하는 곳은 @Configuration 어노테이션이 붙은 설정 클래스였으며, 해당 클래스는 테스트 시에도 빈으로 등록됩니다.

 

그래서, 테스트를 함에도 @Autowired 로 주입받은 빈들은 @Configuration 에 의해 secret외부 설정 파일의 값을 읽게 되는 것이었습니다. 로컬의 테스트 환경에서는 문제가 없었지만, Github Actions의 테스트 환경에서는 필요한 외부 설정 값이 누락되게 되었습니다. 이를 해결하기 위해 GitHub Actions의 secret 변수를 활용했습니다. application-secret.yml 파일의 내용을 secret 변수로 등록한 뒤, ./gradlew test를 실행하기 전에 GitHub Actions의 실행 환경(Virtual Machine)에 해당 파일을 동적으로 생성하도록 설정했습니다.

      - name: Gradle 테스트 수행
        run: |
          echo "${{ secrets.APPLICATION_SECRET_PROPERTIES }}" > ./src/main/resources/application-secret.yml
          ./gradlew test --stacktrace

 

 

문제 3. Spring Rest Docs 이슈

Gradle에서 특정 태스크(Task)가 실행되지 못하고 실패하는 경우 발생하는 예외입니다. 제 경우, 실패한 태스크는 :test로, 테스트 실행과 관련된 작업이었습니다.

* Exception is:
org.gradle.api.tasks.TaskExecutionException: Execution failed for task ':test'.

 

저는 API 문서를 위해 Spring Rest Docs를 사용하고 있었습니다. build.gradle 파일에는 Gradle 테스트가 성공하면 스니펫(snippet)을 생성하고, 이를 활용해 API 문서인 .html 파일을 특정 디렉토리로 복사하는 작업을 추가해두었습니다.

configurations {
	compileOnly {
		extendsFrom annotationProcessor
	}
	asciidoctorExt
}

ext {
	snippetsDir = file('build/generated-snippets') // 테스트 성공 후, 생성된 스니펫 저장 경로

test {
	useJUnitPlatform()
	outputs.dir snippetsDir // REST Docs 테스트 결과물을 snippetsDir에 의해 지정된 경로에 저장
}

asciidoctor {
	dependsOn test
	inputs.dir snippetsDir   // REST Docs에서 생성한 스니펫(build/generated-snippets)을 입력으로 사용
	configurations 'asciidoctorExt'
	sources { 
		include("**/index.adoc") // index.adoc 파일만 문서화 대상에 포함
	}
	baseDirFollowsSourceFile() // 다른 adoc 파일을 include 할 때 경로를 baseDir로 맞춘다
}

task createDocument(type: Copy) {
	dependsOn asciidoctor
	from file("build/docs/asciidoc") // 문서가 생성된 경로
	into file("src/main/resources/static") // 문서를 복사할 경로
}

// 생성된 API 문서를 jar 로 변환하는 과정, jar로 배포 안할 시 필요 없음
bootJar {
	dependsOn createDocument
	from("${asciidoctor.outputDir}") {
		into 'static/docs'
	}
}

 

위 설정에서 test 태스크 실행 중 실패했는데, ./gradlew test --stacktrace 명령어만으로는 원인을 알기 어려웠습니다. 그래서 더 자세한 로그를 확인하기 위해 ./gradlew test --stacktrace --info를 실행한 결과, 오류 원인을 찾을 수 있었습니다. 문제는 아래와 같습니다.

./gradlew test --stacktrace --info 시 Github Actions 의 log

 

문제 원인

snippets가 저장될 경로인 /stay/stay-image-update 디렉토리를 생성할 수 없다는 점이 주요 원인이었습니다. 로컬 환경에서는 해당 경로가 정상적으로 생성되었지만, GitHub Actions 환경에서는 생성에 실패했습니다.

 

경로 설정 과정

저는 도메인별로 스니펫을 구분하기 위해 /stay/stay-image-update 와 같은 폴더 구조를 만들고자 했습니다.
즉, Gradle의 build.gradle에서 설정한 ext.snippetsDir 변수와 함께 스니펫의 경로는

build/generated-snippets/stay/stay-image-update로 지정되기를 바랬습니다.

@DisplayName("숙소 이미지 업데이트 API")
@Test
void changeStayImage() throws Exception {
    //given
    ...
        
    // when then
    mockMvc.perform(
                    RestDocumentationRequestBuilders.put("/stay/{stayId}/image", stayId)
                            .contentType(MediaType.APPLICATION_JSON)
                            .content(objectMapper.writeValueAsString(imageUrls))
                            .sessionAttr(LOGIN_MEMBER, 1L)
                            .cookie(new Cookie("JSESSIONID", "ACBCDFD0FF93D5BB"))
            ).andDo(print())
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.code").value("0200"))
            .andExpect(jsonPath("$.status").value("OK"))
            .andExpect(jsonPath("$.message").value("OK"))
            .andExpect(jsonPath("$.data").exists())
            .andDo(document("/stay/stay-image-update",     << ⭐주의해서 볼 부분!!!!⭐
                    preprocessRequest(prettyPrint()),
                    preprocessResponse(prettyPrint()),
                    pathParameters(
                            attributes(key("url").value("/stay/{stayId}/image")),
                            parameterWithName("stayId").description("이미지 업데이트할 숙소 Id")
                    ),
                    requestFields(
                            fieldWithPath("[]").type(JsonFieldType.ARRAY).description("업데이트할 숙소 이미지(최소 5개)")
                    ),
                    responseFields(
                            beneathPath("data"),
                            fieldWithPath("stayId").type(JsonFieldType.NUMBER).description("숙소 ID"),
                            fieldWithPath("hostId").type(JsonFieldType.NUMBER).description("숙소 주인ID"),
                            ...
                            fieldWithPath("imageUrls").type(JsonFieldType.ARRAY).description("숙소 이미지 url")
                    )
            ));
}

 

처음에는 Github Actions VM에서 build 디렉토리가 없어서!? 추측해서 시도했지만, 유효하지 않았습니다. 그러던 중, CircleCI 사용자의 이슈인 Spring Java 8 project, REST DOCS, Failed to create directory 를 참고하여  /stay/stay-image-update를 상대 경로인 stay/stay-image-update로 수정했습니다.

 

왜 "/" 를 제거하는 방법이 유효한지 원인을 찾아보았습니다.

 

원인 분석: 운영 체제의 파일 시스템과 권한 관리 방식의 차이

1. 로컬 환경 (Windows)
   • /로 시작하는 경로를 지정하더라도, Windows 에서는 특정 드라이브(C:\ 등)나 사용자 디렉토리로 매핑되어 디렉토리가 생성됩니다.
   • 따라서 로컬 환경에서 /stay/stay-image-update는 사용자 디렉토리 하위에 생성될 수 있었습니다.
2. GitHub Actions 환경 (Linux/Ubuntu 기반)
   • /로 시작하는 경로는 루트 디렉토리로 인식됩니다.
   • 일반 사용자는 루트 디렉토리에 디렉토리를 생성할 권한이 없습니다. 따라서 GitHub Actions에서는 디렉토리 생성이 실패했습니다
   • 저는 build/snippets 하위에 디렉토리를 생성하려 했지만, 경로를 "/" 로 시작하는 /stay/stay-image-update 루트 디렉토리 경로로 지정하면서 Linux 환경에서는 루트 디렉토리로 잘못 해석된 것이었습니다.

이는 절대 경로와 상대 경로에 대한 이해 부족에서 비롯된 오류였습니다. 그리고, 수정한 결과 드디어 Github Actions 에서 ./gradlew test 를 성공할 수 있게 되었습니다.

./gradlew test 성공 !

 

추가 확인: Linux 환경에서의 권한 제한

루트 디렉토리 생성 권한 확인
WSL(Windows Subsystem for Linux)을 사용해 실제로 일반 사용자가 루트 디렉토리에 디렉토리를 생성할 수 있는지 테스트했습니다.

 

Windows 환경

• 특정 디렉토리에서 /use 디렉토리를 생성하니 C:\ 드라이브에 디렉토리가 생성됐습니다.

Windows 환경

WSL (Linux 환경)

• 동일한 작업을 WSL에서 수행하면 루트 디렉토리(/)에 폴더를 생성하려는 것으로 인식됩니다.
• 일반 사용자는 루트 디렉토리에 폴더 생성 권한이 없기 때문에 아래와 같이 디렉토리 생성할 수 없었습니다.

WSL 환경

 

 

마치며

하루종일 10시간 동안 삽질하며 다음과 같은 많은 것을 배우고 성장할 수 있었습니다.

• @TestConfiguration과 @Configuration의 차이 및 동작 원리
• Spring Boot 의 외부 설정 우선순위
• 운영 체제의 파일 시스템과 권한 관리 방식
• 파일 경로의 절대 경로/상대 경로에 대한 이해
• GitHub Actions에서 로그 확인 및 디버깅 방법

물론, GitHub Actions의 로그가 없었다면 절대로 해결할 수 없었을 문제들이었습니다..
(물론, ./gradlew test --info 명령어로 무한 스크롤 수준의 로그를 확인하는 데는 인내가 필요했지만요...)

 

요즘 다양한 트러블슈팅을 겪으면서 느끼는 점이 있습니다.
왜 문제가 발생했는지 원인을 정의하고 분석해야만, 다음에 비슷한 문제가 발생했을 때 응용할 수 있다는 사실입니다.

앞으로도 항상 "왜 발생했는지"를 깊이 분석하며, 체계적으로 트러블슈팅을 해결해 나가려 합니다.

이번 경험이 GitHub Actions를 사용해 CI 자동화 테스트를 구축하려는 분들이나, 저와 비슷한 오류로 고민 중인 분들에게 도움이 되기를 바라며 마치겠습니다.