electron-playwright-cli 0.1.0

package/skills/playwright-cli/references/running-code.md

@@ -0,0 +1,226 @@
+# Running Custom Playwright Code
+
+Use `run-code` to execute arbitrary Playwright code for advanced scenarios not covered by CLI commands.
+
+## Syntax
+
+```bash
+electron-playwright-cli run-code "async page => {
+  // Your Playwright code here
+  // Access page.context() for browser context operations
+}"
+```
+
+## Geolocation
+
+```bash
+# Grant geolocation permission and set location
+electron-playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
+}"
+
+# Set location to London
+electron-playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
+}"
+
+# Clear geolocation override
+electron-playwright-cli run-code "async page => {
+  await page.context().clearPermissions();
+}"
+```
+
+## Permissions
+
+```bash
+# Grant multiple permissions
+electron-playwright-cli run-code "async page => {
+  await page.context().grantPermissions([
+    'geolocation',
+    'notifications',
+    'camera',
+    'microphone'
+  ]);
+}"
+
+# Grant permissions for specific origin
+electron-playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read'], {
+    origin: 'file://'
+  });
+}"
+```
+
+## Media Emulation
+
+```bash
+# Emulate dark color scheme
+electron-playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+}"
+
+# Emulate light color scheme
+electron-playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'light' });
+}"
+
+# Emulate reduced motion
+electron-playwright-cli run-code "async page => {
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+}"
+
+# Emulate print media
+electron-playwright-cli run-code "async page => {
+  await page.emulateMedia({ media: 'print' });
+}"
+```
+
+## Wait Strategies
+
+```bash
+# Wait for network idle
+electron-playwright-cli run-code "async page => {
+  await page.waitForLoadState('networkidle');
+}"
+
+# Wait for specific element
+electron-playwright-cli run-code "async page => {
+  await page.waitForSelector('.loading', { state: 'hidden' });
+}"
+
+# Wait for function to return true
+electron-playwright-cli run-code "async page => {
+  await page.waitForFunction(() => window.appReady === true);
+}"
+
+# Wait with timeout
+electron-playwright-cli run-code "async page => {
+  await page.waitForSelector('.result', { timeout: 10000 });
+}"
+```
+
+## Frames and Iframes
+
+```bash
+# Work with iframe
+electron-playwright-cli run-code "async page => {
+  const frame = page.locator('iframe#my-iframe').contentFrame();
+  await frame.locator('button').click();
+}"
+
+# Get all frames
+electron-playwright-cli run-code "async page => {
+  const frames = page.frames();
+  return frames.map(f => f.url());
+}"
+```
+
+## File Downloads
+
+```bash
+# Handle file download
+electron-playwright-cli run-code "async page => {
+  const [download] = await Promise.all([
+    page.waitForEvent('download'),
+    page.click('a.download-link')
+  ]);
+  await download.saveAs('./downloaded-file.pdf');
+  return download.suggestedFilename();
+}"
+```
+
+## Clipboard
+
+```bash
+# Read clipboard (requires permission)
+electron-playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read']);
+  return await page.evaluate(() => navigator.clipboard.readText());
+}"
+
+# Write to clipboard
+electron-playwright-cli run-code "async page => {
+  await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!');
+}"
+```
+
+## Page Information
+
+```bash
+# Get page title
+electron-playwright-cli run-code "async page => {
+  return await page.title();
+}"
+
+# Get current URL
+electron-playwright-cli run-code "async page => {
+  return page.url();
+}"
+
+# Get page content
+electron-playwright-cli run-code "async page => {
+  return await page.content();
+}"
+
+# Get viewport size
+electron-playwright-cli run-code "async page => {
+  return page.viewportSize();
+}"
+```
+
+## JavaScript Execution
+
+```bash
+# Execute JavaScript and return result
+electron-playwright-cli run-code "async page => {
+  return await page.evaluate(() => {
+    return {
+      userAgent: navigator.userAgent,
+      language: navigator.language,
+      cookiesEnabled: navigator.cookieEnabled
+    };
+  });
+}"
+
+# Pass arguments to evaluate
+electron-playwright-cli run-code "async page => {
+  const multiplier = 5;
+  return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);
+}"
+```
+
+## Error Handling
+
+```bash
+# Try-catch in run-code
+electron-playwright-cli run-code "async page => {
+  try {
+    await page.click('.maybe-missing', { timeout: 1000 });
+    return 'clicked';
+  } catch (e) {
+    return 'element not found';
+  }
+}"
+```
+
+## Complex Workflows
+
+```bash
+# Save app state
+electron-playwright-cli run-code "async page => {
+  await page.fill('input[name=email]', 'user@example.com');
+  await page.fill('input[name=password]', 'secret');
+  await page.click('button[type=submit]');
+  await page.waitForSelector('.dashboard');
+  await page.context().storageState({ path: 'auth.json' });
+  return 'Login successful';
+}"
+
+# Extract data from a list
+electron-playwright-cli run-code "async page => {
+  const items = await page.locator('.item').allTextContents();
+  return items;
+}"
+```

