playwright-skill

1. You describe what you want to test/automate
2. I auto-detect running dev servers (or ask for URL if testing external site)
3. I write custom Playwright code in /tmp/playwright-test-*.js (won't clutter your project)
4. I execute it via: cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js
5. Results displayed in real-time, browser window visible for debugging
6. Test files auto-cleaned from /tmp by your OS

```bash

cd $SKILL_DIR

npm run setup

```

This installs Playwright and Chromium browser. Only needed once.

Step 1: Detect dev servers (for localhost testing)

```bash

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

```javascript

// /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

```bash

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

```

Test a Page (Multiple Viewports)

```javascript

// /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

```javascript

// /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

```javascript

// /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

```javascript

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

```javascript

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

```javascript

// /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();

})();

```

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

```bash

# 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:

• Inline: Quick one-off tasks (screenshot, check if element exists, get page title)
• Files: Complex tests, responsive design checks, anything user might want to re-run

Optional utility functions in lib/helpers.js:

```javascript

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.

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

• Identifying automated traffic to your backend
• Getting LLM-optimized responses (e.g., plain text errors instead of styled HTML)
• Adding authentication tokens globally

Configuration

Single header (common case):

```bash

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):

```bash

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():

```javascript

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():

```javascript

const context = await browser.newContext(

getContextOptionsWithHeaders({ viewport: { width: 1920, height: 1080 } }),

);

```

For comprehensive Playwright API documentation, see [API_REFERENCE.md](API_REFERENCE.md):

• Selectors & Locators best practices
• Network interception & API mocking
• Authentication & session management
• Visual regression testing
• Mobile device emulation
• Performance testing
• Debugging techniques
• CI/CD integration

• CRITICAL: Detect servers FIRST - Always run detectDevServers() before writing test code for localhost testing
• Custom headers - Use PW_HEADER_NAME/PW_HEADER_VALUE env vars to identify automated traffic to your backend
• Use /tmp for test files - Write to /tmp/playwright-test-*.js, never to skill directory or user's project
• Parameterize URLs - Put detected/provided URL in a TARGET_URL constant at the top of every script
• DEFAULT: Visible browser - Always use headless: false unless user explicitly asks for headless mode
• Headless mode - Only use headless: true when user specifically requests "headless" or "background" execution
• Slow down: Use slowMo: 100 to make actions visible and easier to follow
• Wait strategies: Use waitForURL, waitForSelector, waitForLoadState instead of fixed timeouts
• Error handling: Always use try-catch for robust automation
• Console output: Use console.log() to track progress and show what's happening

Playwright not installed:

```bash

cd $SKILL_DIR && npm run setup

```

Module not found:

Ensure running from skill directory via run.js wrapper

Browser doesn't open:

Check headless: false and ensure display available

Element not found:

Add wait: await page.waitForSelector('.element', { timeout: 10000 })

```

User: "Test if the marketing page looks good"

Claude: I'll test the marketing page across multiple viewports. Let me first detect running servers...

[Runs: detectDevServers()]

[Output: Found server on port 3001]

I found your dev server running on http://localhost:3001

[Writes custom automation script to /tmp/playwright-test-marketing.js with URL parameterized]

[Runs: cd $SKILL_DIR && node run.js /tmp/playwright-test-marketing.js]

[Shows results with screenshots from /tmp/]

```

```

User: "Check if login redirects correctly"

Claude: I'll test the login flow. First, let me check for running servers...

[Runs: detectDevServers()]

[Output: Found servers on ports 3000 and 3001]

I found 2 dev servers. Which one should I test?

• http://localhost:3000
• http://localhost:3001

User: "Use 3001"

[Writes login automation to /tmp/playwright-test-login.js]

[Runs: cd $SKILL_DIR && node run.js /tmp/playwright-test-login.js]

[Reports: ✅ Login successful, redirected to /dashboard]

```

• Each automation is custom-written for your specific request
• Not limited to pre-built scripts - any browser task possible
• Auto-detects running dev servers to eliminate hardcoded URLs
• Test scripts written to /tmp for automatic cleanup (no clutter)
• Code executes reliably with proper module resolution via run.js
• Progressive disclosure - API_REFERENCE.md loaded only when advanced features needed