diff --git a/skills/playwright-cli/SKILL.md b/skills/playwright-cli/SKILL.md index b7c8838..d26002a 100644 --- a/skills/playwright-cli/SKILL.md +++ b/skills/playwright-cli/SKILL.md @@ -6,21 +6,36 @@ allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*) # Browser Automation with playwright-cli +## Session lifecycle + +Browser sessions run in a background daemon and stay alive until they are +closed. Treat every `open` or `attach` as acquiring a resource that must be +released before the agent task finishes. + +- Use a unique, semantic named session for each agent task and reuse that name + for every command in the task. +- Close sessions created with `open` by running + `playwright-cli -s= close`, including after failures or early exits. + Use `detach` instead for sessions created with `attach`. +- Do not use `close-all` or `kill-all` for routine cleanup because other agents + may have active sessions. Reserve them for cases where every session is in + scope, or for explicit stale-process recovery. + ## Quick start ```bash -# open new browser -playwright-cli open +# choose a unique session name and reuse it for every command +playwright-cli -s=docs-check open # navigate to a page -playwright-cli goto https://playwright.dev +playwright-cli -s=docs-check goto https://playwright.dev # interact with the page using refs from the snapshot -playwright-cli click e15 -playwright-cli type "page.click" -playwright-cli press Enter +playwright-cli -s=docs-check click e15 +playwright-cli -s=docs-check type "page.click" +playwright-cli -s=docs-check press Enter # take a screenshot (rarely used, as snapshot is more common) -playwright-cli screenshot +playwright-cli -s=docs-check screenshot # close the browser -playwright-cli close +playwright-cli -s=docs-check close ``` ## Commands diff --git a/skills/playwright-cli/references/session-management.md b/skills/playwright-cli/references/session-management.md index bf39acd..da28bb2 100644 --- a/skills/playwright-cli/references/session-management.md +++ b/skills/playwright-cli/references/session-management.md @@ -203,16 +203,26 @@ playwright-cli -s=docs-scrape open https://docs.example.com playwright-cli -s=s1 open https://github.com ``` -### 2. Always Clean Up +### 2. Always Clean Up Agent Sessions + +Cleanup is required for agent tasks. A browser session runs in a detached +daemon and remains alive after the agent finishes unless it is closed. Put the +close command in a `finally` block or shell `trap` when possible so failures +and early exits do not leak the daemon and its browser processes. ```bash -# Stop browsers when done -playwright-cli -s=auth close -playwright-cli -s=scrape close +session=auth +trap 'playwright-cli -s="$session" close >/dev/null 2>&1 || true' EXIT INT TERM -# Or stop all at once -playwright-cli close-all +# Work with the named session here. +playwright-cli -s="$session" open https://example.com +``` +Close only the sessions owned by the current task. `close-all` and `kill-all` +can terminate another agent's active browser, so use them only when every +session is in scope or when explicitly recovering stale processes. + +```bash # If browsers become unresponsive or zombie processes remain playwright-cli kill-all ```