빌드 및 테스트

이 페이지에서는 Fess 의 빌드 방법, 테스트 방법, 배포 패키지 생성 방법에 대해 설명합니다.

빌드 시스템 개요

Fess 는 Maven을 빌드 도구로 사용합니다. Maven은 의존성 관리, 컴파일, 테스트, 패키징을 자동화합니다.

pom.xml

Maven 설정 파일입니다. 프로젝트 루트 디렉터리에 배치되어 있습니다.

주요 설정 내용:

프로젝트 정보(groupId, artifactId, version)
의존 라이브러리
빌드 플러그인
프로파일

기본 빌드 명령

클린 빌드

빌드 산출물을 삭제한 후 재빌드합니다:

mvn clean compile

패키지 생성

WAR 파일과 배포용 zip 패키지를 생성합니다:

mvn package

산출물은 target/ 디렉터리에 생성됩니다:

target/
├── fess.war
└── releases/
    └── fess-{version}.zip

전체 빌드

클린, 컴파일, 테스트, 패키지를 모두 실행합니다:

mvn clean package

의존성 다운로드

의존 라이브러리를 다운로드합니다:

mvn dependency:resolve

OpenSearch 플러그인 다운로드

OpenSearch와 필수 플러그인을 다운로드합니다:

mvn antrun:run

참고

이 명령은 개발 환경 설정 시나 플러그인을 업데이트할 때 실행합니다.

테스트

Fess 에서는 JUnit을 사용하여 테스트를 구현합니다.

단위 테스트 실행

모든 단위 테스트 실행

mvn test

특정 테스트 클래스 실행

mvn test -Dtest=SearchServiceTest

특정 테스트 메서드 실행

mvn test -Dtest=SearchServiceTest#testSearch

여러 테스트 클래스 실행

mvn test -Dtest=SearchServiceTest,CrawlerTest

테스트 건너뛰기

테스트를 건너뛰고 빌드하는 경우:

mvn package -DskipTests

경고

개발 중에는 테스트를 건너뛰지 말고 반드시 실행하세요. PR 작성 전에는 모든 테스트가 통과하는지 확인하세요.

통합 테스트 실행

통합 테스트에는 integrationTests 프로파일을 사용합니다. 실행하려면 Fess 서버와 OpenSearch가 실행 중이어야 합니다:

mvn test -P integrationTests \
    -Dtest.fess.url="http://localhost:8080" \
    -Dtest.search_engine.url="http://localhost:9201"

참고

통합 테스트 클래스는 *Tests.java 패턴입니다(단위 테스트는 *Test.java).

테스트 작성

단위 테스트 작성

테스트 클래스 배치

테스트 클래스는 src/test/java/ 이하에 배치합니다. 패키지 구조는 본체 코드와 동일하게 합니다.

src/
├── main/java/org/codelibs/fess/app/service/SearchService.java
└── test/java/org/codelibs/fess/app/service/SearchServiceTest.java

테스트 클래스 기본 구조

package org.codelibs.fess.app.service;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

public class SearchServiceTest {

    @Test
    public void testSearch() {
        // Given: 테스트 전제 조건
        SearchService service = new SearchService();
        String query = "test";

        // When: 테스트 대상 실행
        SearchResponse response = service.search(query);

        // Then: 결과 검증
        assertNotNull(response);
        assertTrue(response.getResultCount() > 0);
    }
}

테스트 라이프사이클

import org.junit.jupiter.api.*;

public class MyServiceTest {

    @BeforeAll
    static void setUpClass() {
        // 모든 테스트 전에 1회 실행
    }

    @BeforeEach
    void setUp() {
        // 각 테스트 전에 실행
    }

    @Test
    void testSomething() {
        // 테스트
    }

    @AfterEach
    void tearDown() {
        // 각 테스트 후에 실행
    }

    @AfterAll
    static void tearDownClass() {
        // 모든 테스트 후에 1회 실행
    }
}

어설션

JUnit 5의 어설션을 사용합니다:

import static org.junit.jupiter.api.Assertions.*;

// 동등성
assertEquals(expected, actual);
assertNotEquals(unexpected, actual);

// null 체크
assertNull(obj);
assertNotNull(obj);

// 참/거짓
assertTrue(condition);
assertFalse(condition);

// 예외
assertThrows(IllegalArgumentException.class, () -> {
    service.doSomething();
});

// 컬렉션
assertIterableEquals(expectedList, actualList);

