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 기본 스텝 구조

```json
{
  "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 맵 활용

```json
{
  "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 스크립트 작성법

```json
{
  "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 객체

```json
{
  "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

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

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

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

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

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

#### 패턴 C: selectors 맵 활용

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

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

#### 패턴 D: evaluate로 복잡한 검증

```json
{
  "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. 롤백 계획

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

**롤백 트리거**:
- 통과율 85/90 미만
- 단일 시나리오 완전 실패 (0% 스텝 성공)
- 실행 시간 40분 초과