allra-test-writing

Allra Test Writing Standards

Allra 백엔드 팀의 테스트 작성 표준을 정의합니다. 테스트 헬퍼 선택, Fixture Monkey 데이터 생성, Given-When-Then 패턴, AssertJ 검증을 포함합니다.

프로젝트 기본 정보

이 가이드는 다음 환경을 기준으로 작성되었습니다:

• Java: 17 이상
• Spring Boot: 3.2 이상
• Testing Framework: JUnit 5
• Assertion Library: AssertJ
• Mocking: Mockito
• Test Data: Fixture Monkey (선택 사항)
• Container: Testcontainers (선택 사항)

참고: 프로젝트별로 사용하는 라이브러리나 버전이 다를 수 있습니다. 프로젝트에 맞게 조정하여 사용하세요.

테스트 헬퍼 선택 가이드

주의: 아래 테스트 헬퍼는 Allra 표준 템플릿에서 제공됩니다. 프로젝트에 이러한 헬퍼가 없는 경우, Spring Boot 기본 테스트 어노테이션(@SpringBootTest, @DataJpaTest, @WebMvcTest 등)을 직접 사용하되, 이 가이드의 테스트 패턴과 원칙은 동일하게 적용합니다.

헬퍼	태그	용도	무게	언제?
IntegrationTest	Integration	여러 서비스 통합	🔴 무거움	전체 워크플로우
RdbTest	RDB	Repository, QueryDSL	🟡 중간	쿼리 검증
ControllerTest	Controller	API 엔드포인트	🟢 가벼움	REST API 검증
RedisTest	Redis	Redis 캐싱	🟢 가벼움	캐시 검증
MockingUnitTest	MockingUnit	Service 단위	🟢 매우 가벼움	비즈니스 로직
PojoUnitTest	PojoUnit	도메인 로직	🟢 매우 가벼움	순수 자바

선택 플로우

API 엔드포인트? → ControllerTest
여러 서비스 통합? → IntegrationTest
Repository/QueryDSL? → RdbTest
Redis 캐싱? → RedisTest
Service 로직 (Mock)? → MockingUnitTest
도메인 로직 (POJO)? → PojoUnitTest

---

🎯 Mock vs Integration 선택 기준 (중요!)

원칙: 기본은 MockingUnitTest, 꼭 필요할 때만 IntegrationTest

목표: IntegrationTest 비율 5% 이하 유지

의사결정 플로우차트

┌─────────────────────────────────┐
│ 무엇을 테스트하려고 하는가?    │
└────────────┬────────────────────┘
             │
    ┌────────▼────────┐
    │ 도메인 로직만?  │ ──Yes──> PojoUnitTest
    └────────┬────────┘
             │ No
    ┌────────▼─────────────────────┐
    │ Repository/QueryDSL 쿼리?   │ ──Yes──> RdbTest
    └────────┬─────────────────────┘
             │ No
    ┌────────▼─────────────────────┐
    │ API 엔드포인트 응답/검증?   │ ──Yes──> ControllerTest
    └────────┬─────────────────────┘
             │ No
    ┌────────▼─────────────────────────────┐
    │ Service 비즈니스 로직 검증?         │
    └────────┬─────────────────────────────┘
             │
    ┌────────▼──────────────────────────────────────────┐
    │ 다음 중 하나라도 해당하는가?                      │
    │                                                   │
    │ 1. 💰 금전 처리 (입금/출금/이체/환불)            │
    │ 2. 🔄 트랜잭션 롤백이 중요한 워크플로우           │
    │ 3. 📊 여러 테이블 데이터 정합성 검증             │
    │ 4. 🔐 실제 DB 제약조건 검증 필수                 │
    │ 5. 📝 복잡한 상태 전이 (3단계 이상)              │
    │ 6. 🎯 이벤트 발행/리스너 통합 검증               │
    │ 7. 🤝 3개 이상 서비스 필수 협력                  │
    └────┬──────────────────────────────────────┬────────┘
         │ Yes                                  │ No
         │                                      │
    ┌────▼────────────┐              ┌─────────▼──────────┐
    │ IntegrationTest │              │ MockingUnitTest    │
    │ (최소화)        │              │ (기본 선택)       │
    └─────────────────┘              └────────────────────┘