테스트 커버리지

JaCoCo로 테스트 커버리지를 측정합니다:

mvn clean test jacoco:report

리포트는 target/site/jacoco/index.html 에 생성됩니다.

코드 포맷팅

Fess 에서는 코드 품질을 유지하기 위해 다음 도구를 사용합니다.

코드 포맷터

코딩 스타일을 통일합니다:

mvn formatter:format

라이선스 헤더

소스 파일에 라이선스 헤더를 추가합니다:

mvn license:format

커밋 전 검사

커밋 전에 둘 다 실행하세요:

mvn formatter:format
mvn license:format

배포 패키지 생성

zip 패키지 생성

배포용 zip 패키지를 생성합니다:

mvn clean package

생성되는 산출물:

target/releases/
└── fess-{version}.zip

RPM 패키지 생성

mvn rpm:rpm

DEB 패키지 생성

mvn jdeb:jdeb

프로파일

Maven 프로파일을 사용하여 테스트 유형을 전환할 수 있습니다.

build (기본)

기본 프로파일입니다. 단위 테스트(*Test.java)를 실행합니다:

mvn package

integrationTests

통합 테스트(*Tests.java)를 실행하기 위한 프로파일입니다:

mvn test -P integrationTests \
    -Dtest.fess.url="http://localhost:8080" \
    -Dtest.search_engine.url="http://localhost:9201"

CI/CD

Fess 에서는 GitHub Actions를 사용하여 CI/CD를 실행합니다.

GitHub Actions

.github/workflows/ 디렉터리에 설정 파일이 있습니다.

자동 실행되는 검사:

빌드
단위 테스트
패키지 생성

로컬 CI 검사

PR 작성 전에 로컬에서 CI와 동일한 검사를 실행할 수 있습니다:

mvn clean package

문제 해결

빌드 오류

오류: 의존성 다운로드 실패

# Maven 로컬 리포지토리 정리
rm -rf ~/.m2/repository
mvn clean compile

오류: 메모리 부족

# Maven 메모리 증가
export MAVEN_OPTS="-Xmx2g"
mvn clean package

오류: Java 버전이 오래됨

Java 21 이상을 사용하세요:

java -version

테스트 오류

테스트 타임아웃

테스트 타임아웃 시간 연장:

mvn test -Dmaven.test.timeout=600

OpenSearch가 시작되지 않음

포트를 확인하고 사용 중인 경우 변경합니다:

lsof -i :9201

의존성 문제

의존성 충돌

의존성 트리 확인:

mvn dependency:tree

특정 의존성 제외:

<dependency>
    <groupId>org.example</groupId>
    <artifactId>example-lib</artifactId>
    <version>1.0</version>
    <exclusions>
        <exclusion>
            <groupId>conflicting-lib</groupId>
            <artifactId>conflicting-lib</artifactId>
        </exclusion>
    </exclusions>
</dependency>

빌드 모범 사례

정기적인 클린 빌드

정기적으로 클린 빌드를 실행하여 빌드 캐시 문제를 회피합니다:

mvn clean package

테스트 실행

커밋 전에 반드시 테스트를 실행합니다:

mvn test

코드 포맷팅 실행

PR 작성 전에 코드 포맷팅을 실행합니다:

mvn formatter:format
mvn license:format

의존성 업데이트

정기적으로 의존성을 업데이트합니다:

mvn versions:display-dependency-updates

빌드 캐시 활용

빌드 시간을 단축하기 위해 Maven 캐시를 활용합니다:

# 이미 컴파일된 경우 건너뛰기
mvn compile

Maven 명령 참조

자주 사용하는 명령

# 클린
mvn clean

# 컴파일
mvn compile

# 테스트
mvn test

# 패키지
mvn package

# 설치(로컬 리포지토리에 등록)
mvn install

# 검증(통합 테스트 포함)
mvn verify

# 의존성 해결
mvn dependency:resolve

# 의존성 트리 표시
mvn dependency:tree

# 프로젝트 정보 표시
mvn help:effective-pom

# 코드 포맷팅
mvn formatter:format

# 라이선스 헤더 추가
mvn license:format

다음 단계

빌드 및 테스트 방법을 이해했다면 다음 문서를 참조하세요:

개발 워크플로우 - 개발 워크플로우
기여 가이드 - 기여 가이드라인
아키텍처 및 코드 구조 - 코드베이스 이해