Playwright의 Planner / Generator / Healer 에이전트, Model Context Protocol (MCP) 서버, 그리고 accessibility-tree 중심 자동화를 활용한 에이전트 기반 엔드 투 엔드 (end-to-end) 테스팅 — 제품을 출시하는 QA, SDET 및 AI 엔지니어를 위해 설계되었습니다.

1. 서론 (Introduction)

Playwright는 빠르고 크로스 브라우저(cross-browser)를 지원하는 엔드 투 엔드 (end-to-end) 프레임워크로 시작되었습니다. 1.56 릴리스에서 Playwright는 다른 무언가가 되었습니다. 앱을 탐색하고, 라이브 브라우저를 대상으로 테스트를 작성하며, 실패를 스스로 복구하는 **퍼스트 파티 AI 에이전트 (first-party AI agents)**를 탑재한 최초의 주류 테스트 프레임워크가 된 것입니다. 이 플레이북은 "Playwright AI"를 마케팅 용어가 아닌, 실제로 출시된 세 가지 구체적인 기능으로 다룹니다:

1. Playwright Test Agents — planner, generator, healer (npx playwright init-agents를 통해 프레임워크에 내장됨).
2. Playwright MCP — 스크린샷이 아닌 **접근성 트리 (accessibility tree)**를 통해 어떤 LLM이든 실제 브라우저를 제어할 수 있게 해주는 @playwright/mcp Model Context Protocol (MCP) 서버.
3. Playwright CLI + Skills — 코딩 에이전트를 위한, MCP의 토큰 효율적인 명령 기반 대안.

여기 있는 모든 내용은 출시된 API에 근거합니다. 특정 기술에 트레이드오프 (trade-offs)가 있는 경우, 이를 명확하게 기술합니다.

2. 이 기술이 중요한 이유 (Why This Technology Matters)

E2E 테스팅의 경제성은 항상 불균형했습니다. 테스트를 작성하는 것은 저렴하지만, 이를 **유지보수 (maintaining)**하는 것은 비용이 많이 듭니다. 이름이 변경된 CSS 클래스, 리팩토링된 컴포넌트, 또는 200ms 느려진 모달은 통과하던 파이프라인을 실패(red)로 만듭니다. 그리고 이 중 그 어떤 것도 실제 버그가 아닙니다. 전통적인 셀렉터 (div.checkout-btn-v3)는 매 스프린트마다 변하는 구현 세부 사항에 테스트를 결합시킵니다.

Playwright AI는 두 가지 측면에서 유지보수 비용 문제를 해결합니다:

핵심 통찰 (Key insight): 가치는 무료 테스트 생성이 아니라 _유지보수 감소_에 있습니다. UI가 거의 변경되지 않거나 테스트 스위트가 매우 작다면, 에이전트 설정 오버헤드가 아직 이득이 되지 않을 수도 있습니다.

3. 아키텍처 (Architecture)

2026년의 Playwright AI 스택은 계층화되어 있습니다. MCP (또는 CLI)는 구조화된 브라우저 접근 (structured browser access) 계층이며, 세 개의 에이전트는 그 상단에서 테스트 라이프사이클 (test lifecycle) 계층으로 자리 잡고 있습니다.

graph TD
    subgraph Human["Human / CI"]
        DEV[Engineer or Pipeline]
...

요청 경로의 ASCII 뷰 (ASCII view of the request path):

Engineer prompt
      │
      ▼
...

4. 핵심 구성 요소 (Core Components)

에이전트는 호스팅된 서비스가 아니라, 도구 접근 권한을 가진 정의 (definitions) (Markdown 지침 파일)입니다. LLM이 추론을 수행하며, Playwright가 근거 있는 도구 (grounded tools)를 제공합니다.

5. 내부 동작 (Internal Working)

결정적인 설계 선택은 접근성 트리 우선 (accessibility-tree-first) 자동화입니다. 모델에 픽셀 (pixels)을 입력하는 대신, MCP 서버는 페이지를 구조화된 스냅샷으로 직렬화합니다:

- button "Checkout" [ref=e12]
- textbox "Email" [ref=e7]
- link "Cart (3)" [ref=e3]

모델은 role + 접근 가능한 name + 안정적인 ref를 바탕으로 추론한 뒤, 결정론적인 도구 호출 (browser_click { ref: "e12" })을 실행합니다. 이에 따른 세 가지 결과는 다음과 같습니다:

