playwright-skill

Setup (First Time)

cd $SKILL_DIR
npm run setup

This installs Playwright and Chromium browser. Only needed once.

Execution Pattern

Step 1: Detect dev servers (for localhost testing)

cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(s => console.log(JSON.stringify(s)))"

Step 2: Write test script to /tmp with URL parameter

// /tmp/playwright-test-page.js
const { chromium } = require('playwright');
// Parameterized URL (detected or user-provided)
const TARGET_URL = 'http://localhost:3001'; // <-- Auto-detected or from user
(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto(TARGET_URL);
  console.log('Page loaded:', await page.title());
  await page.screenshot({ path: '/tmp/screenshot.png', fullPage: true });
  console.log('📸 Screenshot saved to /tmp/screenshot.png');
  await browser.close();
})();

Step 3: Execute from skill directory

cd $SKILL_DIR && node run.js /tmp/playwright-test-page.js

Common Patterns

Test a Page (Multiple Viewports)

// /tmp/playwright-test-responsive.js
const { chromium } = require('playwright');
const TARGET_URL = 'http://localhost:3001'; // Auto-detected
(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 100 });
  const page = await browser.newPage();
  // Desktop test
  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.goto(TARGET_URL);
  console.log('Desktop - Title:', await page.title());
  await page.screenshot({ path: '/tmp/desktop.png', fullPage: true });
  // Mobile test
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({ path: '/tmp/mobile.png', fullPage: true });
  await browser.close();
})();

Test Login Flow

// /tmp/playwright-test-login.js
const { chromium } = require('playwright');
const TARGET_URL = 'http://localhost:3001'; // Auto-detected
(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto(${TARGET_URL}/login);
  await page.fill('input[name="email"]', 'test@example.com');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');
  // Wait for redirect
  await page.waitForURL('/dashboard');
  console.log('✅ Login successful, redirected to dashboard');
  await browser.close();
})();

Fill and Submit Form

// /tmp/playwright-test-form.js
const { chromium } = require('playwright');
const TARGET_URL = 'http://localhost:3001'; // Auto-detected
(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 50 });
  const page = await browser.newPage();
  await page.goto(${TARGET_URL}/contact);
  await page.fill('input[name="name"]', 'John Doe');
  await page.fill('input[name="email"]', 'john@example.com');
  await page.fill('textarea[name="message"]', 'Test message');
  await page.click('button[type="submit"]');
  // Verify submission
  await page.waitForSelector('.success-message');
  console.log('✅ Form submitted successfully');
  await browser.close();
})();

Check for Broken Links

const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto('http://localhost:3000');
  const links = await page.locator('a[href^="http"]').all();
  const results = { working: 0, broken: [] };
  for (const link of links) {
    const href = await link.getAttribute('href');
    try {
      const response = await page.request.head(href);
      if (response.ok()) {
        results.working++;
      } else {
        results.broken.push({ url: href, status: response.status() });
      }
    } catch (e) {
      results.broken.push({ url: href, error: e.message });
    }
  }
  console.log(✅ Working links: ${results.working});
  console.log(❌ Broken links:, results.broken);
  await browser.close();
})();

Take Screenshot with Error Handling

const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  try {
    await page.goto('http://localhost:3000', {
      waitUntil: 'networkidle',
      timeout: 10000,
    });
    await page.screenshot({
      path: '/tmp/screenshot.png',
      fullPage: true,
    });
    console.log('📸 Screenshot saved to /tmp/screenshot.png');
  } catch (error) {
    console.error('❌ Error:', error.message);
  } finally {
    await browser.close();
  }
})();

Test Responsive Design

// /tmp/playwright-test-responsive-full.js
const { chromium } = require('playwright');
const TARGET_URL = 'http://localhost:3001'; // Auto-detected
(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  const viewports = [
    { name: 'Desktop', width: 1920, height: 1080 },
    { name: 'Tablet', width: 768, height: 1024 },
    { name: 'Mobile', width: 375, height: 667 },
  ];
  for (const viewport of viewports) {
    console.log(
      Testing ${viewport.name} (${viewport.width}x${viewport.height}),
    );
    await page.setViewportSize({
      width: viewport.width,
      height: viewport.height,
    });
    await page.goto(TARGET_URL);
    await page.waitForTimeout(1000);
    await page.screenshot({
      path: /tmp/${viewport.name.toLowerCase()}.png,
      fullPage: true,
    });
  }
  console.log('✅ All viewports tested');
  await browser.close();
})();

Inline Execution (Simple Tasks)

For quick one-off tasks, you can execute code inline without creating files:

# Take a quick screenshot
cd $SKILL_DIR && node run.js "
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('http://localhost:3001');
await page.screenshot({ path: '/tmp/quick-screenshot.png', fullPage: true });
console.log('Screenshot saved');
await browser.close();
"

When to use inline vs files:

Available Helpers

Optional utility functions in lib/helpers.js:

const helpers = require('./lib/helpers');
// Detect running dev servers (CRITICAL - use this first!)
const servers = await helpers.detectDevServers();
console.log('Found servers:', servers);
// Safe click with retry
await helpers.safeClick(page, 'button.submit', { retries: 3 });
// Safe type with clear
await helpers.safeType(page, '#username', 'testuser');
// Take timestamped screenshot
await helpers.takeScreenshot(page, 'test-result');
// Handle cookie banners
await helpers.handleCookieBanner(page);
// Extract table data
const data = await helpers.extractTableData(page, 'table.results');

See lib/helpers.js for full list.

Custom HTTP Headers

Configure custom headers for all HTTP requests via environment variables. Useful for:

Single header (common case):

PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
  cd $SKILL_DIR && node run.js /tmp/my-script.js

Multiple headers (JSON format):

PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
  cd $SKILL_DIR && node run.js /tmp/my-script.js

How It Works

Headers are automatically applied when using helpers.createContext():

const context = await helpers.createContext(browser);
const page = await context.newPage();
// All requests from this page include your custom headers

For scripts using raw Playwright API, use the injected getContextOptionsWithHeaders():

const context = await browser.newContext(
  getContextOptionsWithHeaders({ viewport: { width: 1920, height: 1080 } }),
);

Advanced Usage

For comprehensive Playwright API documentation, see API_REFERENCE.md: