From 2e9d5b0acb5e6fd13020519e1807d804d5ab8a80 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Fri, 22 May 2026 14:23:34 -0500 Subject: docs(skills): document headed vs headless choice in playwright skills playwright-js defaulted headed, playwright-py headless, with no explanation, so an agent could flip modes by habit. I added a matching purpose-based decision table to each (headed for interactive debugging, headless for CI/pytest), and made each skill name its own default and point at the other. I also softened the absolutist "always headless" comment in the py example. --- playwright-js/SKILL.md | 7 ++++++- playwright-py/SKILL.md | 8 +++++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/playwright-js/SKILL.md b/playwright-js/SKILL.md index 7c5f10c..b4b037b 100644 --- a/playwright-js/SKILL.md +++ b/playwright-js/SKILL.md @@ -30,7 +30,12 @@ General-purpose browser automation skill. I'll write custom Playwright code for 2. **Write scripts to /tmp** - NEVER write test files to skill directory; always use `/tmp/playwright-test-*.js` -3. **Use visible browser by default** - Always use `headless: false` unless user specifically requests headless mode +3. **Choose headed vs headless by purpose, not habit.** This skill defaults to *headed* (`headless: false`) because its job is interactive visual debugging. The companion `/playwright-py` defaults to *headless* because it targets CI and pytest. The two differ on purpose — pick by what you're doing, and only override when the purpose flips: + + | Purpose | Mode | + |---|---| + | Interactive debugging, watching a flow, demos | headed (`headless: false`) | + | CI, pytest, smoke tests, unattended runs | headless (`headless: true`) | 4. **Parameterize URLs** - Always make URLs configurable via environment variable or constant at top of script diff --git a/playwright-py/SKILL.md b/playwright-py/SKILL.md index 1dee60e..0ed912b 100644 --- a/playwright-py/SKILL.md +++ b/playwright-py/SKILL.md @@ -54,7 +54,7 @@ To create an automation script, include only Playwright logic (servers are manag from playwright.sync_api import sync_playwright with sync_playwright() as p: - browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode + browser = p.chromium.launch(headless=True) # headless for CI/pytest; headless=False for interactive debugging page = browser.new_page() page.goto('http://localhost:5173') # Server already running and ready page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute @@ -87,6 +87,12 @@ with sync_playwright() as p: - Always close the browser when done - Use descriptive selectors: `text=`, `role=`, CSS selectors, or IDs - Add appropriate waits: `page.wait_for_selector()` or `page.wait_for_timeout()` +- **Choose headed vs headless by purpose, not habit.** This skill defaults to *headless* (`headless=True`) because it targets CI and pytest. The companion `/playwright-js` defaults to *headed* for interactive visual debugging. Pick by what you're doing, and only override when the purpose flips: + + | Purpose | Mode | + |---|---| + | CI, pytest, smoke tests, unattended runs | headless (`headless=True`) | + | Interactive debugging, watching a flow | headed (`headless=False`) | ## Reference Files -- cgit v1.2.3