Skip to content

zebbern/claude-code-guide / skills/playwright/playwright-cli

playwright-cli

Unverified

Automates browser interactions for web testing, form filling, screenshots, and data extraction using playwright-cli. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, extract information from web pages, mock network requests, manage browser sessions, or generate test code.

FileKindSize
SKILL.mdskill md9.3 KB
advanced-workflows.mdmarkdown18.3 KB
core-commands.mdmarkdown10.6 KB
device-emulation.mdmarkdown13.1 KB
request-mocking.mdmarkdown10.4 KB
running-custom-code.mdmarkdown14.8 KB
screenshots-and-media.mdmarkdown10.3 KB
session-management.mdmarkdown9.5 KB
storage-and-auth.mdmarkdown11.2 KB
test-generation.mdmarkdown11.1 KB
tracing-and-debugging.mdmarkdown12.1 KB

running-custom-code.md

View on GitHub
# Running Custom Playwright Code

> **When to use**: When CLI commands aren't sufficient — geolocation, permissions, media emulation, waiting strategies, iframe interaction, file downloads, clipboard access, complex multi-step workflows, or any scenario requiring the full Playwright API.
> **Prerequisites**: [core-commands.md](core-commands.md) for basic CLI usage

## Quick Reference

```bash
# Syntax: run-code accepts an async function with page as argument
playwright-cli run-code "async page => {
  // Full Playwright API available here
  // page.context() for browser context operations
  // Return a value to see it in output
  return await page.title();
}"
```

## Geolocation

Override the browser's reported location — essential for testing location-based features like store locators, delivery zones, and weather apps.

```bash
# Grant permission and set location to New York
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 40.7128, longitude: -74.0060 });
}"

# London
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
}"

# San Francisco
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
}"

# Tokyo
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 35.6762, longitude: 139.6503 });
}"

# Update location mid-session (simulates user moving)
playwright-cli run-code "async page => {
  await page.context().setGeolocation({ latitude: 34.0522, longitude: -118.2437 });
}"

# Clear geolocation override
playwright-cli run-code "async page => {
  await page.context().clearPermissions();
}"
```

## Permissions

Control browser permission grants — notifications, camera, microphone, clipboard, etc.

```bash
# Grant multiple permissions
playwright-cli run-code "async page => {
  await page.context().grantPermissions([
    'geolocation',
    'notifications',
    'camera',
    'microphone'
  ]);
}"

# Grant permissions for a specific origin only
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['clipboard-read', 'clipboard-write'], {
    origin: 'https://example.com'
  });
}"

# Revoke all permissions
playwright-cli run-code "async page => {
  await page.context().clearPermissions();
}"
```

Available permissions: `geolocation`, `notifications`, `camera`, `microphone`, `clipboard-read`, `clipboard-write`, `payment-handler`, `midi`, `midi-sysex`, `ambient-light-sensor`, `accelerometer`, `gyroscope`, `magnetometer`, `accessibility-events`, `background-sync`

## Media Emulation

Test how your app behaves under different media conditions — dark mode, reduced motion, print layout.

### Color Scheme

```bash
# Dark mode
playwright-cli run-code "async page => {
  await page.emulateMedia({ colorScheme: 'dark' });
}"

# Light mode
playwright-cli run-code "async page => {
  await page.emulateMedia({ colorScheme: 'light' });
}"

# System preference (no override)
playwright-cli run-code "async page => {
  await page.emulateMedia({ colorScheme: 'no-preference' });
}"
```

### Reduced Motion

```bash
# Simulate prefers-reduced-motion: reduce
playwright-cli run-code "async page => {
  await page.emulateMedia({ reducedMotion: 'reduce' });
}"

# Reset to no preference
playwright-cli run-code "async page => {
  await page.emulateMedia({ reducedMotion: 'no-preference' });
}"
```

### Forced Colors (High Contrast)

```bash
playwright-cli run-code "async page => {
  await page.emulateMedia({ forcedColors: 'active' });
}"
```

### Print Media

```bash
# Emulate print stylesheet (useful before taking PDF)
playwright-cli run-code "async page => {
  await page.emulateMedia({ media: 'print' });
}"

# Reset to screen
playwright-cli run-code "async page => {
  await page.emulateMedia({ media: 'screen' });
}"
```

### Combine Multiple Emulations

```bash
playwright-cli run-code "async page => {
  await page.emulateMedia({
    colorScheme: 'dark',
    reducedMotion: 'reduce',
    forcedColors: 'none'
  });
}"
```

## Locale and Timezone

Override browser locale and timezone to test internationalization:

```bash
# Set locale (affects number formatting, date display, etc.)
playwright-cli run-code "async page => {
  // Locale is set at context creation; for existing context, use evaluate
  return await page.evaluate(() => navigator.language);
}"

# For new contexts, set locale and timezone at open time:
# playwright-cli open --config=locale-config.json
# where locale-config.json contains: { "locale": "de-DE", "timezoneId": "Europe/Berlin" }
```

