e34796a53f
- AI/E2E 자동화 시 URL 추측 금지, 메뉴 클릭 필수 규칙 - .gitignore에 frontend 폴더 추적 허용 - _index.md에 11번 문서 항목 추가
136 lines
4.5 KiB
Markdown
136 lines
4.5 KiB
Markdown
# 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) 작성 시
|
|
|
|
```typescript
|
|
// ✅ 올바른 패턴 - 메뉴 클릭으로 이동
|
|
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만 하드코딩 허용:
|
|
|
|
```typescript
|
|
// e2e/fixtures/urls.ts (검증된 URL만 등록)
|
|
export const VERIFIED_URLS = {
|
|
dashboard: '/',
|
|
quoteManagement: '/sales/quote-management',
|
|
// ... 실제 앱에서 확인 후 추가
|
|
} as const;
|
|
```
|
|
|
|
이 목록에 없는 URL은 반드시 메뉴 클릭으로 이동한다.
|
|
|
|
---
|
|
|
|
## 5. 체크리스트
|
|
|
|
브라우저 자동화 또는 E2E 테스트 작성 시:
|
|
|
|
- [ ] URL을 추측하여 직접 입력하지 않았는가?
|
|
- [ ] 사이드바 메뉴 또는 앱 내 링크/버튼으로 이동했는가?
|
|
- [ ] 이동 후 페이지가 정상 로드되었는지 확인했는가?
|
|
- [ ] 하드코딩한 URL이 있다면, 실제 앱에서 검증한 URL인가?
|
|
- [ ] 존재하지 않는 페이지(404)로 이동하는 테스트가 없는가? |