68 / 168 · 01 Agent Skills for Browser Automation · Architecture Decision Records for an AI Test Automation Framework← prev⊞ allnext →☰ Read as one page
10.2ADR-002: Playwright CLI Skill as Primary Browser Interface
Context
We evaluated three approaches:
- Playwright MCP server (structured tools, streamed accessibility trees)
- Playwright CLI taught via SKILL.md (
playwright-cli install --skills) - Direct Playwright client library
Decision
Use the Playwright CLI skill as the primary interface, with Playwright MCP reserved for environments without filesystem access.
Rationale
| Criterion | MCP | CLI Skill | Library |
|---|---|---|---|
| Tokens per typical task (measured) | ~114,000 | N/A (not usable by agent directly) | |
| Agent integration | Native | Via Bash tool | Requires code generation |
| Setup complexity | Medium | Low | High |
| Page understanding | Rich (streamed always) | Rich (YAML snapshots, read on demand) | Programmatic |
| CI compatibility | Yes | Yes | Yes |
The CLI's disk-first design leaves the bulk of context for reasoning while providing the same accessibility-tree semantics MCP streams — as files under .playwright-cli/ that the agent reads only when needed. This matches Microsoft's own recommendation for coding agents.
Consequences
- (+) ~4x lower token cost than MCP (up to ~10x on long sessions), per Microsoft's benchmark
- (+) Simple setup (
npm i -g @playwright/cli+playwright-cli install --skills) - (+) Composable with other CLI tools; snapshots are greppable YAML
- (+) Same Playwright engine underneath — auto-waiting, actionability checks, cross-browser
- (-) Disk round-trips add latency versus MCP streaming (cheaper in tokens ≠ faster in wall-clock)
- (-) Requires filesystem access — sandboxed surfaces still need MCP
- (-) Refs go stale when the page changes; recovery means a fresh snapshot read