Skip to content

session-management.md

Latest commit

 

History

History
352 lines (258 loc) · 9.52 KB

session-management.md

File metadata and controls

352 lines (258 loc) · 9.52 KB

Session Management

When to use: Running multiple isolated browser sessions concurrently, managing persistent profiles, comparing different browser states side by side, parallel scraping, or A/B testing flows. Prerequisites: core-commands.md for basic CLI usage

Quick Reference

# Named sessions: each has independent cookies, storage, tabs
playwright-cli -s=auth open https://app.example.com/login
playwright-cli -s=public open https://example.com

# Interact within a session
playwright-cli -s=auth fill e1 "user@example.com"
playwright-cli -s=public snapshot

# List all active sessions
playwright-cli list

# Clean up
playwright-cli -s=auth close
playwright-cli close-all             # Close everything
playwright-cli kill-all              # Force kill zombie processes

Named Sessions

Use the -s=<name> flag to create isolated browser instances. Each named session has its own:

  • Cookies
  • localStorage / sessionStorage
  • IndexedDB
  • Cache
  • Browsing history
  • Open tabs

Creating Sessions

# Create a session for authentication testing
playwright-cli -s=admin open https://app.example.com/login

# Create a separate session for a different user
playwright-cli -s=viewer open https://app.example.com/login

# All commands in a session are isolated
playwright-cli -s=admin fill e1 "admin@company.com"
playwright-cli -s=admin fill e2 "admin-password"
playwright-cli -s=admin click e3

playwright-cli -s=viewer fill e1 "viewer@company.com"
playwright-cli -s=viewer fill e2 "viewer-password"
playwright-cli -s=viewer click e3

Default Session

When -s is omitted, all commands share a single default session:

# These all use the same default session
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli click e1
playwright-cli close

Session Isolation

Sessions are fully independent — actions in one session never affect another:

# Session A logs in as admin
playwright-cli -s=admin open https://app.example.com
playwright-cli -s=admin fill e1 "admin@example.com"
playwright-cli -s=admin fill e2 "admin-pass"
playwright-cli -s=admin click e3

# Session B visits the same site — NOT logged in
playwright-cli -s=guest open https://app.example.com
playwright-cli -s=guest snapshot
# Shows the login page, not the admin dashboard

# Session C can use a completely different browser
playwright-cli -s=firefox-test open https://app.example.com --browser=firefox

Session Commands

# List all active sessions with their status
playwright-cli list

# Close a specific named session
playwright-cli -s=mysession close

# Close the default session
playwright-cli close

# Close ALL sessions at once
playwright-cli close-all

# Force kill all browser daemon processes (for stuck/zombie browsers)
playwright-cli kill-all

# Delete persistent profile data for a session
playwright-cli -s=mysession delete-data

# Delete default session data
playwright-cli delete-data

Persistent Profiles

By default, sessions run in-memory — all cookies, storage, and browsing data are lost when the session closes. Use --persistent to save state to disk.

Auto-Generated Profile

# Playwright-cli manages the profile directory automatically
playwright-cli -s=myapp open https://example.com --persistent

# Close and reopen — cookies and storage are preserved
playwright-cli -s=myapp close
playwright-cli -s=myapp open https://example.com --persistent
# Still logged in!

Custom Profile Directory

# Specify exactly where to store profile data
playwright-cli -s=myapp open https://example.com --profile=/tmp/my-browser-profile

# Useful for sharing profiles between sessions
playwright-cli -s=session-a open https://example.com --profile=/shared/profile
playwright-cli -s=session-a close
playwright-cli -s=session-b open https://example.com --profile=/shared/profile

Cleaning Up Persistent Data

# Remove stored profile data (must close the session first)
playwright-cli -s=myapp close
playwright-cli -s=myapp delete-data

Session Configuration

Configure browser engine and options per session:

# Different browsers for different sessions
playwright-cli -s=chrome-test open https://example.com --browser=chrome
playwright-cli -s=firefox-test open https://example.com --browser=firefox
playwright-cli -s=webkit-test open https://example.com --browser=webkit
playwright-cli -s=edge-test open https://example.com --browser=msedge

# With config file
playwright-cli -s=configured open https://example.com --config=my-config.json

# Headed mode (visible browser window)
playwright-cli -s=visible open https://example.com --headed

# Connect to existing browser via extension
playwright-cli -s=extension open --extension

Environment Variable

Set a default session name so all commands use it without the -s flag:

export PLAYWRIGHT_CLI_SESSION="mysession"