## Wait Strategies

When the page needs time to load, render, or settle after an action.

### Wait for Load States

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

# Wait for DOM content loaded
playwright-cli run-code "async page => {
  await page.waitForLoadState('domcontentloaded');
}"

# Wait for full load (including images, stylesheets)
playwright-cli run-code "async page => {
  await page.waitForLoadState('load');
}"
```

### Wait for Elements

```bash
# Wait for a loading spinner to disappear
playwright-cli run-code "async page => {
  await page.waitForSelector('.loading-spinner', { state: 'hidden' });
}"

# Wait for content to appear
playwright-cli run-code "async page => {
  await page.waitForSelector('.search-results', { state: 'visible', timeout: 10000 });
}"

# Wait for element to be removed from DOM entirely
playwright-cli run-code "async page => {
  await page.waitForSelector('.skeleton-loader', { state: 'detached' });
}"
```

### Wait for URL Changes

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

playwright-cli run-code "async page => {
  await page.waitForURL(/.*\/order\/\d+/);
}"
```

### Wait for Custom Conditions

```bash
# Wait for a JavaScript variable to be set
playwright-cli run-code "async page => {
  await page.waitForFunction(() => window.appReady === true);
}"

# Wait for specific number of elements
playwright-cli run-code "async page => {
  await page.waitForFunction(() => document.querySelectorAll('.item').length >= 10);
}"

# Wait with polling
playwright-cli run-code "async page => {
  await page.waitForFunction(
    () => document.querySelector('.status')?.textContent === 'Complete',
    { polling: 500, timeout: 30000 }
  );
}"
```

### Wait for Network Requests

```bash
# Wait for a specific API call to complete
playwright-cli run-code "async page => {
  const responsePromise = page.waitForResponse('**/api/users');
  await page.click('button#load-users');
  const response = await responsePromise;
  return { status: response.status(), url: response.url() };
}"

# Wait for a request to be made
playwright-cli run-code "async page => {
  const requestPromise = page.waitForRequest('**/api/submit');
  await page.click('button#submit');
  const request = await requestPromise;
  return request.postDataJSON();
}"
```

## Frames and Iframes

Interact with content inside iframes:

```bash
# Click a button inside an iframe
playwright-cli run-code "async page => {
  const frame = page.locator('iframe#my-iframe').contentFrame();
  await frame.locator('button.submit').click();
}"

# Fill a form inside an iframe
playwright-cli run-code "async page => {
  const frame = page.locator('iframe[name=\"checkout\"]').contentFrame();
  await frame.locator('input[name=\"card-number\"]').fill('4111111111111111');
  await frame.locator('input[name=\"expiry\"]').fill('12/25');
  await frame.locator('input[name=\"cvc\"]').fill('123');
}"

# Get all frame URLs
playwright-cli run-code "async page => {
  const frames = page.frames();
  return frames.map(f => ({ name: f.name(), url: f.url() }));
}"

# Nested iframes
playwright-cli run-code "async page => {
  const outerFrame = page.locator('iframe#outer').contentFrame();
  const innerFrame = outerFrame.locator('iframe#inner').contentFrame();
  await innerFrame.locator('button').click();
}"
```

## File Downloads

```bash
# Trigger download and save the file
playwright-cli run-code "async page => {
  const [download] = await Promise.all([
    page.waitForEvent('download'),
    page.click('a.download-link')
  ]);
  const filename = download.suggestedFilename();
  await download.saveAs('./downloads/' + filename);
  return 'Downloaded: ' + filename;
}"

# Download with custom path
playwright-cli run-code "async page => {
  const [download] = await Promise.all([
    page.waitForEvent('download'),
    page.getByRole('button', { name: 'Export CSV' }).click()
  ]);
  await download.saveAs('/tmp/export.csv');
  return 'Saved to /tmp/export.csv';
}"

# Get download URL without saving
playwright-cli run-code "async page => {
  const [download] = await Promise.all([
    page.waitForEvent('download'),
    page.click('#download-btn')
  ]);
  return download.url();
}"
```

## Clipboard

```bash
# Read clipboard content
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['clipboard-read']);
  return await page.evaluate(() => navigator.clipboard.readText());
}"

# Write to clipboard
playwright-cli run-code "async page => {
  await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!');
}"

# Copy text from an element to clipboard
playwright-cli run-code "async page => {
  const text = await page.locator('.api-key').textContent();
  await page.evaluate(t => navigator.clipboard.writeText(t), text);
  return 'Copied: ' + text;
}"
```

## Page Information

