Skip to content

core-commands.md

Latest commit

 

History

History
375 lines (280 loc) · 10.3 KB

core-commands.md

File metadata and controls

375 lines (280 loc) · 10.3 KB
Raw

Core Commands

When to use: Starting browser automation sessions, navigating pages, interacting with elements, filling forms, and performing basic browser operations via the CLI. Prerequisites: playwright-cli install --skills && playwright-cli install-browser

Quick Reference

playwright-cli open https://example.com     # Launch + navigate
playwright-cli snapshot                      # See all interactive elements
playwright-cli fill e1 "user@example.com"   # Fill an input field
playwright-cli click e3                      # Click a button
playwright-cli screenshot --filename=pg.png # Capture the page
playwright-cli close                         # Done

The Snapshot Workflow

Every interaction starts with a snapshot. The snapshot command renders the page's accessibility tree and assigns short refs (like e1, e2, e3) to each interactive element.

playwright-cli open https://example.com/login
playwright-cli snapshot
# Output:
# e1 [textbox "Email"]
# e2 [textbox "Password"]
# e3 [button "Sign In"]
# e4 [link "Forgot password?"]
# e5 [link "Create account"]

Use refs to target elements precisely:

playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "secretpassword"
playwright-cli click e3

Always re-snapshot after page changes — refs are only valid for the current page state. After navigation, form submission, or dynamic content updates, take a new snapshot.

playwright-cli click e3          # Submit form
playwright-cli snapshot          # Re-snapshot to see new page elements

Saving Snapshots

Save snapshots to YAML files for later reference or comparison:

playwright-cli snapshot --filename=before-submit.yaml
playwright-cli click e3
playwright-cli snapshot --filename=after-submit.yaml

Opening & Closing Browsers

Basic Launch

# Open browser with blank page
playwright-cli open

# Open and navigate immediately
playwright-cli open https://example.com

# Open with specific browser engine
playwright-cli open --browser=chrome      # Google Chrome
playwright-cli open --browser=firefox     # Mozilla Firefox
playwright-cli open --browser=webkit      # Safari/WebKit
playwright-cli open --browser=msedge      # Microsoft Edge

Persistent Profiles

By default, each session runs in-memory — no cookies or storage persist after closing. Use --persistent to keep state across restarts:

# Auto-generated profile directory
playwright-cli open https://example.com --persistent

# Custom profile directory
playwright-cli open https://example.com --profile=/tmp/my-profile

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

Browser Extension Mode

Connect to an existing browser via extension instead of launching a new one:

playwright-cli open --extension

Closing

playwright-cli close              # Close the current browser
playwright-cli close-all          # Close all open browsers
playwright-cli kill-all           # Force kill zombie processes
playwright-cli delete-data        # Delete stored profile data

Navigation

playwright-cli goto https://example.com/dashboard    # Navigate to URL
playwright-cli go-back                                # Browser back
playwright-cli go-forward                             # Browser forward
playwright-cli reload                                 # Refresh page

Waiting for Navigation

After actions that trigger navigation (form submits, link clicks), the CLI waits for the page to reach load state before returning. If you need to wait for specific conditions, use run-code:

playwright-cli run-code "async page => {
  await page.waitForURL('**/dashboard');
}"

# Wait for network to settle
playwright-cli run-code "async page => {
  await page.waitForLoadState('networkidle');
}"

Element Interaction

Clicking

playwright-cli click e3            # Standard left click
playwright-cli dblclick e7         # Double click
playwright-cli hover e4            # Hover without clicking

Form Input

# fill: clears existing value, then types the full value at once
playwright-cli fill e5 "user@example.com"

# type: sends keystrokes one by one (triggers keydown/keypress/keyup per char)
playwright-cli type "search query"

# select: choose dropdown option by value
playwright-cli select e9 "option-value"

# check/uncheck: toggle checkboxes
playwright-cli check e12
playwright-cli uncheck e12

When to use fill vs type:

Command Behavior Use when
fill Clears field, sets value at once Forms, login fields, standard inputs
type Sends individual keystrokes Autocomplete, search-as-you-type, custom inputs that listen for keydown events

File Upload

playwright-cli upload e8 ./document.pdf
playwright-cli upload e8 ./photo1.jpg ./photo2.jpg    # Multiple files

Drag and Drop

playwright-cli drag e2 e8    # Drag element e2 onto element e8

Viewport Resizing

playwright-cli resize 1920 1080    # Desktop
playwright-cli resize 375 812      # iPhone X viewport
playwright-cli resize 768 1024     # iPad viewport

Keyboard Input

Single Key Presses

playwright-cli press Enter
playwright-cli press Tab
playwright-cli press Escape
playwright-cli press Backspace
playwright-cli press Delete
playwright-cli press Space