# These now use "mysession" automatically
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli close

Common Patterns

Multi-User Role Testing

Test the same application as different user roles simultaneously:

# Admin session
playwright-cli -s=admin open https://app.example.com/login
playwright-cli -s=admin snapshot
playwright-cli -s=admin fill e1 "admin@company.com"
playwright-cli -s=admin fill e2 "admin-pass"
playwright-cli -s=admin click e3

# Regular user session
playwright-cli -s=user open https://app.example.com/login
playwright-cli -s=user fill e1 "user@company.com"
playwright-cli -s=user fill e2 "user-pass"
playwright-cli -s=user click e3

# Compare what each role sees
playwright-cli -s=admin snapshot     # Should show admin panel
playwright-cli -s=user snapshot      # Should NOT show admin panel

playwright-cli -s=admin screenshot --filename=admin-view.png
playwright-cli -s=user screenshot --filename=user-view.png

Concurrent Scraping

Scrape multiple sites in parallel for speed:

#!/bin/bash

# Launch all browsers concurrently
playwright-cli -s=site1 open https://site1.example.com &
playwright-cli -s=site2 open https://site2.example.com &
playwright-cli -s=site3 open https://site3.example.com &
wait

# Collect data from each
playwright-cli -s=site1 snapshot --filename=site1.yaml
playwright-cli -s=site2 snapshot --filename=site2.yaml
playwright-cli -s=site3 snapshot --filename=site3.yaml

# Take screenshots
playwright-cli -s=site1 screenshot --filename=site1.png
playwright-cli -s=site2 screenshot --filename=site2.png
playwright-cli -s=site3 screenshot --filename=site3.png

# Clean up
playwright-cli close-all

A/B Testing Comparison

# Variant A
playwright-cli -s=variant-a open "https://app.example.com?variant=a"
playwright-cli -s=variant-a screenshot --filename=variant-a.png

# Variant B
playwright-cli -s=variant-b open "https://app.example.com?variant=b"
playwright-cli -s=variant-b screenshot --filename=variant-b.png

# Compare side by side
playwright-cli close-all

Cross-Browser Testing

Run the same flow in multiple browsers to verify compatibility:

#!/bin/bash

for browser in chrome firefox webkit; do
  playwright-cli -s=$browser open https://example.com --browser=$browser
  playwright-cli -s=$browser snapshot
  playwright-cli -s=$browser screenshot --filename="$browser-home.png"

  playwright-cli -s=$browser goto https://example.com/features
  playwright-cli -s=$browser screenshot --filename="$browser-features.png"
done

playwright-cli close-all

Authenticated State Sharing Across Sessions

# Log in once and save state
playwright-cli -s=login open https://app.example.com/login
playwright-cli -s=login fill e1 "user@example.com"
playwright-cli -s=login fill e2 "password123"
playwright-cli -s=login click e3
playwright-cli -s=login state-save auth.json
playwright-cli -s=login close

# Reuse auth state in multiple sessions
playwright-cli -s=session-a open https://app.example.com
playwright-cli -s=session-a state-load auth.json
playwright-cli -s=session-a goto https://app.example.com/dashboard

playwright-cli -s=session-b open https://app.example.com
playwright-cli -s=session-b state-load auth.json
playwright-cli -s=session-b goto https://app.example.com/settings

Best Practices

1. Name Sessions Semantically

# Good: Clear purpose
playwright-cli -s=github-auth open https://github.com
playwright-cli -s=docs-scrape open https://docs.example.com
playwright-cli -s=checkout-flow open https://shop.example.com

# Avoid: Generic names
playwright-cli -s=s1 open https://github.com
playwright-cli -s=test open https://docs.example.com

2. Always Clean Up

# Close individual sessions when done
playwright-cli -s=auth close
playwright-cli -s=scrape close

# Or close all at once
playwright-cli close-all

# If browsers become unresponsive
playwright-cli kill-all

3. Delete Stale Persistent Data

# Remove old persistent profiles to free disk space
playwright-cli -s=old-session delete-data

4. Use Default Session for Single-Task Work

Don't create named sessions when you only need one browser:

# Simple single-session workflow — no -s flag needed
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli click e1
playwright-cli close

5. Combine with State Management

For long-running tasks, save state periodically:

playwright-cli -s=long-task open https://app.example.com --persistent
# ... many interactions ...
playwright-cli -s=long-task state-save checkpoint.json
# ... more interactions ...
# If something goes wrong, restore:
playwright-cli -s=long-task state-load checkpoint.json