```bash
# Page title
playwright-cli run-code "async page => {
  return await page.title();
}"

# Current URL
playwright-cli run-code "async page => {
  return page.url();
}"

# Full page HTML content
playwright-cli run-code "async page => {
  return await page.content();
}"

# Viewport size
playwright-cli run-code "async page => {
  return page.viewportSize();
}"

# Browser information
playwright-cli run-code "async page => {
  return await page.evaluate(() => ({
    userAgent: navigator.userAgent,
    language: navigator.language,
    languages: navigator.languages,
    cookiesEnabled: navigator.cookieEnabled,
    onLine: navigator.onLine,
    platform: navigator.platform,
    screenSize: { width: screen.width, height: screen.height }
  }));
}"
```

## JavaScript Execution

```bash
# Execute and return result
playwright-cli run-code "async page => {
  return await page.evaluate(() => {
    return {
      title: document.title,
      url: window.location.href,
      elementCount: document.querySelectorAll('*').length,
      scripts: document.querySelectorAll('script').length
    };
  });
}"

# Pass arguments to evaluate
playwright-cli run-code "async page => {
  const selector = '.product-card';
  const count = await page.evaluate(
    sel => document.querySelectorAll(sel).length,
    selector
  );
  return count + ' products found';
}"

# Modify the DOM
playwright-cli run-code "async page => {
  await page.evaluate(() => {
    document.querySelector('.banner')?.remove();
    document.body.style.zoom = '80%';
  });
}"
```

## Error Handling

```bash
# Try-catch for optional elements
playwright-cli run-code "async page => {
  try {
    await page.click('.cookie-consent-accept', { timeout: 2000 });
    return 'Cookie banner dismissed';
  } catch (e) {
    return 'No cookie banner found';
  }
}"

# Retry pattern
playwright-cli run-code "async page => {
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      await page.click('.flaky-button', { timeout: 3000 });
      return 'Clicked on attempt ' + attempt;
    } catch (e) {
      if (attempt === 3) throw e;
      await page.waitForTimeout(1000);
    }
  }
}"
```

## Complex Workflows

### Login and Save Authentication State

```bash
playwright-cli run-code "async page => {
  await page.goto('https://example.com/login');
  await page.fill('input[name=email]', 'user@example.com');
  await page.fill('input[name=password]', 'secret');
  await page.click('button[type=submit]');
  await page.waitForURL('**/dashboard');
  await page.context().storageState({ path: 'auth.json' });
  return 'Login successful, state saved to auth.json';
}"
```

### Scrape Data from Multiple Pages

```bash
playwright-cli run-code "async page => {
  const results = [];
  for (let i = 1; i <= 5; i++) {
    await page.goto(\`https://example.com/products?page=\${i}\`);
    await page.waitForSelector('.product-card');
    const items = await page.locator('.product-card').evaluateAll(cards =>
      cards.map(card => ({
        name: card.querySelector('.title')?.textContent?.trim(),
        price: card.querySelector('.price')?.textContent?.trim(),
        rating: card.querySelector('.rating')?.getAttribute('data-value')
      }))
    );
    results.push(...items);
  }
  return JSON.stringify(results, null, 2);
}"
```

### Fill Multi-Step Form (Wizard)

```bash
playwright-cli run-code "async page => {
  // Step 1: Personal info
  await page.fill('#firstName', 'Jane');
  await page.fill('#lastName', 'Doe');
  await page.fill('#email', 'jane@example.com');
  await page.click('button:text(\"Next\")');

  // Step 2: Address
  await page.waitForSelector('#street');
  await page.fill('#street', '123 Main St');
  await page.fill('#city', 'Springfield');
  await page.selectOption('#state', 'IL');
  await page.fill('#zip', '62701');
  await page.click('button:text(\"Next\")');

  // Step 3: Confirm and submit
  await page.waitForSelector('.review-summary');
  await page.click('button:text(\"Submit\")');
  await page.waitForURL('**/confirmation');

  return 'Form submitted successfully';
}"
```

### Infinite Scroll Data Extraction

```bash
playwright-cli run-code "async page => {
  await page.goto('https://example.com/feed');
  const items = [];

  while (items.length < 50) {
    const newItems = await page.locator('.feed-item').evaluateAll(
      els => els.map(el => el.textContent.trim())
    );
    items.push(...newItems.filter(item => !items.includes(item)));

    await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
    await page.waitForTimeout(1000);

    // Check if we've reached the end
    const hasMore = await page.locator('.load-more').isVisible().catch(() => false);
    if (!hasMore && newItems.length === items.length) break;
  }

  return items.slice(0, 50);
}"
```

## Tips

- **Return values**: Always `return` data from `run-code` to see it in the CLI output
- **`page.context()`**: Access browser context for permissions, cookies, storage, geolocation
- **Error messages**: Playwright errors include element snapshots and call logs — read them carefully
- **Combine with CLI**: Use `run-code` for setup (permissions, routes) then CLI commands for interaction
- **Async/await**: All Playwright operations are async — always `await` them
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall