sam-hotfix/e2e/docs/SCENARIO_QUALITY_IMPROVEMENT_PLAN.md

E2E 시나리오 품질 개선 계획

1. 문제 분석

1.1 이전 시도 실패 원인

문제	잘못된 형식	올바른 형식
필드명 오류	"selector": "..."	"target": "..."
evaluate 문법	return value;	IIFE 필요 없음, 단 복잡한 로직은 IIFE 권장
버튼 클릭	{"action": "click_button"} (target 없음)	{"action": "click", "target": "button:has-text('저장')"}
존재하지 않는 액션	"action": "click_button" (value 필수)	"action": "click", "target": "저장"

1.2 현재 상태

• 통과율: 90/90 (100%)
• 스텝 성공률 낮은 시나리오: 8개 (27~62%)
  • popup-management: 24/89 (27%)
  • payment-history: 4/10 (40%)
  • draft-box: 23/56 (41%)
  • production-dashboard: 5/12 (42%)
  • company-info: 13/30 (43%)
  • purchase-status: 7/15 (47%)
  • settings-subscription: 7/12 (58%)
  • item-management: 63/101 (62%)

---

2. step-executor.js 형식 규칙

2.1 기본 스텝 구조

{
  "id": 1,
  "name": "스텝 이름",
  "action": "액션타입",
  "target": "셀렉터 또는 텍스트",
  "value": "입력값 (옵션)",
  "phase": "CRUD단계 (옵션)",
  "critical": true
}

2.2 target 필드 문법

step-executor의 findEl() 함수가 지원하는 형식:

형식	예시	설명
CSS 셀렉터	"#id", ".class", "input[type='text']"	표준 CSS
:has-text()	"button:has-text('등록')"	텍스트 포함 요소
text=	"text=E2E 테스트"	텍스트 노드 검색
한글 텍스트	"등록"	클릭 가능 요소에서 검색
콤마 구분 폴백	"button.save, button:has-text('저장')"	첫 번째 매치 반환
selectors 참조	"searchInput"	selectors 맵에서 조회

2.3 selectors 맵 활용

{
  "selectors": {
    "searchInput": "input[type='search'], input[placeholder*='검색']",
    "saveButton": "button:has-text('저장'), button:has-text('등록')",
    "table": "table, [role='grid']",
    "tableRows": "table tbody tr, [role='row']"
  },
  "steps": [
    {
      "action": "fill",
      "target": "searchInput",
      "value": "테스트"
    }
  ]
}

2.4 주요 액션 타입

액션	target	value	설명
click	셀렉터/텍스트	-	요소 클릭
click_if_exists	셀렉터/텍스트	-	있으면 클릭, 없으면 pass
fill	셀렉터/텍스트	입력값	입력 필드 채우기
verify_element	셀렉터/텍스트	-	요소 존재 확인
verify_text	-	-	페이지 텍스트 확인 (verification 필요)
wait_for_element	셀렉터/텍스트	-	요소 대기 (timeout 옵션)
wait	-	-	duration ms 대기
evaluate	-	-	script 필드의 JS 실행

2.5 evaluate 스크립트 작성법

{
  "action": "evaluate",
  "script": "document.querySelectorAll('table tbody tr').length > 0"
}

• eval(action.script) 으로 실행됨
• 반환값은 무시되고 항상 pass('evaluate ok') 반환
• 에러 발생 시 warn('evaluate error: ...') 반환
• 복잡한 로직은 IIFE 권장: "(() => { const x = 1; return x; })()"

2.6 verification 객체

{
  "action": "verify_element",
  "target": "table tbody tr",
  "verification": {
    "count": 5,
    "exists": true
  }
}

필드	타입	설명
exists	boolean	존재 여부 (false면 없어야 통과)
count	number	최소 개수
url_contains	string	URL 포함 문자열
visible	array	화면에 보여야 할 텍스트 배열
text	string	포함되어야 할 텍스트

---

3. 품질 개선 전략

3.1 단계별 접근

단계	내용	리스크
1단계	selectors 맵 추가	낮음
2단계	verify_elements → verify_element 변환	낮음
3단계	click_if_exists 타겟 구체화	중간
4단계	evaluate 스크립트 추가	높음

3.2 시나리오별 개선 우선순위

순위	시나리오	현재	목표	복잡도
1	settings-subscription	58%	90%	낮음
2	production-dashboard	42%	85%	낮음
3	payment-history	40%	80%	낮음
4	purchase-status	47%	80%	중간
5	company-info	43%	85%	중간
6	item-management	62%	80%	중간
7	draft-box	41%	75%	높음
8	popup-management	27%	70%	높음

3.3 변환 패턴

패턴 A: verify_elements → verify_element

// Before (soft-pass 가능)
{
  "action": "verify_elements",
  "checks": ["테이블", "검색", "버튼"]
}

// After (실제 검증)
{
  "action": "verify_element",
  "target": "table, [role='grid']"
}

패턴 B: 한글 텍스트 → CSS 셀렉터 + 폴백

// Before
{
  "action": "click_if_exists",
  "target": "등록 버튼"
}

// After
{
  "action": "click_if_exists",
  "target": "button:has-text('등록'), button[class*='add'], button[class*='create']"
}

패턴 C: selectors 맵 활용

// selectors 섹션
{
  "selectors": {
    "addButton": "button:has-text('등록'), button:has-text('추가'), button[class*='add']",
    "searchInput": "input[type='search'], input[placeholder*='검색']"
  }
}

// 스텝에서 참조
{
  "action": "click",
  "target": "addButton"
}

패턴 D: evaluate로 복잡한 검증

{
  "action": "evaluate",
  "script": "document.querySelectorAll('table tbody tr').length >= 1 || document.body.innerText.includes('데이터 없음')"
}

---

4. 실행 계획

4.1 Phase 1: 저위험 시나리오 (3개)

대상: settings-subscription, production-dashboard, payment-history

작업:

1. selectors 맵 추가
2. verify_elements → verify_element 변환
3. 테스트 실행 후 검증

예상 결과: 90/90 유지, 스텝 성공률 80%+ 달성

4.2 Phase 2: 중위험 시나리오 (3개)

대상: purchase-status, company-info, item-management

작업:

1. selectors 맵 추가
2. click_if_exists 타겟 구체화
3. fill 액션 타겟 검증
4. 테스트 실행 후 검증

예상 결과: 90/90 유지, 스텝 성공률 75%+ 달성

4.3 Phase 3: 고위험 시나리오 (2개)

대상: draft-box, popup-management

작업:

1. 시나리오 구조 분석
2. 불필요한 스텝 제거
3. 핵심 CRUD 흐름만 유지
4. 테스트 실행 후 검증

예상 결과: 90/90 유지, 스텝 성공률 70%+ 달성

---

5. 검증 체크리스트

각 시나리오 수정 후 확인사항

• JSON 문법 오류 없음 (node -e "require('./scenario.json')")
• 모든 action 타입이 유효함
• target 필드가 빈 문자열이 아님
• selectors 참조 시 해당 키가 존재함
• evaluate 스크립트 문법 오류 없음
• 단일 시나리오 테스트 통과 (node run-all.js --filter scenario-id)

전체 테스트 후 확인사항

• 90/90 통과 유지
• 각 시나리오 스텝 성공률 목표 달성
• 실행 시간 30분 이내

---

6. 롤백 계획

# 문제 발생 시 즉시 롤백
cd C:/Users/codeb/sam/e2e/scenarios
git revert HEAD
git push

롤백 트리거:

• 통과율 85/90 미만
• 단일 시나리오 완전 실패 (0% 스텝 성공)
• 실행 시간 40분 초과