IntegrationTest가 필요한 구체적인 케이스

✅ 1. 금전 처리 (입금/출금/이체/환불)

이유: 돈이 관련된 로직은 실제 DB 트랜잭션 동작 검증 필수

// 예시: 펀딩 신청 (FsData → FsPayment → PointUsage → UserAccount 연계)
@DisplayName("펀딩 신청 시 금액 차감 및 결제 생성")
class ApplyServiceIntegrationTest extends IntegrationTest {

    @Test
    @Transactional
    void apply_DecreasesAmount_Success() {
        // given: 사용자 잔액 100만원
        User user = createUserWithBalance(1_000_000);

        // when: 50만원 펀딩 신청
        applyService.apply(new ApplyRequest(user.getId(), 500_000));

        // then: 실제 DB에서 잔액 50만원 확인
        User updated = userRepository.findById(user.getId()).get();
        assertThat(updated.getBalance()).isEqualTo(500_000);

        // then: FsPayment 생성 확인
        FsPayment payment = fsPaymentRepository.findByUserId(user.getId()).get();
        assertThat(payment.getAmount()).isEqualTo(500_000);
    }
}

✅ 2. 트랜잭션 롤백이 중요한 워크플로우

이유: 실패 시 모든 작업이 원자적으로 롤백되어야 함

// 예시: 결제 실패 시 전체 롤백
@Test
@DisplayName("결제 실패 시 신청 데이터도 롤백")
void apply_PaymentFails_RollbackAll() {
    // given
    User user = createUser();
    mockPaymentGateway_ToFail(); // 외부 결제는 Mock으로

    // when & then
    assertThatThrownBy(() -> applyService.apply(request))
        .isInstanceOf(PaymentException.class);

    // then: DB에 어떤 데이터도 저장되지 않음
    assertThat(fsDataRepository.findAll()).isEmpty();
    assertThat(fsPaymentRepository.findAll()).isEmpty();
}

참고: 외부 연동(결제 게이트웨이, 외부 API)은 @MockBean으로 처리

✅ 3. 여러 테이블 데이터 정합성 검증

이유: 관련된 모든 테이블의 상태가 일관되게 유지되는지 확인

// 예시: 계약 생성 시 UserAccount, Contract, FsData 모두 생성
@Test
@DisplayName("신규 계약 시 관련 테이블 모두 생성")
void createContract_CreatesAllRelatedData() {
    // when
    contractService.createContract(userId, contractType);

    // then: 3개 테이블 모두 데이터 존재
    assertThat(userAccountRepository.findByUserId(userId)).isPresent();
    assertThat(contractRepository.findByUserId(userId)).isPresent();
    assertThat(fsDataRepository.findByUserId(userId)).isPresent();
}

✅ 4. 실제 DB 제약조건 검증

이유: Unique, FK, Check 제약조건은 실제 DB에서만 확인 가능

// 예시: 중복 계좌 등록 방지
@Test
@DisplayName("동일 계좌번호 중복 등록 시 예외")
void registerAccount_Duplicate_ThrowsException() {
    // given
    userAccountRepository.save(new UserAccount(userId, "123-456-789"));

    // when & then: Unique 제약조건 위반
    assertThatThrownBy(() ->
        userAccountRepository.save(new UserAccount(userId, "123-456-789"))
    ).isInstanceOf(DataIntegrityViolationException.class);
}

✅ 5. 복잡한 상태 전이 (3단계 이상)

이유: 상태 변화 흐름을 실제 시나리오대로 검증

// 예시: 계약 상태 전이 (신청 → 심사 → 승인 → 완료)
@Test
@DisplayName("계약 워크플로우 전체 검증")
void contractWorkflow_FullCycle() {
    // given: 신청
    Contract contract = contractService.create(userId);
    assertThat(contract.getStatus()).isEqualTo(ContractStatus.PENDING);

    // when: 심사
    contractService.review(contract.getId());
    // then
    Contract reviewed = contractRepository.findById(contract.getId()).get();
    assertThat(reviewed.getStatus()).isEqualTo(ContractStatus.REVIEWED);

    // when: 승인
    contractService.approve(contract.getId());
    // then
    Contract approved = contractRepository.findById(contract.getId()).get();
    assertThat(approved.getStatus()).isEqualTo(ContractStatus.APPROVED);
}

✅ 6. 이벤트 발행/리스너 통합 검증

이유: 이벤트가 실제로 발행되고 리스너가 동작하는지 확인

// 예시: 계약 완료 이벤트 → 알림 발송
@Test
@DisplayName("계약 완료 시 알림 이벤트 발행")
void completeContract_PublishesEvent() {
    // given
    Contract contract = createContract(userId);

    // when
    contractService.complete(contract.getId());

    // then: 실제로 알림이 발송되었는가? (외부 알림은 @MockBean)
    verify(notificationService).sendContractCompleteNotification(userId);
}

✅ 7. 3개 이상 서비스가 필수적으로 협력

이유: 서비스 간 상호작용을 실제 환경에서 검증

// 예시: 주문 생성 → 재고 차감 → 결제 → 알림
@Test
@DisplayName("주문 생성 워크플로우")
void createOrder_FullWorkflow() {
    // given
    Product product = createProductWithStock(100);

    // when
    orderService.createOrder(userId, product.getId(), 10);

    // then: 재고 차감
    Product updated = productRepository.findById(product.getId()).get();
    assertThat(updated.getStock()).isEqualTo(90);

    // then: 결제 생성
    Payment payment = paymentRepository.findByUserId(userId).get();
    assertThat(payment.getStatus()).isEqualTo(PaymentStatus.COMPLETED);
}

MockingUnitTest로 충분한 케이스

✅ 대부분의 Service 로직

• 단순 조회 (findById, findAll)
• 데이터 변환/계산
• 검증 로직 (validation)
• 단일 엔티티 CRUD
• 비즈니스 규칙 검증

// 예시: 할인율 계산 로직 (Mock으로 충분)
@ExtendWith(MockitoExtension.class)
class DiscountServiceTest {

    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private DiscountService discountService;

    @Test
    @DisplayName("VIP 회원 10% 할인 계산")
    void calculateDiscount_VipUser_10Percent() {
        // given
        User vipUser = User.builder().grade("VIP").build();
        when(userRepository.findById(1L)).thenReturn(Optional.of(vipUser));

        // when
        BigDecimal discount = discountService.calculateDiscount(1L, new BigDecimal("10000"));

        // then
        assertThat(discount).isEqualByComparingTo(new BigDecimal("1000"));
    }
}

외부 연동 처리 원칙

중요: IntegrationTest에서도 외부 시스템은 @MockBean으로 처리

@SpringBootTest
class PaymentServiceIntegrationTest extends IntegrationTest {

    @Autowired
    private PaymentService paymentService;

    @MockBean // 외부 결제 게이트웨이는 Mock
    private ExternalPaymentGateway externalPaymentGateway;

    @MockBean // 외부 알림 서비스는 Mock
    private ExternalNotificationService notificationService;

