Files

유병철 e34796a53f docs: [frontend] 브라우저 네비게이션 규칙 문서 추가

- AI/E2E 자동화 시 URL 추측 금지, 메뉴 클릭 필수 규칙
- .gitignore에 frontend 폴더 추적 허용
- _index.md에 11번 문서 항목 추가

2026-03-10 17:32:05 +09:00

4.5 KiB

Raw Blame History

11. 브라우저 네비게이션 규칙 (AI/자동화 필수)

대상: AI 에이전트 (Claude, Cursor 등), E2E 테스트 작성자, 브라우저 자동화 개발자 버전: 1.0.0 최종 수정: 2026-03-10

1. 핵심 원칙

URL을 추측하거나 자의적으로 생성하여 주소창에 입력하지 않는다. 반드시 사이드바 메뉴 클릭 또는 앱 내부 라우터(링크/버튼)를 통해서만 페이지를 이동한다.

왜?

SAM ERP는 폐쇄형 시스템으로, 페이지 URL 구조가 외부에 공개되지 않는다. AI가 URL을 추측하면 존재하지 않는 경로로 이동하여 404가 발생하고, E2E 테스트에서는 잘못된 URL로 인해 테스트가 실패하거나 의미 없는 결과를 반환한다.

2. 규칙 상세

2.1 페이지 이동

상황	올바른 방법	금지
메뉴 페이지 이동	사이드바 메뉴 버튼 클릭	URL 직접 입력
상세 페이지 이동	목록에서 행 클릭	URL에 ID 직접 조합
모달/다이얼로그 열기	버튼 클릭	URL 파라미터 추가
뒤로가기	브라우저 뒤로가기 또는 앱 내 버튼	이전 URL 추측 입력
탭 전환	탭 버튼 클릭	URL 해시/쿼리 직접 수정

2.2 현재 페이지 확인

페이지 이동 전, 반드시 현재 상태를 먼저 확인한다.

1. 현재 페이지의 스냅샷/스크린샷 확인
2. 사이드바에서 원하는 메뉴 찾기
3. 메뉴 클릭으로 이동
4. 이동 후 페이지 로드 완료 확인

2.3 사이드바 메뉴 구조

SAM ERP의 사이드바는 2단계 계층 구조이다.

1단계: 대분류 (클릭하면 하위 메뉴 펼침)
  └─ 2단계: 실제 페이지 메뉴 (클릭하면 페이지 이동)

하위 메뉴가 보이지 않으면, 먼저 대분류 버튼을 클릭하여 펼쳐야 한다.

3. AI 에이전트 전용 규칙

3.1 Chrome DevTools MCP 사용 시

✅ 올바른 패턴:
1. take_snapshot → 현재 페이지 및 사이드바 상태 확인
2. click(uid) → 사이드바 대분류 클릭하여 하위 메뉴 펼치기
3. take_snapshot → 하위 메뉴 uid 확인
4. click(uid) → 원하는 페이지 메뉴 클릭
5. take_screenshot → 페이지 로드 확인

❌ 금지 패턴:
- navigate_page("http://localhost:3000/some-guessed-url")
- URL을 추측하여 직접 이동

3.2 E2E 테스트 (Playwright) 작성 시

// ✅ 올바른 패턴 - 메뉴 클릭으로 이동
await page.getByRole('button', { name: '회계관리' }).click();
await page.getByRole('button', { name: '계좌입출금내역' }).click();
await expect(page.getByRole('heading', { name: '계좌 입출금 내역' })).toBeVisible();

// ✅ 허용 - 이미 알려진 URL로 직접 이동 (테스트 효율성)
// 단, URL은 실제 앱에서 확인한 것만 사용
await page.goto('/accounting/bank-transactions');

// ❌ 금지 - URL 추측
await page.goto('/accounting/bank-transaction-inquiry');  // 존재하지 않는 경로
await page.goto('/account/bank');                          // 추측 URL

3.3 URL 확인이 필요할 때

특정 페이지의 URL을 알아야 한다면:

1. 사이드바 메뉴 클릭으로 해당 페이지 이동
2. 이동 후 스냅샷의 RootWebArea url 속성에서 확인
3. 확인된 URL만 이후 작업에 사용

4. 메뉴 → URL 매핑 관리

원칙

URL 매핑 테이블을 별도로 유지하지 않는다 (변경 시 동기화 비용)
항상 앱 사이드바가 Single Source of Truth
URL이 필요하면 메뉴 클릭 후 브라우저에서 확인

예외: 자주 사용하는 진입점

E2E 테스트 효율을 위해 검증된 URL만 하드코딩 허용:

// e2e/fixtures/urls.ts (검증된 URL만 등록)
export const VERIFIED_URLS = {
  dashboard: '/',
  quoteManagement: '/sales/quote-management',
  // ... 실제 앱에서 확인 후 추가
} as const;

이 목록에 없는 URL은 반드시 메뉴 클릭으로 이동한다.

5. 체크리스트

브라우저 자동화 또는 E2E 테스트 작성 시:

URL을 추측하여 직접 입력하지 않았는가?
사이드바 메뉴 또는 앱 내 링크/버튼으로 이동했는가?
이동 후 페이지가 정상 로드되었는지 확인했는가?
하드코딩한 URL이 있다면, 실제 앱에서 검증한 URL인가?
존재하지 않는 페이지(404)로 이동하는 테스트가 없는가?

4.5 KiB Raw Blame History