• 비전 모델 (vision model) 불필요 → 더 저렴하고, 빠르며, 재현 가능합니다.
• 생성된 로케이터 (Locators)가 해결됨 → 생성기가 정적 HTML이 아닌 실제 (live) 브라우저를 구동했기 때문입니다.
• 자가 치유 (Healing)가 근거를 가짐 → Healer는 추측하는 대신 실제 페이지를 다시 스냅샷 찍고 사용 가능한 최선의 role/text 로케이터를 선택합니다.

결정적으로, Healer는 앱 자체에 결함이 있는 경우(예: 결제 프로세스가 실제로 실패함) 버그를 숨기기 위해 단언문 (assertion)을 다시 쓰는 대신 해당 테스트를 건너뜁니다 (skip). 이 단 하나의 규칙이 "자가 치유 (self-healing)"와 "자가 기만 (self-lying)"을 구분 짓는 요소입니다.

6. 단계별 워크플로우 (Step-by-Step Workflow)

sequenceDiagram
    participant E as Engineer
    participant PL as Planner
...

루프는 탐색 (explore) → 계획 (plan) → 생성 (generate) → 실행 (run) → 치유 (heal) 순으로 진행되며, **각 단계 이후에 인간의 승인 게이트 (human approval gate)**가 존재합니다. 검토되지 않은 에이전트 출력물을 절대 병합하지 마십시오.

7. 실제 엔지니어링 사례 (Real Engineering Example)

역할 기반 로케이터 (role-based locators)와 ARIA 스냅샷 어설션 (ARIA snapshot assertion)을 사용하여 생성된 탄력적인 로그인 스펙 (login spec):

// tests/login.spec.ts
import { test, expect } from '@playwright/test';

...

역할 기반 조회가 모호한 경우를 위한 폴백 로케이터 헬퍼 (fallback locator helper) — Healer가 효과적으로 인코딩하는 패턴:

// utils/resilientLocator.ts
import { Page, Locator } from '@playwright/test';

...

8. 프로덕션 유스케이스 (Production Use Cases)

에이전트가 생성한 테스트는 일반적인 Playwright 테스트입니다. 이 테스트들은 GitHub Actions, GitLab CI, Jenkins 또는 Azure Pipelines에서 변경 없이 그대로 실행됩니다. AI는 개발 시점 (development-time) 도구이며, 결과물 (artifact)은 평범하고 이식성이 높습니다 — 바로 여러분이 원하는 형태입니다.

9. 폴더 구조 (Folder Structure)

my-app-e2e/
├── agents/                     # `init-agents`에 의해 생성됨 (PW 업그레이드 시 재생성)
│   ├── planner.md
...

10. 설치 (Installation)

# 1. Playwright 설치 (에이전트는 v1.56+ 필요)
npm init playwright@latest

...

최소한의 MCP 클라이언트 설정 (Claude Code, Cursor, VS Code와 호환):

{
  "mcpServers": {
    "playwright": {
...

참고: init-agents 초기화기는 Node.js Playwright Test 환경에 속합니다. 에이전트 워크플로우에 대해 Python/Java/.NET과의 기능적 동등성 (parity)을 가정하지 마십시오.

11. 설정 (Configuration)

CI 신뢰성과 트레이스 기반 디버깅 (trace-driven debugging)에 최적화된 playwright.config.ts:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
...

CLI 플래그를 통해 생성기 에이전트 (generator agent)의 MCP 노출 범위를 제한 (최소 권한 원칙):

npx @playwright/mcp@latest \
  --allowed-origins "https://staging.example.com" \
  --blocked-origins "https://*.analytics.com" \
...

12. 베스트 프랙티스 (Best Practices)

• CSS/XPath보다 role/name 로케이터 (locators) (getByRole, getByLabel)를 우선적으로 사용하세요. 최후의 수단으로 getByTestId를 사용합니다.
• Playwright 업그레이드 후에는 에이전트 정의 (agent definitions)를 매번 재생성하세요. 에이전트 정의에는 변경될 수 있는 도구 스키마 (tool schemas)가 인코딩되어 있습니다.
• 머지 (merge) 전에는 모든 계획 (plan)과 생성된 스펙 (spec)을 반드시 사람이 검토하세요. 이 검토 단계는 타협할 수 없는 필수 관문입니다.
• Planner에게 인증/설정 (auth/setup)이 포함된 깨끗한 시드 테스트 (seed test)를 제공하세요. Planner는 생성된 각 파일에 설정 로직을 복사합니다.
• **CI에서 에이전트 평가 (agent evals)를 고정 (pin)**하세요. 그래야 모델 성능 저하 (regression)가 조용한 품질 하락이 아닌, 실패한 평가로 드러납니다.
• trace: 'on-first-retry'를 사용하세요. 성공한 실행 (green runs)에 대해 전체 트레이싱 (full tracing)을 수행하는 것은 저장 공간 낭비입니다.
• MCP 접근 권한을 생성기/치유기 (generator/healer)와 일반 어시스턴트 간에 좁게 제한하세요. 제3자 오리진 (third-party origins)은 차단해야 합니다.
• ARIA 스냅샷을 작게 유지하세요. 전체 트리 (tree)가 아닌 의미 있는 랜드마크 (landmarks)를 단언 (assert)해야 합니다.

13. 흔한 실수 (Common Mistakes)

14. 성능 최적화 (Performance Optimization)

• CI 러너 간 샤딩 (Shard across CI runners): 대규모 테스트 스위트를 병렬화하기 위해 --shard=1/4 … --shard=4/4를 사용하세요.
• 인증 상태 (auth state) 재사용: 테스트마다 로그인하는 대신 storageState를 통해 재사용하세요.
• AI 테스트 영향 분석 (AI test-impact analysis): PR diff의 영향을 받는 스펙만 선택하여 실행 시간을 40–75% 단축하세요 (도구: Launchable, Tricentis LiveCompare, Appsurify).
• 코딩 에이전트의 경우 MCP보다 CLI + Skills를 선호하세요. MCP는 대규모 도구 스키마와 장황한 접근성 (a11y) 트리를 컨텍스트 (context)에 로드하지만, CLI 명령은 토큰 효율성 (token-efficient)이 훨씬 높습니다.
• 조정된 workers와 함께 fullyParallel: true 사용: 러너의 vCPU 수에 맞추세요.
• CI에서 브라우저 캐싱: (~/.cache/ms-playwright).

# 샤딩된 병렬 실행 (Sharded parallel execution)
npx playwright test --shard=1/4

15. 보안 고려 사항 (Security Considerations)

• MCP --allowed-origins / --blocked-origins는 편의를 위한 필터일 뿐, 보안 경계(security boundary)가 아닙니다 — 이는 리다이렉트(redirects)에 영향을 미치지 않습니다. 실제 자격 증명(credentials)이 있는 프로덕션(production) 환경에 에이전트를 절대 연결하지 마세요.
• 트레이스(Traces) 및 스냅샷(snapshots)에는 개인정보(PII), 토큰(tokens) 및 전체 네트워크 바디(network bodies)가 포함될 수 있습니다. trace.zip을 민감한 정보로 취급하고, 보존 기간 및 액세스 제어(access controls)를 설정하세요.
• MCP를 최소 권한(least privilege) 원칙에 따라 실행하세요: --isolated, 범위가 지정된 스토리지 상태(scoped storage state), 필요하지 않은 경우 클립보드/지리적 위치(clipboard/geolocation) 권한 부여 금지.
• CI 환경에서는 **수명이 짧고 범위가 지정된 비밀값(short-lived, scoped secrets)**을 사용하고, 에이전트의 PR(Pull Request)이 스스로 머지(self-merge)할 수 없도록 브랜치 보호(branch protection)를 설정하세요.
• 에이전트 탐색을 위해 합성 데이터(synthetic data)가 포함된 **스테이징 환경(staging environments)**을 우선적으로 사용하세요.
• 브라우저를 샌드박스(sandboxed) 상태로 유지하세요 (--no-sandbox는 일회용 컨테이너 내부에서만 사용).

16. 확장 전략 (Scaling Strategies)

graph LR
    A[Single dev, few specs] -->|grows| B[Team suite in CI]
    B -->|churn rises| C[Healer in nightly job]
...

• 작게 시작하기: 완전히 새로운 프로젝트(greenfield)가 아닌, 기존 Playwright 프로젝트에 에이전트를 추가하세요.
• 아침 파이프라인(pipeline)이 시작되기 전 드리프트(drift)를 흡수하기 위해 야간 힐러(Nightly Healer) 작업을 실행하세요.
• 대규모 조직에서 커버리지 격차(coverage gaps)를 드러내기 위해 **예약된 자율 플래너(Scheduled autonomous Planner)**를 실행하세요.
• 테스트 스위트(suite)가 커짐에 따라 실제 소요 시간(wall-clock time)을 일정하게 유지하기 위해 **샤딩(Shard) + 영향 분석(impact analysis)**을 사용하세요.
• 실패 원인을 명확히 파악할 수 있도록 독립적인 에이전트 지표(플래너 커버리지, 생성기 통과율, 힐러 패치 유효성)를 별도로 평가하세요.

17. CI/CD 통합 (CI/CD Integration)

# .github/workflows/e2e.yml
name: E2E
on: [push, pull_request]
...

에이전트 출력물은 특별한 CI가 필요하지 않습니다 — 복구된 .spec.ts 파일은 다른 테스트와 동일하게 실행됩니다. 대화형(interactive) 에이전트 작업은 개발 단계에서 유지하고, CI는 결정론적인(deterministic) 결과만을 실행합니다.

18. 테스트 전략 (Testing Strategy)

graph TD
    U[Unit / Component] --> I[Integration / API]
    I --> E[E2E: Playwright]
...

Playwright AI는 **피라미드의 E2E 정점 (E2E tip of the pyramid)**에 위치합니다. 이는 유닛 (Unit), API, 계약 (Contract), 접근성 (Accessibility), 보안 (Security), 성능 (Performance) 또는 실제 기기 (Real-device) 테스트를 대체하지 않습니다. 에이전트 (Agent)를 사용하여 E2E 작성 및 유지보수 비용을 절감하되, 무엇을 테스트할지 그리고 수정 사항이 정당한지에 대한 판단은 인간의 판단을 유지하십시오.

의사 결정 트리 — 여기서 에이전트를 사용해야 할까요?

실패 원인이 로케이터 드리프트 (Locator drift)인가요? ── 예 ──► Healer
        │ 아니요
        ▼
...

19. 디버깅 가이드 (Debugging Guide)

# 대화형으로 디버깅하기
npx playwright test --debug            # 인스펙터 (inspector)
npx playwright test --ui               # 타임 트래블 UI 모드 (time-travel UI mode)
...

20. 인터뷰 질문 (50개)

개념적 질문 (Conceptual)

1. Playwright Test 에이전트란 무엇인가요? 앱을 탐색하고, 테스트를 작성하며, 라이브 브라우저를 대상으로 실패를 복구하는 세 가지 공식 에이전트 정의 — 플래너 (Planner), 제너레이터 (Generator), 힐러 (Healer) — 입니다 (v1.56에 포함됨).
2. 스크린샷보다 접근성 트리 (Accessibility-tree)를 사용하는 이유는 무엇인가요? 구조화되어 있고 결정론적(Deterministic)이며, 비전 모델 (Vision model)이 필요하지 않습니다. ARIA는 CSS보다 변경이 적으므로 로케이터 (Locator)가 더 안정적입니다.
3. Planner vs Generator vs Healer의 차이는 무엇인가요? Planner → 마크다운 (Markdown) 계획 수립; Generator → .spec.ts 작성; Healer → 실패하는 테스트를 진단 및 패치 (Patch).
4. 자가 치유(Self-healed)된 테스트를 신뢰할 수 있나요? 자동으로 신뢰해서는 안 됩니다. 통과된 재실행이 근본 원인을 증명하는 것은 아니므로 검토가 필요합니다.
5. 앱이 실제로 고장 난 경우 Healer는 무엇을 하나요? 버그를 숨기는 대신 테스트를 건너뜁니다.
6. Playwright MCP란 무엇인가요? 접근성 스냅샷 (Accessibility snapshots)을 통해 브라우저 자동화를 모든 LLM 클라이언트에 노출하는 MCP 서버입니다.
7. CLI+Skills vs MCP — 각각 언제 사용하나요? CLI는 토큰 효율적인 코딩 에이전트 (Coding agents)를 위해, MCP는 지속적이고 반복적인 에이전트 루프 (Agentic loops)를 위해 사용합니다.
8. 에이전트를 추가하는 명령어는 무엇인가요? npx playwright init-agents --loop=<claude|vscode|codex|opencode>.
9. 에이전트를 위한 최소 Playwright 버전은 무엇인가요? 1.56.

에이전트 정의는 어디에 저장되나요? /agents 디렉토리에 Markdown 형식으로 저장됩니다; reg