    @Test
    @DisplayName("결제 성공 시 내부 데이터 정합성 검증")
    void processPayment_Success() {
        // given: 외부 결제는 성공으로 Mock
        when(externalPaymentGateway.charge(any()))
            .thenReturn(new PaymentResult("SUCCESS", "tx-123"));

        // when: 실제 내부 로직 검증
        paymentService.processPayment(userId, amount);

        // then: 내부 DB 상태 확인
        Payment payment = paymentRepository.findByUserId(userId).get();
        assertThat(payment.getStatus()).isEqualTo(PaymentStatus.COMPLETED);
        assertThat(payment.getExternalTxId()).isEqualTo("tx-123");
    }
}

테스트 전략 요약

테스트 유형	목표 비율	실행 속도	주요 사용처
PojoUnitTest	30%	⚡️ 0.01초	도메인 로직, 유틸리티
MockingUnitTest	50%	⚡️ 0.1초	Service 비즈니스 로직
ControllerTest	10%	🟡 0.5초	API 검증
RdbTest	5%	🟡 1초	복잡한 쿼리 검증
IntegrationTest	5%	🔴 5초	금전/트랜잭션/워크플로우

빠른 판단 체크리스트

새로운 테스트를 작성할 때 다음을 확인하세요:

□ 돈이 관련되어 있나요? (입금/출금/결제)
  → Yes: IntegrationTest

□ 실패 시 데이터 롤백이 중요한가요?
  → Yes: IntegrationTest

□ 3개 이상 테이블의 정합성을 확인해야 하나요?
  → Yes: IntegrationTest

□ DB 제약조건(Unique/FK)이 핵심인가요?
  → Yes: IntegrationTest

□ 복잡한 상태 전이(3단계+)를 검증하나요?
  → Yes: IntegrationTest

□ 이벤트 발행/리스너를 검증하나요?
  → Yes: IntegrationTest

□ 3개 이상 서비스가 협력하나요?
  → Yes: IntegrationTest

모두 No → MockingUnitTest 사용

---

테스트 헬퍼 구조

IntegrationTest - 통합 테스트

@Tag("Integration")
@SpringBootTest
public abstract class IntegrationTest {
    // 전체 Spring Context, Testcontainers 활용
}

언제: 여러 서비스 협력, 실제 DB/외부 시스템 필요 주의: 가장 무거움, 외부 API는 @MockBean 사용

RdbTest - Repository 테스트

@Tag("RDB")
@DataJpaTest
public abstract class RdbTest {}

언제: Repository CRUD, QueryDSL 쿼리, N+1 문제 검증

ControllerTest - API 테스트

@Tag("Controller")
@WebMvcTest(TargetController.class)
public abstract class ControllerTest {
    @Autowired
    protected MockMvc mockMvc;
}

언제: API 엔드포인트, HTTP Status, 입력 검증 주의: Service는 @MockBean 필수

RedisTest - Redis 테스트

@Tag("Redis")
@DataRedisTest
public abstract class RedisTest {}

언제: Redis 캐싱, 세션 저장소 검증

MockingUnitTest - Service 단위 테스트

@ExtendWith(MockitoExtension.class)
class UserServiceTest {
    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserService userService;
}

언제: Service 로직 단위 테스트, 빠른 테스트 주의: Spring Context 없음, @Autowired 불가

PojoUnitTest - 도메인 로직 테스트

class UserTest {
    @Test
    void activate_Success() {
        // 순수 자바 로직 테스트
    }
}

언제: 도메인 엔티티, VO, 유틸리티 클래스

---

Fixture Monkey - 테스트 데이터 생성

의존성 설정

// Gradle
testImplementation 'com.navercorp.fixturemonkey:fixture-monkey-starter:1.0.13'

<!-- Maven -->
<dependency>
    <groupId>com.navercorp.fixturemonkey</groupId>
    <artifactId>fixture-monkey-starter</artifactId>
    <version>1.0.13</version>
    <scope>test</scope>
</dependency>

사용법

import static {your.package}.fixture.FixtureFactory.FIXTURE_MONKEY;

// 단순 생성
User user = FIXTURE_MONKEY.giveMeOne(User.class);

// 특정 필드 지정
User user = FIXTURE_MONKEY.giveMeBuilder(User.class)
    .set("email", "[email protected]")
    .set("active", true)
    .sample();

// 여러 개 생성
List<User> users = FIXTURE_MONKEY.giveMe(User.class, 10);

---

Given-When-Then 패턴 (필수)

모든 테스트는 Given-When-Then 패턴 필수

@Test
@DisplayName("사용자 생성 - 성공")
void createUser_Success() {
    // given - 테스트 준비
    UserRequest request = new UserRequest("[email protected]", "password");
    User savedUser = FIXTURE_MONKEY.giveMeOne(User.class);
    when(userRepository.save(any())).thenReturn(savedUser);

    // when - 실제 실행
    UserResponse response = userService.createUser(request);

    // then - 검증
    assertThat(response).isNotNull();
    verify(userRepository, times(1)).save(any());
}

---

AssertJ 검증 패턴

// 단일 값
assertThat(response).isNotNull();
assertThat(response.userId()).isEqualTo(1L);

// 컬렉션
assertThat(users).hasSize(3);
assertThat(users).extracting(User::getEmail)
    .containsExactlyInAnyOrder("[email protected]", "[email protected]");

// Boolean
assertThat(user.isActive()).isTrue();

// 예외
assertThatThrownBy(() -> userService.findById(999L))
    .isInstanceOf(BusinessException.class)
    .hasMessageContaining("USER_NOT_FOUND");

// Optional
assertThat(result).isPresent();
assertThat(result.get().getName()).isEqualTo("홍길동");

---

Mockito 패턴

Mock 설정

// 반환값
when(userRepository.findById(1L)).thenReturn(Optional.of(user));

// void 메서드
doNothing().when(emailService).sendEmail(any());

// 예외 발생
when(userRepository.findById(999L))
    .thenThrow(new BusinessException(ErrorCode.USER_NOT_FOUND));

Mock 호출 검증

// 호출 횟수
verify(userRepository, times(1)).findById(1L);
verify(userRepository, never()).delete(any());

// 인자 검증
verify(userRepository).save(argThat(user ->
    user.getEmail().equals("[email protected]")
));

---

테스트 명명 규칙

클래스

class ApplyServiceIntegrationTest extends IntegrationTest  // Integration
class UserRepositoryTest extends RdbTest                   // Repository
class UserControllerTest extends ControllerTest            // Controller
class UserServiceTest                                      // Service Unit
class UserTest                                             // Domain

메서드

// 패턴: {메서드명}_{시나리오}_{예상결과}
@Test
@DisplayName("사용자 생성 - 성공")
void createUser_ValidRequest_Success()

@Test
@DisplayName("사용자 조회 - 사용자 없음")
void findById_UserNotFound_ThrowsException()

---

테스트 예시

Controller 테스트

@DisplayName("User -> UserController 테스트")
@WebMvcTest(UserController.class)
class UserControllerTest extends ControllerTest {

    @MockBean
    private UserService userService;

    @Test
    @DisplayName("사용자 조회 API - 성공")
    void getUser_Success() throws Exception {
        // given
        Long userId = 1L;
        UserResponse response = new UserResponse(userId, "[email protected]");
        when(userService.findById(userId)).thenReturn(response);

        // when & then
        mockMvc.perform(get("/api/v1/users/{id}", userId))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.userId").value(userId));
    }
}

Service 단위 테스트

@ExtendWith(MockitoExtension.class)
@DisplayName("User -> UserService 단위 테스트")
class UserServiceTest {

    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserService userService;

    @Test
    @DisplayName("사용자 조회 - 성공")
    void findById_Success() {
        // given
        Long userId = 1L;
        User user = FIXTURE_MONKEY.giveMeBuilder(User.class)
            .set("id", userId)
            .sample();
        when(userRepository.findById(userId)).thenReturn(Optional.of(user));

        // when
        UserResponse response = userService.findById(userId);

        // then
        assertThat(response).isNotNull();
        assertThat(response.userId()).isEqualTo(userId);
        verify(userRepository, times(1)).findById(userId);
    }
}

