pwdebug_skill

Overview

This skill provides a Playwright-based command-line debugger for driving a real Chromium browser instance via CDP. It keeps a persistent browser service so you can run multiple commands that reuse the same browser session. The tool supports navigation, JS evaluation, screenshots, interactive element picking, and console log capture for front-end debugging.

How this skill works

A resident browser service is started by the CLI and listens for subsequent commands that control the same browser session. Commands include nav, evaluate, screenshot, pick, watch-logs and logs; each command connects to the running service and issues the requested CDP/Playwright actions. Logs and server state are persisted to the user cache so you can inspect recent console output and server status between runs.

When to use it

• When you need to interact with a real browser from the shell and preserve state across commands.
• When reproducing UI bugs that require navigation, DOM inspection or JS evaluation over multiple steps.
• When you want automated screenshots or full-page captures from an interactive session.
• When you need to collect console logs or watch runtime logs while exercising a page.
• When you want to pick page elements interactively and run targeted script snippets.

Best practices

• Run the CLI from its containing directory and invoke the script directly (e.g., ./scripts/pwdebug.py start).
• Always start the resident browser service first, then run navigation or other commands to reuse the session.
• Use --new when you need a fresh tab and --full for full-page screenshots to avoid cropping.
• Monitor console logs with watch-logs during test steps, and inspect recent logs via logs N for troubleshooting.
• Keep the environment secure when running a long-lived browser service and avoid exposing it on untrusted networks.

Example use cases

• Start the service, open a site, reproduce a UI flow, then evaluate document state to debug a failing assertion.
• Capture a full-page screenshot of a SPA route after interactive navigation to validate visual regressions.
• Pick a page element interactively to obtain selectors, then run JS snippets against that element for quick fixes.
• Stream console logs while running a user scenario to capture errors and network-related messages in real time.
• Run short ad-hoc scripts (evaluate) against the live page to inspect variables or invoke client-side utilities.