Read Original
#Backend

상태 전이마다 테스트가 없으면, 운영 가이드가 빌드되지 않습니다

상태 전이마다 테스트가 없으면, 운영 가이드가 빌드되지 않습니다
01

Summary

문서와 코드의 불일치를 Zero로 만드는 flex의 Living Documentation 도전기

상태 전이 선언과 CI 기반 검증으로 깨지지 않는 운영 가이드를 자동 빌드하는 방법

flex 매출 플랫폼 팀이 운영 가이드와 테스트 코드의 불일치로 인한 운영 차질을 해결하기 위해 '테스트가 없는 상태 전이는 빌드를 실패하게 만드는' 자동화 체계를 구축했습니다. YAML 선언을 Single Source of Truth로 삼아 CI 파이프라인에서 테스트 검증을 강제함으로써, 시스템의 안정성과 문서 최신성을 완성도 높게 동기화한 사례를 다룹니다.

  • 01운영 가이드와 actual 테스트 동작 간의 불일치 문제 원인 정밀 분석
  • 02상태, 전이, 화면 액션, 테스트 메서드를 단일 YAML 선언으로 통합 관리
  • 03테스트 참조가 없거나 소스코드와 다르면 CI 빌드를 거부하는 자동화 생성기 구축
  • 04Mermaid 및 ELK 엔진을 활용한 상태 전이 다이어그램 자동 생성 파이프라인 마련
  • 05알려진 결함(Defect)까지 테스트와 연동하여 문서에 정확히 안내하는 방안 제시

RECOMMENDATION

비즈니스 로직 및 상태 관리 복잡도가 높아 운영팀과의 협업과 도메인 문서 최신화가 필수적인 백엔드 개발자 및 DevOps 엔지니어에게 적극 추천합니다.

The Problem

매출 및 결제 도메인의 복잡한 상태 관리 로직에서 기존 문서(위키)와 실제 시스템 동작 및 테스트 코드가 일치하지 않아 운영자 문의 응대 및 데이터 검증에 차질이 발생했습니다. 특히 가이드에 핵심 단계가 누락되어 있거나 E2E 테스트가 CI 실행 대상에서 빠져 있어 문제를 미리 인지하지 못하는 한계가 있었습니다.

The Solution

엔티티별 상태, 전이, 운영자 액션, 그리고 이를 검증하는 테스트 메서드 경로를 단일 YAML 선언에 묶어 정의했습니다. CI 빌드 시 테스트 참조가 누락되었거나 실제 소스코드에 존재하지 않으면 빌드가 실패하도록 생성기를 구현하고, 이 선언으로부터 운영 가이드와 상태 다이어그램을 자동 생성했습니다.

The Result

가이드 기반 실제 업무 처리 실패율이 현격히 줄어들었으며, 상태 전이에 연관된 누락 테스트 및 금지 전이 검증 테스트를 대거 발굴 및 추가하여 코드 품질을 향상시켰습니다. 문서를 수정하지 않거나 테스트를 제거하면 PR 머지가 불가능해져 최신 문서 생성이 보장되었습니다.

Trade-off

수동으로 직접 관리하던 색인 표 등 자동 검증 로직이 미미한 문서 구성 요소에는 여전히 정보 불일치가 발생할 수 있으며, 전이 추가 시 반드시 테스트 코드를 동반 작성해야 하는 작업 공수가 수반됩니다.

03

Key Concepts

Concept · 01

Living Documentation (살아있는 문서화)

소프트웨어의 코드와 테스트가 변경될 때 문서도 함께 자동으로 최신화되어, 문서가 항상 실제 시스템의 동작을 정확히 반영하도록 하는 문서화 방식입니다.

  • YAML 파일에 상태 전이 정보와 관련 테스트를 한데 묶어 관리함
  • CI 빌드 파이프라인에서 자동 검증을 통과한 결과물만 문서로 게시함
Concept · 02

State Transition Declaration (상태 전이 선언)

도메인 엔티티의 가능한 상태 변화 규칙과 이를 유발하는 이벤트, 대응하는 테스트 코드를 선언적인 형식으로 정의하는 구조입니다.

  • 운영자용 액션(UI 버튼)과 개발자용 메서드(Code)를 한 전이 선언 내에 작성함
  • 정상 전이 외에도 허용되지 않는 금지 전이와 미해결 결함(Defects) 정보까지 명시함
Concept · 03

CI Test Verification Enforcement (CI 테스트 검증 강제)

빌드 단계에서 문서 선언에 포함된 테스트 코드가 실제 소스 코드 상에 존재하는지 확인하고, 미존재 시 PR 머지를 차단하는 검증 기법입니다.

  • 테스트 참조가 비어 있거나 존재하지 않으면 'Test reference does not exist' 오류를 발생시킴
  • 개발자가 상태 전이를 변경하거나 테스트를 수정할 때 선언도 함께 고치도록 강제함