# Playwright 설정 (Chrome 조작)

> 작성일: 2026-07-19 · 한글 복구: 2026-09-07
> 위치: `playwright/`

## 개요

이 프로젝트는 Playwright로 Chrome 또는 Chromium을 열고 문서 페이지 점검, 스크린샷 저장 및 브라우저 자동화를 수행합니다. Chrome 확장 프로그램 없이 별도 브라우저를 실행하거나 CDP로 디버깅용 Chrome에 연결할 수 있습니다.

## 설치 구성

| 항목 | 값 |
|------|-----|
| 패키지 경로 | `C:\Developments\LivekitDev\playwright` |
| 라이브러리 | `playwright`, `@playwright/test` |
| 브라우저 | Playwright Chromium 또는 시스템 Chrome |
| 기존 스크립트 산출물 | `playwright/output/` |

재설치 명령:

```powershell
cd C:\Developments\LivekitDev\playwright
npm install
npm run install:browsers
```

## 명령 요약

| npm script | 동작 |
|------------|------|
| `npm run open:docs` | 문서 사이트를 Chrome 창으로 열고 Enter 입력 시 종료 |
| `npm run open -- <url>` | 지정한 URL 열기 |
| `npm run open:chrome` | 시스템 Chrome으로 기본 URL 열기 |
| `npm run smoke:docs` | 문서 페이지 점검 |
| `npm run attach` | localhost:9222의 디버깅용 Chrome에 연결 |
| `npm test` | Chromium E2E 테스트 |
| `npm run test:chrome` | 시스템 Chrome E2E 테스트 |
| `npm run test:headed` | 브라우저 창을 표시하며 테스트 |
| `npm run test:ui` | Playwright UI 모드 |

## 스크립트

| 파일 | 역할 |
|------|------|
| `scripts/open-url.mjs` | URL 열기, 콘솔 로그 및 스크린샷 |
| `scripts/smoke-docs.mjs` | 문서 페이지 점검 및 JSON 결과 |
| `scripts/attach-chrome.mjs` | 원격 디버깅 Chrome 연결 |
| `tests/docs-site.spec.ts` | 문서 사이트 E2E 테스트 |
| `playwright.config.ts` | baseURL 및 브라우저 프로젝트 설정 |

## 사용 예시

### 문서 사이트 점검

첫 번째 터미널에서 Astro 서버를 실행합니다.

```powershell
cd C:\Developments\LivekitDev\docs-site
npm run dev -- --host 127.0.0.1 --port 4321
```

다른 터미널에서 점검합니다.

```powershell
cd C:\Developments\LivekitDev\playwright
npm run smoke:docs
```

### Chrome 창으로 열기

```powershell
cd C:\Developments\LivekitDev\playwright
npm run open:docs
node scripts/open-url.mjs http://127.0.0.1:4321/guides/getting-started/ --channel=chrome
```

### 디버깅용 Chrome에 연결

별도 프로필로 Chrome을 실행합니다.

```powershell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:TEMP\chrome-playwright-profile"
```

다른 터미널에서 연결합니다.

```powershell
cd C:\Developments\LivekitDev\playwright
node scripts/attach-chrome.mjs http://127.0.0.1:4321
```

## 에이전트 연동

에이전트는 이 폴더의 스크립트를 실행해 브라우저를 제어합니다. 문서 점검에는 smoke-docs, 시각적 확인에는 open-url, 디버깅 세션 연결에는 attach-chrome을 사용합니다.

## 한계

- 별도로 실행한 브라우저는 일상 Chrome의 로그인·프로필·확장 프로그램과 분리됩니다.
- 기존 로그인 세션이 필요한 작업은 연결 대상 프로필을 확인해야 합니다.
- CAPTCHA 등 사이트의 자동화 제한으로 작업이 실패할 수 있습니다.

## 관련 문서

- [프로젝트 분석](/analysis/project-analysis/)
- [시작 가이드](/guides/getting-started/)
- 문서 사이트 소스: `docs-site/`