package/skills/playwright-cli/references/session-management.md

@@ -0,0 +1,145 @@
+# Session Management
+
+Run multiple isolated Electron app sessions concurrently with state persistence.
+
+## Named Sessions
+
+Use `-s` flag to isolate Electron app instances:
+
+```bash
+# Session 1: Main app interaction
+electron-playwright-cli -s=main snapshot
+
+# Session 2: Separate instance (independent cookies, storage)
+electron-playwright-cli -s=secondary snapshot
+
+# Commands are isolated by session
+electron-playwright-cli -s=main fill e1 "user@example.com"
+electron-playwright-cli -s=secondary click e3
+```
+
+## Session Isolation Properties
+
+Each session has independent:
+- Cookies
+- LocalStorage / SessionStorage
+- IndexedDB
+- Cache
+- Open windows
+
+## Session Commands
+
+```bash
+# List all sessions
+electron-playwright-cli list
+
+# Stop a session (close the Electron app)
+electron-playwright-cli close                # stop the default session
+electron-playwright-cli -s=mysession close   # stop a named session
+
+# Stop all sessions
+electron-playwright-cli close-all
+
+# Forcefully kill all daemon processes (for stale/zombie processes)
+electron-playwright-cli kill-all
+
+# Delete session user data (profile directory)
+electron-playwright-cli delete-data                # delete default session data
+electron-playwright-cli -s=mysession delete-data   # delete named session data
+```
+
+## Environment Variable
+
+Set a default session name via environment variable:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION="mysession"
+electron-playwright-cli snapshot  # Uses "mysession" automatically
+```
+
+## Common Patterns
+
+### Multiple App Instances
+
+```bash
+# Launch two instances of your Electron app
+electron-playwright-cli -s=instance1 snapshot
+electron-playwright-cli -s=instance2 snapshot
+
+# Interact with each independently
+electron-playwright-cli -s=instance1 fill e1 "user-a@example.com"
+electron-playwright-cli -s=instance2 fill e1 "user-b@example.com"
+
+# Compare screenshots
+electron-playwright-cli -s=instance1 screenshot --filename=instance1.png
+electron-playwright-cli -s=instance2 screenshot --filename=instance2.png
+
+# Cleanup
+electron-playwright-cli close-all
+```
+
+### Testing Different App States
+
+```bash
+# Test with different configurations or data
+electron-playwright-cli -s=fresh snapshot
+electron-playwright-cli -s=with-data snapshot
+
+# Take screenshots for comparison
+electron-playwright-cli -s=fresh screenshot
+electron-playwright-cli -s=with-data screenshot
+```
+
+## Default Session
+
+When `-s` is omitted, commands use the default session:
+
+```bash
+# These use the same default session
+electron-playwright-cli snapshot
+electron-playwright-cli click e3
+electron-playwright-cli close  # Stops the default session
+```
+
+## Session Configuration
+
+Configure a session with a specific config file:
+
+```bash
+# Use a custom config file
+electron-playwright-cli --config=.playwright/my-cli.json snapshot
+```
+
+## Best Practices
+
+### 1. Name Sessions Semantically
+
+```bash
+# GOOD: Clear purpose
+electron-playwright-cli -s=login-test snapshot
+electron-playwright-cli -s=settings-test snapshot
+
+# AVOID: Generic names
+electron-playwright-cli -s=s1 snapshot
+```
+
+### 2. Always Clean Up
+
+```bash
+# Stop sessions when done
+electron-playwright-cli -s=login-test close
+electron-playwright-cli -s=settings-test close
+
+# Or stop all at once
+electron-playwright-cli close-all
+
+# If sessions become unresponsive or zombie processes remain
+electron-playwright-cli kill-all
+```
+
+### 3. Delete Stale Session Data
+
+```bash
+# Remove old session data to free disk space
+electron-playwright-cli -s=oldsession delete-data
+```

package/skills/playwright-cli/references/storage-state.md

@@ -0,0 +1,270 @@
+# Storage Management
+
+Manage cookies, localStorage, sessionStorage, and storage state in your Electron app.
+
+## Storage State
+
+Save and restore complete app state including cookies and storage.
+
+### Save Storage State
+
+```bash
+# Save to auto-generated filename (storage-state-{timestamp}.json)
+electron-playwright-cli state-save
+
+# Save to specific filename
+electron-playwright-cli state-save my-state.json
+```
+
+### Restore Storage State
+
+```bash
+# Load storage state from file
+electron-playwright-cli state-load my-state.json
+
+# Reload the app to apply
+electron-playwright-cli reload
+```
+
+### Storage State File Format
+
+The saved file contains:
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123",
+      "domain": "example.com",
+      "path": "/",
+      "expires": 1735689600,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "theme", "value": "dark" },
+        { "name": "user_id", "value": "12345" }
+      ]
+    }
+  ]
+}
+```
+
+## Cookies
+
+### List All Cookies
+
+```bash
+electron-playwright-cli cookie-list
+```
+
+### Filter Cookies by Domain
+
+```bash
+electron-playwright-cli cookie-list --domain=example.com
+```
+
+### Filter Cookies by Path
+
+```bash
+electron-playwright-cli cookie-list --path=/api
+```
+
+### Get Specific Cookie
+
+```bash
+electron-playwright-cli cookie-get session_id
+```
+
+### Set a Cookie
+
+```bash
+# Basic cookie
+electron-playwright-cli cookie-set session abc123
+
+# Cookie with options
+electron-playwright-cli cookie-set session abc123 --domain=example.com --path=/ --httpOnly --secure --sameSite=Lax
+
+# Cookie with expiration (Unix timestamp)
+electron-playwright-cli cookie-set remember_me token123 --expires=1735689600
+```
+
+### Delete a Cookie
+
+```bash
+electron-playwright-cli cookie-delete session_id
+```
+
+### Clear All Cookies
+
+```bash
+electron-playwright-cli cookie-clear
+```
+
+### Advanced: Multiple Cookies or Custom Options
+
+For complex scenarios like adding multiple cookies at once, use `run-code`:
+
+```bash
+electron-playwright-cli run-code "async page => {
+  await page.context().addCookies([
+    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
+    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
+  ]);
+}"
+```
+
+## Local Storage
+
+### List All localStorage Items
+
+```bash
+electron-playwright-cli localstorage-list
+```
+
+### Get Single Value
+
+```bash
+electron-playwright-cli localstorage-get token
+```
+
+### Set Value
+
+```bash
+electron-playwright-cli localstorage-set theme dark
+```
+
+### Set JSON Value
+
+```bash
+electron-playwright-cli localstorage-set user_settings '{"theme":"dark","language":"en"}'
+```
+
+### Delete Single Item
+
+```bash
+electron-playwright-cli localstorage-delete token
+```
+
+### Clear All localStorage
+
+```bash
+electron-playwright-cli localstorage-clear
+```
+
+### Advanced: Multiple Operations
+
+For complex scenarios like setting multiple values at once, use `run-code`:
+
+```bash
+electron-playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    localStorage.setItem('token', 'jwt_abc123');
+    localStorage.setItem('user_id', '12345');
+    localStorage.setItem('expires_at', Date.now() + 3600000);
+  });
+}"
+```
+
+## Session Storage
+
+### List All sessionStorage Items
+
+```bash
+electron-playwright-cli sessionstorage-list
+```
+
+### Get Single Value
+
+```bash
+electron-playwright-cli sessionstorage-get form_data
+```
+
+### Set Value
+
+```bash
+electron-playwright-cli sessionstorage-set step 3
+```
+
+### Delete Single Item
+
+```bash
+electron-playwright-cli sessionstorage-delete step
+```
+
+### Clear sessionStorage
+
+```bash
+electron-playwright-cli sessionstorage-clear
+```
+
+## IndexedDB
+
+### List Databases
+
+```bash
+electron-playwright-cli run-code "async page => {
+  return await page.evaluate(async () => {
+    const databases = await indexedDB.databases();
+    return databases;
+  });
+}"
+```
+
+### Delete Database
+
+```bash
+electron-playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    indexedDB.deleteDatabase('myDatabase');
+  });
+}"
+```
+
+## Common Patterns
+
+### Save and Restore App State
+
+```bash
+# Step 1: Set up the app state
+electron-playwright-cli snapshot
+electron-playwright-cli fill e1 "user@example.com"
+electron-playwright-cli fill e2 "password123"
+electron-playwright-cli click e3
+
+# Save the state
+electron-playwright-cli state-save app-state.json
+
+# Step 2: Later, restore state and skip setup
+electron-playwright-cli state-load app-state.json
+electron-playwright-cli reload
+# App state is restored!
+```
+
+### Inspect and Modify Storage
+
+```bash
+# Check current storage
+electron-playwright-cli cookie-list
+electron-playwright-cli localstorage-list
+
+# Modify values
+electron-playwright-cli localstorage-set theme dark
+electron-playwright-cli cookie-set debug true
+
+# Reload to see effect
+electron-playwright-cli reload
+```
+
+## Security Notes
+
+- Never commit storage state files containing auth tokens
+- Add `*.auth-state.json` to `.gitignore`
+- Delete state files after automation completes
+- Use environment variables for sensitive data

package/skills/playwright-cli/references/test-generation.md

@@ -0,0 +1,88 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with your Electron app.
+
+## How It Works
+
+Every action you perform with `electron-playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Take a snapshot to see elements
+electron-playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+electron-playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+electron-playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+electron-playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test for your Electron app:
+
+```typescript
+import { test, expect, _electron as electron } from '@playwright/test';
+
+test('login flow', async () => {
+  const electronApp = await electron.launch({ args: ['path/to/main.js'] });
+  const page = await electronApp.firstWindow();
+
+  // Generated code from electron-playwright-cli session:
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page.getByText('Dashboard')).toBeVisible();
+
+  await electronApp.close();
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the app structure before recording actions:
+
+```bash
+electron-playwright-cli snapshot
+# Review the element structure
+electron-playwright-cli click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test:
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertion
+await expect(page.getByText('Success')).toBeVisible();
+```