Repository 테스트

@DisplayName("User -> UserRepository 테스트")
class UserRepositoryTest extends RdbTest {

    @Autowired
    private UserRepository userRepository;

    @Test
    @DisplayName("활성 사용자 조회 - 성공")
    void findActiveUsers_Success() {
        // given
        User active = FIXTURE_MONKEY.giveMeBuilder(User.class)
            .set("active", true)
            .sample();
        userRepository.save(active);

        // when
        List<UserDto> result = userRepository.findActiveUsers();

        // then
        assertThat(result).hasSize(1);
        assertThat(result).extracting(UserDto::email)
            .contains(active.getEmail());
    }
}

---

When to Use This Skill

이 skill은 다음 상황에서 자동으로 적용됩니다:

• 테스트 파일 생성 또는 수정
• 테스트 헬퍼 선택 (IntegrationTest vs MockingUnitTest 판단)
• 테스트 데이터 생성 (Fixture Monkey 사용)
• Given-When-Then 패턴 적용
• AssertJ 검증 코드 작성
• Mockito Mock 설정 및 검증

특히 중요: 새로운 Service 테스트 작성 시 먼저 "Mock vs Integration 선택 기준"을 확인하세요!

---

Checklist

테스트 코드 작성 시 확인사항:

모든 테스트 공통

• Given-When-Then 패턴을 따르는가?
• @DisplayName으로 테스트 의도가 명확한가?
• AssertJ로 검증하는가?
• 메서드명이 메서드_시나리오_결과 패턴인가?

테스트 헬퍼 선택 (가장 먼저 확인!)

• 금전 처리(입금/출금/결제) 또는 트랜잭션 롤백 검증이 필요한가? → IntegrationTest
• 3개 이상 테이블 정합성 또는 DB 제약조건 검증이 필요한가? → IntegrationTest
• 복잡한 상태 전이(3단계+) 또는 이벤트 발행/리스너 검증이 필요한가? → IntegrationTest
• 3개 이상 서비스가 협력하는가? → IntegrationTest
• 위 조건 모두 해당 안됨 → MockingUnitTest 사용

IntegrationTest

• 위 선택 기준 중 하나 이상에 해당하는가?
• 외부 API는 @MockBean으로 처리했는가?
• 정말 IntegrationTest가 필요한지 다시 한번 검토했는가?

RdbTest

• Repository/QueryDSL 테스트만 포함하는가?
• N+1 문제를 검증했는가?

ControllerTest

• @WebMvcTest(TargetController.class)를 명시했는가?
• Service는 @MockBean으로 처리했는가?
• HTTP Status Code를 검증하는가?

MockingUnitTest

• @Mock으로 의존성, @InjectMocks로 테스트 대상을 주입했는가?
• verify()로 Mock 호출을 검증했는가?

PojoUnitTest

• 도메인 로직만 테스트하는가?
• 외부 의존성이 없는가?

---

테스트 실행 명령어

Gradle

./gradlew test                                    # 전체 테스트
./gradlew test --tests * -Dtest.tags=Integration # 태그별 실행
./gradlew test --tests UserServiceTest            # 특정 클래스

Maven

./mvnw test                        # 전체 테스트
./mvnw test -Dgroups=Integration   # 태그별 실행
./mvnw test -Dtest=UserServiceTest # 특정 클래스

---

테스트 품질 기준

1. 커버리지: 핵심 비즈니스 로직 70% 이상
2. 격리성: 각 테스트가 독립적으로 실행 가능
3. 속도: 단위 테스트 1초 이내, 통합 테스트 5초 이내
4. 명확성: 테스트 이름만으로 의도 파악 가능
5. 신뢰성: 같은 입력에 항상 같은 결과