playwright-debug

Playwright Debug: 3-Tier Hypothesis-First Process

Structured browser debugging that reduces @playwright/cli token usage by 4x by generating hypotheses from code before opening a browser.

Token cost reference: Full CLI session ~114k tokens. Targeted @playwright/cli run-code call ~8-12k tokens. Code-only analysis ~2-4k tokens. Resolve at the cheapest tier possible.

Pre-flight: @playwright/cli Availability Check

Before starting any browser debugging, verify the CLI binary is available:

# Resolve the direct binary path (avoid npx stdout pollution)
PW_CLI="$(npm root)/.bin/playwright"
if [[ ! -x "$PW_CLI" ]]; then
  PW_CLI="$(command -v playwright 2>/dev/null || true)"
fi

if [[ -z "$PW_CLI" || ! -x "$PW_CLI" ]]; then
  echo "ERROR: @playwright/cli binary not found. Install with: npm install @playwright/cli"
  echo "Cannot proceed with browser debugging."
  exit 1
fi

# Verify version
"$PW_CLI" --version

If the binary is not available, do NOT proceed with Tier 2 or Tier 3. Remain in Tier 1 (code analysis only) and report the missing dependency.

Project-Specific Reference (one-time setup)

Many sections below augment the generic guidance with project-specific data (symptom-to-code-path table, framework constraints, worked examples) loaded from a single reference file. Resolve it once at session start:

PLAYWRIGHT_DEBUG_REF=$(bash ".claude/scripts/dso read-config.sh" skills.playwright_debug_reference 2>/dev/null || echo "")

When a section below says "PROJECT-SPECIFIC: read the ## <section name> section from $PLAYWRIGHT_DEBUG_REF", do that lookup if $PLAYWRIGHT_DEBUG_REF is non-empty; skip the section augment if empty.

Session Management

Use a unique session name incorporating the worktree identifier to avoid collisions across concurrent worktrees:

WORKTREE_ID="$(basename "$(git rev-parse --show-toplevel)")"
SESSION_NAME="pw-debug-${WORKTREE_ID}"

All CLI commands below use -s=$SESSION_NAME for session persistence. Open the session once before Tier 2, and register a cleanup trap to ensure the session is closed even if the agent is interrupted: