목표

• QA가 앱/기능을 검증할 수 있도록, 명확하고 자세한 수행 절차와 기대 결과가 포함된 QA 시트를 .xlsx로 생성한다.
• 산출물 컬럼은 고정이다: ID / 우선 순위 / 목적/ 사전 조건 / 수행 절차 / 기대 결과 / QA 판정(공란)

실행 절차

0) 범위를 확정한다

• 사용자 명시 지시가 있으면 그 주제를 최우선으로 반영한다. (추가/수정/삭제 범위 포함)
• 명시 지시가 없으면 현재 브랜치 변경 사항을 분석해 영향 범위를 도출한다.
  • git status -sb, git diff --name-only --cached, git diff --name-only로 변경 파일을 수집한다.
  • 변경 파일을 화면/플로우/도메인으로 매핑하고, 관련 사양(docs/specs/)을 확인한다.
  • 기존 QA 시트의 중복/누락을 점검하고 필요한 케이스만 추가/수정/삭제한다.
• 기본 원칙: 단일 qa 파일(qa-sheet.xlsx)만 유지한다. 기존 파일이 있으면 덮어쓰기 생성이 아니라 업데이트(수정/추가/삭제) 한다.

1) 기존 QA 시트를 로드해 업데이트 기반을 만든다

• qa-sheet.xlsx가 있으면 내용을 읽어 케이스 목록으로 변환한다.
  • 필요 시 openpyxl 또는 .xlsx 내부 XML 파싱으로 추출한다.
  • 추출한 케이스를 기준으로 변경 범위에 맞게 수정/추가/삭제한다.
• qa-sheet.xlsx가 없으면 새로 생성한다.

2) QA 케이스를 “절차형”으로 작성한다

• 한 줄(1 row) = 한 테스트 케이스로 작성한다.
• 수행 절차는 번호가 매겨진 단계로 쓴다(예: 1) ..., 2) ...).
• 버튼/메뉴/탭 이름은 앱에 보이는 그대로 적는다.
• 값은 구체적으로 적는다(예: 이메일/문구/설정 값/토글 상태).
• “정상/이상” 모두 포함한다(성공, 실패, 권한 거부, 네트워크 끊김, 빈 값 등).
• 기대 결과는 관찰 가능한 결과로 적는다(화면 전환, 토스트/다이얼로그 문구, 저장된 값, 활성/비활성 상태 등).
• purpose/preconditions에는 코드/구현 용어를 쓰지 않는다. (금지 예: await, result.fold, 함수/클래스/파일명, 내부 모듈명/커버리지명)
• 구현 디테일을 말하고 싶다면 관찰 가능한 동작으로 번역한다. (예: “라우팅” → “OO 화면으로 이동”, “세션 정리” → “로그인 상태 해제/자동 로그아웃”)

3) 입력 파일(qa_cases.json)을 만든다

아래 포맷 중 하나를 사용한다.

주의:

• 입력 파일명은 반드시 qa_cases.json을 사용한다. (다른 파일명/경로는 스크립트가 거절함)

포맷 A: 객체(JSON) + cases

{
  "cases": [
    {
      "id": "AUTH-001",
      "priority": "P0",
      "feature": "로그인 > 이메일 로그인",
      "platform": "공통",
      "purpose": "이메일/비밀번호로 로그인하면 홈 화면으로 이동한다",
      "preconditions": ["테스트 계정 준비", "네트워크 연결"],
      "test_data": ["계정: qa@example.com / Passw0rd!"],
      "steps": [
        "앱 실행",
        "로그인 화면에서 이메일 `qa@example.com` 입력",
        "비밀번호 `Passw0rd!` 입력",
        "로그인 버튼 탭"
      ],
      "expected": ["홈 화면으로 이동한다", "사용자 이름이 표시된다"]
    }
  ]
}

포맷 B: 배열(JSON) = 케이스 목록

[
  { "priority": "P1", "feature": "…", "platform": "…", "purpose": "…", "steps": ["…"], "expected": ["…"] }
]

필드 규칙:

• id(선택): 없으면 QA-001부터 자동 생성
• ID 컨벤션: 도메인-주제-### (대문자 + 하이픈 + 3자리 숫자). 동일 기능 그룹 내 연속 번호를 사용한다. 예: AUTH-SOCIAL-001
• 기존 케이스를 수정하더라도 ID는 가능한 한 유지하고, 컨벤션 불일치 시에만 일괄 정리한다.
• 새 케이스 추가 시 기존 그룹 prefix 재사용을 우선하고, 필요 시 새 그룹을 추가한다.
• priority(선택): 없으면 P2
• feature/screen/scope(권장): 화면/기능 경로. 목적/ 사전 조건 컬럼에 대상(화면/기능): ...로 들어감
• platform(선택): 목적/ 사전 조건 컬럼에 플랫폼: ...로 들어감
• purpose(권장) / preconditions(선택) / test_data(선택): 목적/ 사전 조건 컬럼에 들어감
• steps(필수): 문자열 또는 문자열 배열
• expected(필수): 문자열 또는 문자열 배열

4) 엑셀(.xlsx)로 생성한다

의존성 설치(필요 시, 권장: 가상환경):

python3 -m venv .venv && source .venv/bin/activate && pip install openpyxl

생성:

python3 $CODEX_HOME/skills/qa-sheet-maker/scripts/generate_qa_sheet.py --input qa_cases.json --output qa-sheet.xlsx --strict

주의:

• 위 명령은 시트 생성에 성공하면 입력 파일(qa_cases.json)을 자동으로 삭제한다. (다른 파일명은 입력 자체가 거절됨)
• 입력 파일을 유지하려면 --keep-input을 추가한다.

빈 템플릿(헤더만) 생성:

python3 $CODEX_HOME/skills/qa-sheet-maker/scripts/generate_qa_sheet.py --template --output qa-sheet.xlsx

품질 체크리스트(작성자용)

• 케이스마다 “사전 조건”이 충족 가능한지(계정/권한/데이터/네트워크/버전)
• 수행 절차가 모호한 표현 없이 재현 가능한지(“적당히”, “정상적으로” 금지)
• 기대 결과가 QA가 눈으로 확인할 수 있는 형태인지
• 목적/사전 조건에 코드/구현 용어가 섞이지 않았는지
• 우선순위가 일관적인지(P0: 치명/결제/로그인/데이터 유실 등)
• ID 컨벤션이 일관적인지(그룹 prefix/번호 체계 유지)
• 시트의 케이스 배치가 유사 기능 그룹 연속 실행과 상태 전환 최소화를 고려했는지