docs(ko-KR): complete all command translations with full examples

Add missing example sessions, code blocks, and detailed sections to 14 command files that were previously summarized versions.
2026-04-14 13:53:29 +08:00 · 2026-03-10 13:59:43 +09:00
parent cbe2e68c26
commit 3e9c207c25
14 changed files with 1548 additions and 61 deletions
--- a/docs/ko-KR/commands/e2e.md
+++ b/docs/ko-KR/commands/e2e.md
@@ -34,6 +34,253 @@ e2e-runner 에이전트가 수행하는 작업:
 5. 결과와 아티팩트로 **보고서 생성**
 6. **불안정한 테스트 식별** 및 수정 권장

+## 사용 예시
+
+```
+User: /e2e 마켓 검색 및 조회 흐름 테스트
+
+Agent (e2e-runner):
+# E2E 테스트 생성: 마켓 검색 및 조회 흐름
+
+## 식별된 테스트 시나리오
+
+**사용자 여정:** 마켓 검색 → 결과 확인 → 마켓 클릭 → 상세 정보 확인
+
+**테스트 범위:**
+1. 마켓 페이지로 이동
+2. 시맨틱 검색 수행
+3. 검색 결과 확인
+4. 첫 번째 결과 클릭
+5. 마켓 상세 페이지 로드 확인
+6. 차트 렌더링 확인
+
+## 생성된 테스트 코드
+
+```typescript
+// tests/e2e/markets/search-and-view.spec.ts
+import { test, expect } from '@playwright/test'
+import { MarketsPage } from '../../pages/MarketsPage'
+import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
+
+test.describe('Market Search and View Flow', () => {
+  test('user can search markets and view details', async ({ page }) => {
+    // 1. 마켓 페이지로 이동
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // 페이지 로드 확인
+    await expect(page).toHaveTitle(/Markets/)
+    await expect(page.locator('h1')).toContainText('Markets')
+
+    // 2. 시맨틱 검색 수행
+    await marketsPage.searchMarkets('election')
+
+    // API 응답 대기
+    await page.waitForResponse(resp =>
+      resp.url().includes('/api/markets/search') && resp.status() === 200
+    )
+
+    // 3. 검색 결과 확인
+    const marketCards = marketsPage.marketCards
+    await expect(marketCards.first()).toBeVisible()
+    const resultCount = await marketCards.count()
+    expect(resultCount).toBeGreaterThan(0)
+
+    // 검색 결과 스크린샷 촬영
+    await page.screenshot({ path: 'artifacts/search-results.png' })
+
+    // 4. 첫 번째 결과 클릭
+    const firstMarketTitle = await marketCards.first().textContent()
+    await marketCards.first().click()
+
+    // 5. 마켓 상세 페이지 로드 확인
+    await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
+
+    const detailsPage = new MarketDetailsPage(page)
+    await expect(detailsPage.marketName).toBeVisible()
+    await expect(detailsPage.marketDescription).toBeVisible()
+
+    // 6. 차트 렌더링 확인
+    await expect(detailsPage.priceChart).toBeVisible()
+
+    // 마켓 이름 일치 확인
+    const detailsTitle = await detailsPage.marketName.textContent()
+    expect(detailsTitle?.toLowerCase()).toContain(
+      firstMarketTitle?.toLowerCase().substring(0, 20) || ''
+    )
+
+    // 마켓 상세 스크린샷 촬영
+    await page.screenshot({ path: 'artifacts/market-details.png' })
+  })
+
+  test('search with no results shows empty state', async ({ page }) => {
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // 존재하지 않는 마켓 검색
+    await marketsPage.searchMarkets('xyznonexistentmarket123456')
+
+    // 빈 상태 확인
+    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+    await expect(page.locator('[data-testid="no-results"]')).toContainText(
+      /no.*results|no.*markets/i
+    )
+
+    const marketCount = await marketsPage.marketCards.count()
+    expect(marketCount).toBe(0)
+  })
+
+  test('can clear search and see all markets again', async ({ page }) => {
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // 초기 마켓 수
+    const initialCount = await marketsPage.marketCards.count()
+
+    // 검색 수행
+    await marketsPage.searchMarkets('trump')
+    await page.waitForLoadState('networkidle')
+
+    // 필터링된 결과 확인
+    const filteredCount = await marketsPage.marketCards.count()
+    expect(filteredCount).toBeLessThan(initialCount)
+
+    // 검색 초기화
+    await marketsPage.searchInput.clear()
+    await page.waitForLoadState('networkidle')
+
+    // 모든 마켓이 다시 표시되는지 확인
+    const finalCount = await marketsPage.marketCards.count()
+    expect(finalCount).toBe(initialCount)
+  })
+})
+```
+
+## 테스트 실행
+
+```bash
+# 생성된 테스트 실행
+npx playwright test tests/e2e/markets/search-and-view.spec.ts
+
+Running 3 tests using 3 workers
+
+  ✓  [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
+  ✓  [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
+  ✓  [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
+
+  3 passed (9.1s)
+
+생성된 아티팩트:
+- artifacts/search-results.png
+- artifacts/market-details.png
+- playwright-report/index.html
+```
+
+## 테스트 보고서
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                    E2E 테스트 결과                            ║
+╠══════════════════════════════════════════════════════════════╣
+║ 상태:       ✅ 모든 테스트 통과                                ║
+║ 전체:       3개 테스트                                        ║
+║ 통과:       3 (100%)                                         ║
+║ 실패:       0                                                ║
+║ 불안정:     0                                                ║
+║ 소요시간:   9.1s                                             ║
+╚══════════════════════════════════════════════════════════════╝
+
+아티팩트:
+📸 스크린샷: 2개 파일
+📹 비디오: 0개 파일 (실패 시에만)
+🔍 트레이스: 0개 파일 (실패 시에만)
+📊 HTML 보고서: playwright-report/index.html
+
+보고서 확인: npx playwright show-report
+```
+
+✅ CI/CD 통합 준비가 완료된 E2E 테스트 모음!
+```
+
+## 테스트 아티팩트
+
+테스트 실행 시 다음 아티팩트가 캡처됩니다:
+
+**모든 테스트:**
+- 타임라인과 결과가 포함된 HTML 보고서
+- CI 통합을 위한 JUnit XML
+
+**실패 시에만:**
+- 실패 상태의 스크린샷
+- 테스트의 비디오 녹화
+- 디버깅을 위한 트레이스 파일 (단계별 재생)
+- 네트워크 로그
+- 콘솔 로그
+
+## 아티팩트 확인
+
+```bash
+# 브라우저에서 HTML 보고서 확인
+npx playwright show-report
+
+# 특정 트레이스 파일 확인
+npx playwright show-trace artifacts/trace-abc123.zip
+
+# 스크린샷은 artifacts/ 디렉토리에 저장됨
+open artifacts/search-results.png
+```
+
+## 불안정한 테스트 감지
+
+테스트가 간헐적으로 실패하는 경우:
+
+```
+⚠️  불안정한 테스트 감지됨: tests/e2e/markets/trade.spec.ts
+
+테스트가 10회 중 7회 통과 (70% 통과율)
+
+일반적인 실패 원인:
+"요소 '[data-testid="confirm-btn"]'을 대기하는 중 타임아웃"
+
+권장 수정 사항:
+1. 명시적 대기 추가: await page.waitForSelector('[data-testid="confirm-btn"]')
+2. 타임아웃 증가: { timeout: 10000 }
+3. 컴포넌트의 레이스 컨디션 확인
+4. 애니메이션에 의해 요소가 숨겨져 있지 않은지 확인
+
+격리 권장: 수정될 때까지 test.fixme()로 표시
+```
+
+## 브라우저 구성
+
+기본적으로 여러 브라우저에서 테스트가 실행됩니다:
+- Chromium (데스크톱 Chrome)
+- Firefox (데스크톱)
+- WebKit (데스크톱 Safari)
+- Mobile Chrome (선택 사항)
+
+`playwright.config.ts`에서 브라우저를 조정할 수 있습니다.
+
+## CI/CD 통합
+
+CI 파이프라인에 추가:
+
+```yaml
+# .github/workflows/e2e.yml
+- name: Install Playwright
+  run: npx playwright install --with-deps
+
+- name: Run E2E tests
+  run: npx playwright test
+
+- name: Upload artifacts
+  if: always()
+  uses: actions/upload-artifact@v3
+  with:
+    name: playwright-report
+    path: playwright-report/
+```
+
 ## 모범 사례

 **해야 할 것:**
@@ -42,15 +289,46 @@ e2e-runner 에이전트가 수행하는 작업:
 - 임의의 타임아웃 대신 API 응답을 대기
 - 핵심 사용자 여정을 E2E로 테스트
 - main에 merge하기 전에 테스트 실행
+- 테스트 실패 시 아티팩트 검토

 **하지 말아야 할 것:**
 - 취약한 셀렉터 사용 (CSS 클래스는 변경될 수 있음)
 - 구현 세부사항 테스트
 - 프로덕션에 대해 테스트 실행
 - 불안정한 테스트 무시
+- 실패 시 아티팩트 검토 생략
 - E2E로 모든 엣지 케이스 테스트 (단위 테스트 사용)

+## 다른 커맨드와의 연동
+
+- `/plan`을 사용하여 테스트할 핵심 여정 식별
+- `/tdd`를 사용하여 단위 테스트 (더 빠르고 세밀함)
+- `/e2e`를 사용하여 통합 및 사용자 여정 테스트
+- `/code-review`를 사용하여 테스트 품질 검증
+
 ## 관련 에이전트

 이 커맨드는 `e2e-runner` 에이전트를 호출합니다:
 `~/.claude/agents/e2e-runner.md`
+
+## 빠른 커맨드
+
+```bash
+# 모든 E2E 테스트 실행
+npx playwright test
+
+# 특정 테스트 파일 실행
+npx playwright test tests/e2e/markets/search.spec.ts
+
+# headed 모드로 실행 (브라우저 표시)
+npx playwright test --headed
+
+# 테스트 디버그
+npx playwright test --debug
+
+# 테스트 코드 생성
+npx playwright codegen http://localhost:3000
+
+# 보고서 확인
+npx playwright show-report
+```