mygo/.agents/skills/playwright-cli/references/session-management.md

Browser Session Management

Run multiple isolated browser sessions concurrently with state persistence.

Named Browser Sessions

Use -s flag to isolate browser contexts:

# Browser 1: Authentication flow
mise exec -- npm run playwright:cli -- -s=auth open https://app.example.com/login

# Browser 2: Public browsing (separate cookies, storage)
mise exec -- npm run playwright:cli -- -s=public open https://example.com

# Commands are isolated by browser session
mise exec -- npm run playwright:cli -- -s=auth fill e1 "user@example.com"
mise exec -- npm run playwright:cli -- -s=public snapshot

Browser Session Isolation Properties

Each browser session has independent:

• Cookies
• LocalStorage / SessionStorage
• IndexedDB
• Cache
• Browsing history
• Open tabs

Browser Session Commands

# List all browser sessions
mise exec -- npm run playwright:cli -- list

# Stop a browser session (close the browser)
mise exec -- npm run playwright:cli -- close                # stop the default browser
mise exec -- npm run playwright:cli -- -s=mysession close   # stop a named browser

# Stop all browser sessions
mise exec -- npm run playwright:cli -- close-all

# Forcefully kill all daemon processes (for stale/zombie processes)
mise exec -- npm run playwright:cli -- kill-all

# Delete browser session user data (profile directory)
mise exec -- npm run playwright:cli -- delete-data                # delete default browser data
mise exec -- npm run playwright:cli -- -s=mysession delete-data   # delete named browser data

Environment Variable

Set a default browser session name via environment variable:

export PLAYWRIGHT_CLI_SESSION="mysession"
mise exec -- npm run playwright:cli -- open example.com  # Uses "mysession" automatically

Common Patterns

Concurrent Scraping

#!/bin/bash
# Scrape multiple sites concurrently

# Start all browsers
mise exec -- npm run playwright:cli -- -s=site1 open https://site1.com &
mise exec -- npm run playwright:cli -- -s=site2 open https://site2.com &
mise exec -- npm run playwright:cli -- -s=site3 open https://site3.com &
wait

# Take snapshots from each
mise exec -- npm run playwright:cli -- -s=site1 snapshot
mise exec -- npm run playwright:cli -- -s=site2 snapshot
mise exec -- npm run playwright:cli -- -s=site3 snapshot

# Cleanup
mise exec -- npm run playwright:cli -- close-all

A/B Testing Sessions

# Test different user experiences
mise exec -- npm run playwright:cli -- -s=variant-a open "https://app.com?variant=a"
mise exec -- npm run playwright:cli -- -s=variant-b open "https://app.com?variant=b"

# Compare
mise exec -- npm run playwright:cli -- -s=variant-a screenshot
mise exec -- npm run playwright:cli -- -s=variant-b screenshot

Persistent Profile

By default, browser profile is kept in memory only. Use --persistent flag on open to persist the browser profile to disk:

# Use persistent profile (auto-generated location)
mise exec -- npm run playwright:cli -- open https://example.com --persistent

# Use persistent profile with custom directory
mise exec -- npm run playwright:cli -- open https://example.com --profile=/path/to/profile

Attaching to a Running Browser

Use attach to connect to a browser that is already running, instead of launching a new one.

Attach by channel name

Connect to a running Chrome or Edge instance by its channel name. The browser must have remote debugging enabled — navigate to chrome://inspect/#remote-debugging in the target browser and check "Allow remote debugging for this browser instance".

# Attach to Chrome
mise exec -- npm run playwright:cli -- attach --cdp=chrome

# Attach to Chrome Canary
mise exec -- npm run playwright:cli -- attach --cdp=chrome-canary

# Attach to Microsoft Edge
mise exec -- npm run playwright:cli -- attach --cdp=msedge

# Attach to Edge Dev
mise exec -- npm run playwright:cli -- attach --cdp=msedge-dev

Supported channels: chrome, chrome-beta, chrome-dev, chrome-canary, msedge, msedge-beta, msedge-dev, msedge-canary.

When --session is not provided, the session is named after the channel (e.g. --cdp=msedge creates a session called msedge), so parallel attaches to Chrome and Edge don't collide on default. Pass --session=<name> to override.

Attach via CDP endpoint

Connect to a browser that exposes a Chrome DevTools Protocol endpoint:

mise exec -- npm run playwright:cli -- attach --cdp=http://localhost:9222

Attach via browser extension

Connect to a browser with the Playwright extension installed:

mise exec -- npm run playwright:cli -- attach --extension

Detach

Tear down an attached session without affecting the external browser:

# Detach the default attached session
mise exec -- npm run playwright:cli -- detach

# Detach a specific attached session
mise exec -- npm run playwright:cli -- -s=msedge detach

detach only works on sessions created via attach. For sessions created via open, use close.

Default Browser Session

When -s is omitted, commands use the default browser session:

# These use the same default browser session
mise exec -- npm run playwright:cli -- open https://example.com
mise exec -- npm run playwright:cli -- snapshot
mise exec -- npm run playwright:cli -- close  # Stops default browser

Browser Session Configuration

Configure a browser session with specific settings when opening:

# Open with config file
mise exec -- npm run playwright:cli -- open https://example.com --config=.playwright/my-cli.json

# Open with specific browser
mise exec -- npm run playwright:cli -- open https://example.com --browser=firefox

# Open in headed mode
mise exec -- npm run playwright:cli -- open https://example.com --headed

# Open with persistent profile
mise exec -- npm run playwright:cli -- open https://example.com --persistent

Best Practices

1. Name Browser Sessions Semantically

# GOOD: Clear purpose
mise exec -- npm run playwright:cli -- -s=github-auth open https://github.com
mise exec -- npm run playwright:cli -- -s=docs-scrape open https://docs.example.com

# AVOID: Generic names
mise exec -- npm run playwright:cli -- -s=s1 open https://github.com

2. Always Clean Up

# Stop browsers when done
mise exec -- npm run playwright:cli -- -s=auth close
mise exec -- npm run playwright:cli -- -s=scrape close

# Or stop all at once
mise exec -- npm run playwright:cli -- close-all

# If browsers become unresponsive or zombie processes remain
mise exec -- npm run playwright:cli -- kill-all

3. Delete Stale Browser Data

# Remove old browser data to free disk space
mise exec -- npm run playwright:cli -- -s=oldsession delete-data