Playwright Skill

1---
2name: playwright-skill
3description: Complete browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login flows, check links, automate any browser task. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing.
4---
5 
6**IMPORTANT - Path Resolution:**
7This skill can be installed in different locations (plugin system, manual installation, global, or project-specific). Before executing any commands, determine the skill directory based on where you loaded this SKILL.md file, and use that path in all commands below. Replace `$SKILL_DIR` with the actual discovered path.
8 
9Common installation paths:
10 
11- Plugin system: `~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill`
12- Manual global: `~/.claude/skills/playwright-skill`
13- Project-specific: `<project>/.claude/skills/playwright-skill`
14 
15# Playwright Browser Automation
16 
17General-purpose browser automation skill. I'll write custom Playwright code for any automation task you request and execute it via the universal executor.
18 
19**CRITICAL WORKFLOW - Follow these steps in order:**
20 
211. **Auto-detect dev servers** - For localhost testing, ALWAYS run server detection FIRST:
22 
23   ```bash
24   cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(servers => console.log(JSON.stringify(servers)))"
25   ```
26 
27   - If **1 server found**: Use it automatically, inform user
28   - If **multiple servers found**: Ask user which one to test
29   - If **no servers found**: Ask for URL or offer to help start dev server
30 
312. **Write scripts to /tmp** - NEVER write test files to skill directory; always use `/tmp/playwright-test-*.js`
32 
333. **Use visible browser by default** - Always use `headless: false` unless user specifically requests headless mode
34 
354. **Parameterize URLs** - Always make URLs configurable via environment variable or constant at top of script
36 
37## How It Works
38 
391. You describe what you want to test/automate
402. I auto-detect running dev servers (or ask for URL if testing external site)
413. I write custom Playwright code in `/tmp/playwright-test-*.js` (won't clutter your project)
424. I execute it via: `cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js`
435. Results displayed in real-time, browser window visible for debugging
446. Test files auto-cleaned from /tmp by your OS
45 
46## Setup (First Time)
47 
48```bash
49cd $SKILL_DIR
50npm run setup
51```
52 
53This installs Playwright and Chromium browser. Only needed once.
54 
55## Execution Pattern
56 
57**Step 1: Detect dev servers (for localhost testing)**
58 
59```bash
60cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(s => console.log(JSON.stringify(s)))"
61```
62 
63**Step 2: Write test script to /tmp with URL parameter**
64 
65```javascript
66// /tmp/playwright-test-page.js
67const { chromium } = require('playwright');
68 
69// Parameterized URL (detected or user-provided)
70const TARGET_URL = 'http://localhost:3001'; // <-- Auto-detected or from user
71 
72(async () => {
73  const browser = await chromium.launch({ headless: false });
74  const page = await browser.newPage();
75 
76  await page.goto(TARGET_URL);
77  console.log('Page loaded:', await page.title());
78 
79  await page.screenshot({ path: '/tmp/screenshot.png', fullPage: true });
80  console.log('📸 Screenshot saved to /tmp/screenshot.png');
81 
82  await browser.close();
83})();
84```
85 
86**Step 3: Execute from skill directory**
87 
88```bash
89cd $SKILL_DIR && node run.js /tmp/playwright-test-page.js
90```
91 
92## Common Patterns
93 
94### Test a Page (Multiple Viewports)
95 
96```javascript
97// /tmp/playwright-test-responsive.js
98const { chromium } = require('playwright');
99 
100const TARGET_URL = 'http://localhost:3001'; // Auto-detected
101 
102(async () => {
103  const browser = await chromium.launch({ headless: false, slowMo: 100 });
104  const page = await browser.newPage();
105 
106  // Desktop test
107  await page.setViewportSize({ width: 1920, height: 1080 });
108  await page.goto(TARGET_URL);
109  console.log('Desktop - Title:', await page.title());
110  await page.screenshot({ path: '/tmp/desktop.png', fullPage: true });
111 
112  // Mobile test
113  await page.setViewportSize({ width: 375, height: 667 });
114  await page.screenshot({ path: '/tmp/mobile.png', fullPage: true });
115 
116  await browser.close();
117})();
118```
119 
120### Test Login Flow
121 
122```javascript
123// /tmp/playwright-test-login.js
124const { chromium } = require('playwright');
125 
126const TARGET_URL = 'http://localhost:3001'; // Auto-detected
127 
128(async () => {
129  const browser = await chromium.launch({ headless: false });
130  const page = await browser.newPage();
131 
132  await page.goto(`${TARGET_URL}/login`);
133 
134  await page.fill('input[name="email"]', 'test@example.com');
135  await page.fill('input[name="password"]', 'password123');
136  await page.click('button[type="submit"]');
137 
138  // Wait for redirect
139  await page.waitForURL('**/dashboard');
140  console.log('✅ Login successful, redirected to dashboard');
141 
142  await browser.close();
143})();
144```
145 
146### Fill and Submit Form
147 
148```javascript
149// /tmp/playwright-test-form.js
150const { chromium } = require('playwright');
151 
152const TARGET_URL = 'http://localhost:3001'; // Auto-detected
153 
154(async () => {
155  const browser = await chromium.launch({ headless: false, slowMo: 50 });
156  const page = await browser.newPage();
157 
158  await page.goto(`${TARGET_URL}/contact`);
159 
160  await page.fill('input[name="name"]', 'John Doe');
161  await page.fill('input[name="email"]', 'john@example.com');
162  await page.fill('textarea[name="message"]', 'Test message');
163  await page.click('button[type="submit"]');
164 
165  // Verify submission
166  await page.waitForSelector('.success-message');
167  console.log('✅ Form submitted successfully');
168 
169  await browser.close();
170})();
171```
172 
173### Check for Broken Links
174 
175```javascript
176const { chromium } = require('playwright');
177 
178(async () => {
179  const browser = await chromium.launch({ headless: false });
180  const page = await browser.newPage();
181 
182  await page.goto('http://localhost:3000');
183 
184  const links = await page.locator('a[href^="http"]').all();
185  const results = { working: 0, broken: [] };
186 
187  for (const link of links) {
188    const href = await link.getAttribute('href');
189    try {
190      const response = await page.request.head(href);
191      if (response.ok()) {
192        results.working++;
193      } else {
194        results.broken.push({ url: href, status: response.status() });
195      }
196    } catch (e) {
197      results.broken.push({ url: href, error: e.message });
198    }
199  }
200 
201  console.log(`✅ Working links: ${results.working}`);
202  console.log(`❌ Broken links:`, results.broken);
203 
204  await browser.close();
205})();
206```
207 
208### Take Screenshot with Error Handling
209 
210```javascript
211const { chromium } = require('playwright');
212 
213(async () => {
214  const browser = await chromium.launch({ headless: false });
215  const page = await browser.newPage();
216 
217  try {
218    await page.goto('http://localhost:3000', {
219      waitUntil: 'networkidle',
220      timeout: 10000,
221    });
222 
223    await page.screenshot({
224      path: '/tmp/screenshot.png',
225      fullPage: true,
226    });
227 
228    console.log('📸 Screenshot saved to /tmp/screenshot.png');
229  } catch (error) {
230    console.error('❌ Error:', error.message);
231  } finally {
232    await browser.close();
233  }
234})();
235```
236 
237### Test Responsive Design
238 
239```javascript
240// /tmp/playwright-test-responsive-full.js
241const { chromium } = require('playwright');
242 
243const TARGET_URL = 'http://localhost:3001'; // Auto-detected
244 
245(async () => {
246  const browser = await chromium.launch({ headless: false });
247  const page = await browser.newPage();
248 
249  const viewports = [
250    { name: 'Desktop', width: 1920, height: 1080 },
251    { name: 'Tablet', width: 768, height: 1024 },
252    { name: 'Mobile', width: 375, height: 667 },
253  ];
254 
255  for (const viewport of viewports) {
256    console.log(
257      `Testing ${viewport.name} (${viewport.width}x${viewport.height})`,
258    );
259 
260    await page.setViewportSize({
261      width: viewport.width,
262      height: viewport.height,
263    });
264 
265    await page.goto(TARGET_URL);
266    await page.waitForTimeout(1000);
267 
268    await page.screenshot({
269      path: `/tmp/${viewport.name.toLowerCase()}.png`,
270      fullPage: true,
271    });
272  }
273 
274  console.log('✅ All viewports tested');
275  await browser.close();
276})();
277```
278 
279## Inline Execution (Simple Tasks)
280 
281For quick one-off tasks, you can execute code inline without creating files:
282 
283```bash
284# Take a quick screenshot
285cd $SKILL_DIR && node run.js "
286const browser = await chromium.launch({ headless: false });
287const page = await browser.newPage();
288await page.goto('http://localhost:3001');
289await page.screenshot({ path: '/tmp/quick-screenshot.png', fullPage: true });
290console.log('Screenshot saved');
291await browser.close();
292"
293```
294 
295**When to use inline vs files:**
296 
297- **Inline**: Quick one-off tasks (screenshot, check if element exists, get page title)
298- **Files**: Complex tests, responsive design checks, anything user might want to re-run
299 
300## Available Helpers
301 
302Optional utility functions in `lib/helpers.js`:
303 
304```javascript
305const helpers = require('./lib/helpers');
306 
307// Detect running dev servers (CRITICAL - use this first!)
308const servers = await helpers.detectDevServers();
309console.log('Found servers:', servers);
310 
311// Safe click with retry
312await helpers.safeClick(page, 'button.submit', { retries: 3 });
313 
314// Safe type with clear
315await helpers.safeType(page, '#username', 'testuser');
316 
317// Take timestamped screenshot
318await helpers.takeScreenshot(page, 'test-result');
319 
320// Handle cookie banners
321await helpers.handleCookieBanner(page);
322 
323// Extract table data
324const data = await helpers.extractTableData(page, 'table.results');
325```
326 
327See `lib/helpers.js` for full list.
328 
329## Custom HTTP Headers
330 
331Configure custom headers for all HTTP requests via environment variables. Useful for:
332 
333- Identifying automated traffic to your backend
334- Getting LLM-optimized responses (e.g., plain text errors instead of styled HTML)
335- Adding authentication tokens globally
336 
337### Configuration
338 
339**Single header (common case):**
340 
341```bash
342PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
343  cd $SKILL_DIR && node run.js /tmp/my-script.js
344```
345 
346**Multiple headers (JSON format):**
347 
348```bash
349PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
350  cd $SKILL_DIR && node run.js /tmp/my-script.js
351```
352 
353### How It Works
354 
355Headers are automatically applied when using `helpers.createContext()`:
356 
357```javascript
358const context = await helpers.createContext(browser);
359const page = await context.newPage();
360// All requests from this page include your custom headers
361```
362 
363For scripts using raw Playwright API, use the injected `getContextOptionsWithHeaders()`:
364 
365```javascript
366const context = await browser.newContext(
367  getContextOptionsWithHeaders({ viewport: { width: 1920, height: 1080 } }),
368);
369```
370 
371## Advanced Usage
372 
373For comprehensive Playwright API documentation, see [API_REFERENCE.md](API_REFERENCE.md):
374 
375- Selectors & Locators best practices
376- Network interception & API mocking
377- Authentication & session management
378- Visual regression testing
379- Mobile device emulation
380- Performance testing
381- Debugging techniques
382- CI/CD integration
383 
384## Tips
385 
386- **CRITICAL: Detect servers FIRST** - Always run `detectDevServers()` before writing test code for localhost testing
387- **Custom headers** - Use `PW_HEADER_NAME`/`PW_HEADER_VALUE` env vars to identify automated traffic to your backend
388- **Use /tmp for test files** - Write to `/tmp/playwright-test-*.js`, never to skill directory or user's project
389- **Parameterize URLs** - Put detected/provided URL in a `TARGET_URL` constant at the top of every script
390- **DEFAULT: Visible browser** - Always use `headless: false` unless user explicitly asks for headless mode
391- **Headless mode** - Only use `headless: true` when user specifically requests "headless" or "background" execution
392- **Slow down:** Use `slowMo: 100` to make actions visible and easier to follow
393- **Wait strategies:** Use `waitForURL`, `waitForSelector`, `waitForLoadState` instead of fixed timeouts
394- **Error handling:** Always use try-catch for robust automation
395- **Console output:** Use `console.log()` to track progress and show what's happening
396 
397## Troubleshooting
398 
399**Playwright not installed:**
400 
401```bash
402cd $SKILL_DIR && npm run setup
403```
404 
405**Module not found:**
406Ensure running from skill directory via `run.js` wrapper
407 
408**Browser doesn't open:**
409Check `headless: false` and ensure display available
410 
411**Element not found:**
412Add wait: `await page.waitForSelector('.element', { timeout: 10000 })`
413 
414## Example Usage
415 
416```
417User: "Test if the marketing page looks good"
418 
419Claude: I'll test the marketing page across multiple viewports. Let me first detect running servers...
420[Runs: detectDevServers()]
421[Output: Found server on port 3001]
422I found your dev server running on http://localhost:3001
423 
424[Writes custom automation script to /tmp/playwright-test-marketing.js with URL parameterized]
425[Runs: cd $SKILL_DIR && node run.js /tmp/playwright-test-marketing.js]
426[Shows results with screenshots from /tmp/]
427```
428 
429```
430User: "Check if login redirects correctly"
431 
432Claude: I'll test the login flow. First, let me check for running servers...
433[Runs: detectDevServers()]
434[Output: Found servers on ports 3000 and 3001]
435I found 2 dev servers. Which one should I test?
436- http://localhost:3000
437- http://localhost:3001
438 
439User: "Use 3001"
440 
441[Writes login automation to /tmp/playwright-test-login.js]
442[Runs: cd $SKILL_DIR && node run.js /tmp/playwright-test-login.js]
443[Reports: ✅ Login successful, redirected to /dashboard]
444```
445 
446## Notes
447 
448- Each automation is custom-written for your specific request
449- Not limited to pre-built scripts - any browser task possible
450- Auto-detects running dev servers to eliminate hardcoded URLs
451- Test scripts written to `/tmp` for automatic cleanup (no clutter)
452- Code executes reliably with proper module resolution via `run.js`
453- Progressive disclosure - API_REFERENCE.md loaded only when advanced features needed
454