---
name: browser-agent
description: 브라우저 자동화 에이전트 - 자연어로 브라우저를 조작하고, 스크린샷 획득·비교 및 E2E 테스트 생성
version: 1.0.0
category: testing
platform: claude-code
---

# Browser Agent 스킬

자연어 명령으로 브라우저를 조작하고, 스크린샷을 획득·비교하며, E2E 테스트 코드를 생성하는 에이전트입니다.

## 기능

1. **브라우저 조작**: 한국어/영어 자연어로 브라우저 조작
2. **스크린샷**: 화면 자동 캡처 및 저장
3. **AI 비교**: 기대 화면과 실제 화면을 Vision AI로 비교
4. **테스트 생성**: 조작 이력을 기반으로 Playwright 테스트 코드 자동 생성
5. **ITDA 연동**: EARS 사양으로부터 브라우저 테스트 생성

## 사용 방법

### 인터랙티브 모드

```bash
npx itda browser
```

브라우저를 실행하고, 자연어 명령을 입력받습니다.

### 단일 명령 실행

```bash
npx itda browser run "https://example.com 을 열고 로그인 버튼을 클릭"
```

### 스크립트 실행

```bash
npx itda browser script ./test-script.txt
```

### 스크린샷 비교

```bash
npx itda browser compare expected.png actual.png --threshold 0.95
```

### 테스트 생성

```bash
npx itda browser generate-test --history actions.json --output tests/e2e/login.spec.ts
```

## 지원하는 명령

### 내비게이션

- `https://example.com을 열기`
- `go to https://example.com`
- `로그인 페이지로 이동`

### 클릭

- `로그인 버튼 클릭`
- `click login button`
- `전송 버튼 누르기`

### 입력

- `이메일 입력란에 "test@example.com" 입력`
- `type "hello" in email field`
- `비밀번호에 "secret" 입력`

### 대기

- `3초 대기`
- `wait 5 seconds`
- `로딩이 사라질 때까지 대기`

### 스크린샷

- `스크린샷 찍기`
- `화면을 "login-page"로 저장`
- `take screenshot`

### 검증

- `"로그인 성공"이 표시됨`
- `verify "Welcome" is visible`
- `대시보드가 표시되는지 확인`

## 세션 명령(인터랙티브 모드)

| 명령어                   | 설명                       |
| --------------------- | ------------------------ |
| `history`             | 액션 이력 표시                 |
| `clear`               | 이력 초기화                   |
| `save-test <file>`    | 이력으로부터 Playwright 테스트 저장 |
| `exit` / `quit` / `q` | 브라우저 종료 후 종료             |
| `help` / `?`          | 도움말 표시                   |

## 옵션

| 옵션              | 설명          | 기본값             |
| --------------- | ----------- | --------------- |
| `--headless`    | 헤드리스 모드로 실행 | `true`          |
| `--no-headless` | 브라우저 UI 표시  | -               |
| `-b, --browser` | 브라우저 종류     | `chromium`      |
| `-o, --output`  | 스크린샷 저장 경로  | `./screenshots` |
| `-t, --timeout` | 타임아웃(ms)    | `30000`         |
| `--threshold`   | 유사도 임계값     | `0.95`          |

## ITDA 사양 연동

EARS 형식의 사양으로부터 브라우저 테스트를 생성할 수 있습니다.

```markdown
## Requirements

### REQ-001: User Login

WHEN the user clicks the login button with valid credentials,
the system SHALL display the dashboard page.
```

↓ 생성되는 테스트

```javascript
test('REQ-001: User Login', async ({ page }) => {
  // Pattern: event-driven
  // Trigger: the user clicks the login button with valid credentials
  // Action: display the dashboard page
  // TODO: Implement test based on requirement
});
```

## API

```javascript
const BrowserAgent = require('itda-sdd/src/agents/browser');

const agent = new BrowserAgent({
  headless: true,
  browser: 'chromium',
  outputDir: './screenshots',
});

await agent.launch();
await agent.execute('https://example.com 을 열기');
await agent.execute('로그인 버튼 클릭');

const testCode = await agent.generateTest({
  name: '로그인 테스트',
  output: 'tests/login.spec.ts',
});

await agent.close();
```

## 요구 사항

- Node.js 18 이상
- Playwright(자동 설치)

## 관련 자료

- [Playwright Documentation](https://playwright.dev/)
- [ITDA SDD](https://github.com/gaebalai/itda-sdd)