Arrow Keys

playwright-cli press ArrowUp
playwright-cli press ArrowDown
playwright-cli press ArrowLeft
playwright-cli press ArrowRight

Modifier Key Combos

playwright-cli press Control+a        # Select all
playwright-cli press Control+c        # Copy
playwright-cli press Control+v        # Paste
playwright-cli press Control+z        # Undo
playwright-cli press Meta+a           # Select all (macOS Cmd+A)
playwright-cli press Shift+Tab        # Reverse tab
playwright-cli press Alt+Enter        # Alt+Enter

Hold and Release Keys

For drag operations or multi-key sequences:

playwright-cli keydown Shift
playwright-cli click e5              # Shift+click
playwright-cli click e8              # Shift+click (range selection)
playwright-cli keyup Shift

Mouse Control

For pixel-precise operations (canvas, maps, custom widgets):

playwright-cli mousemove 150 300     # Move cursor to coordinates
playwright-cli mousedown             # Press left button
playwright-cli mouseup               # Release left button
playwright-cli mousedown right       # Right click down
playwright-cli mouseup right         # Right click up
playwright-cli mousewheel 0 100      # Scroll down 100px
playwright-cli mousewheel 0 -100     # Scroll up 100px
playwright-cli mousewheel 100 0      # Scroll right 100px

Drawing on Canvas

playwright-cli open https://example.com/canvas-app
playwright-cli mousemove 100 100
playwright-cli mousedown
playwright-cli mousemove 200 200
playwright-cli mousemove 300 150
playwright-cli mouseup

Dialog Handling

Dialogs (alert, confirm, prompt) block browser interaction. Handle them immediately:

# Accept an alert or confirm dialog
playwright-cli dialog-accept

# Accept a prompt dialog with input text
playwright-cli dialog-accept "my response"

# Dismiss/cancel a dialog
playwright-cli dialog-dismiss

Tip: If you expect a dialog to appear from a click, configure handling via run-code before triggering the action:

playwright-cli run-code "async page => {
  page.on('dialog', dialog => dialog.accept('confirmed'));
}"
playwright-cli click e5    # This triggers the dialog

JavaScript Evaluation

Execute JavaScript expressions directly in the page context:

# Simple expressions
playwright-cli eval "document.title"
playwright-cli eval "window.location.href"
playwright-cli eval "document.querySelectorAll('li').length"

# Evaluate on a specific element
playwright-cli eval "el => el.textContent" e5
playwright-cli eval "el => el.getAttribute('href')" e3
playwright-cli eval "el => el.getBoundingClientRect()" e1

# Complex evaluation
playwright-cli eval "JSON.stringify(performance.timing)"
playwright-cli eval "window.innerWidth + 'x' + window.innerHeight"

Example Workflows

Login Flow

playwright-cli open https://app.example.com/login
playwright-cli snapshot

playwright-cli fill e1 "admin@example.com"
playwright-cli fill e2 "password123"
playwright-cli click e3
playwright-cli snapshot             # See the dashboard
playwright-cli screenshot --filename=dashboard.png
playwright-cli close

Form Submission with Validation

playwright-cli open https://example.com/contact
playwright-cli snapshot

# Fill form fields
playwright-cli fill e1 "Jane Doe"
playwright-cli fill e2 "jane@example.com"
playwright-cli fill e3 "+1-555-0123"
playwright-cli select e4 "support"
playwright-cli fill e5 "I need help with my account"
playwright-cli check e6             # Agree to terms

# Submit
playwright-cli click e7
playwright-cli snapshot             # Verify success message
playwright-cli close

Search and Navigate Results

playwright-cli open https://example.com
playwright-cli snapshot

playwright-cli fill e1 "playwright automation"
playwright-cli press Enter
playwright-cli snapshot             # See search results

playwright-cli click e5             # Click first result
playwright-cli snapshot             # See result page
playwright-cli go-back              # Return to results
playwright-cli close

Multi-Tab Research

playwright-cli open https://docs.example.com
playwright-cli tab-new https://api.example.com/reference
playwright-cli tab-new https://github.com/example/repo

playwright-cli tab-list             # See all 3 tabs
playwright-cli tab-select 0         # Go to docs tab
playwright-cli snapshot
playwright-cli tab-select 2         # Go to GitHub tab
playwright-cli snapshot

playwright-cli close                # Closes all tabs

Tips

  • Snapshot frequently: After every action that changes the page, re-snapshot to get fresh refs
  • Use fill for forms: It's faster and more reliable than type for standard inputs
  • Viewport matters: Use resize to test responsive layouts before taking screenshots
  • Chain with run-code: When CLI commands feel limiting, drop into the full Playwright API
  • Check console: Run playwright-cli console to see JavaScript errors that might explain unexpected behavior