IMPORTANT - Path Resolution: This skill is installed via the plugin system. 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.

Expected plugin path: ~/.claude/plugins/marketplaces/inkeep-team-skills/plugins/eng/skills/browser

Playwright Browser Automation

General-purpose browser automation skill. Write custom Playwright code for any automation task and execute it via the universal executor.

CRITICAL WORKFLOW - Follow these steps in order:

Start a session - If you expect to run more than one script (debugging, iterating, multi-step flows), start a persistent browser session FIRST. This is the default mode for all interactive work:

cd $SKILL_DIR && node run.js --session start

Scripts auto-detect the session and connect via WebSocket (~50ms) instead of launching a new browser (~2-3s). Login state, cookies, and localStorage persist between runs. Skip this step only for true one-off scripts or CI/CD environments.

Auto-detect dev servers - For localhost testing, run server detection:

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

• If 1 server found: Use it automatically, inform user

• If multiple servers found: Ask user which one to test

• If no servers found: Ask for URL or offer to help start dev server

Write scripts to /tmp - NEVER write test files to skill directory; always use /tmp/playwright-test-*.js

Parameterize URLs - Always make URLs configurable via environment variable or constant at top of script

Stop session when done - Clean up the persistent browser when the task is complete:

cd $SKILL_DIR && node run.js --session stop

Sessions also auto-stop after 10 minutes of inactivity.

How It Works

• You describe what you want to test/automate

• Start a session (--session start ) — browser stays warm for all subsequent scripts

• Auto-detect running dev servers (or ask for URL if testing external site)

• Write custom Playwright code in /tmp/playwright-test-*.js (won't clutter your project)

• Execute it via: cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js — auto-connects to session

• Results displayed in real-time; login state and pages persist between runs

• Stop session when done (--session stop ); test files auto-cleaned from /tmp by OS

Local browser mode (user's Chrome)

When the user asks you to interact with their actual browser — using their auth, cookies, or extensions — use the local browser connector instead of headless Playwright.

When to use: User directs you to do something in their browser on their behalf, or you need their authenticated session. Only available on the user's local machine (not Docker/sandbox).

Prerequisites: Chrome running + Playwright MCP Bridge extension installed.

Execute: cd $SKILL_DIR && node scripts/connect-local.js /tmp/my-script.js or cd $SKILL_DIR && node run.js --connect /tmp/my-script.js

Load: references/local-browser.md for routing guidance, limitations, and examples.

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: true }); 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: true }); 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: true }); 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(); })();

Test Authenticated Pages

Login once, save the session, and reuse it across multiple test runs. Avoids re-logging in every time.

Step 1: Login and save auth state (run once)

// /tmp/playwright-auth-save.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001/login';

(async () => { const browser = await chromium.launch({ headless: true }); const context = await helpers.createContext(browser); const page = await context.newPage();

await page.goto(TARGET_URL); await helpers.authenticate(page, { username: 'admin@example.com', password: 'password123' });

// Save session for reuse const saved = await helpers.saveAuthState(context); console.log('Auth state saved:', saved.path); console.log( ${saved.cookies} cookies, ${saved.origins} origins);

// For Firebase/Supabase/modern auth that stores tokens in IndexedDB: // const saved = await helpers.saveAuthState(context, '/tmp/auth.json', { indexedDB: true });

await browser.close(); })();

Step 2: Reuse saved auth in subsequent tests

// /tmp/playwright-test-dashboard.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001/dashboard';

(async () => { const browser = await chromium.launch({ headless: true });

// Load saved auth — skips login entirely const context = await helpers.loadAuthState(browser); const page = await context.newPage();

await page.goto(TARGET_URL); console.log('Page title:', await page.title()); // You're now on the authenticated dashboard await page.screenshot({ path: '/tmp/dashboard.png', fullPage: true });

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: true }); 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(); })();

Network Request Inspection

// /tmp/playwright-test-network.js const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage();

// Capture all API requests const apiRequests = []; page.on('request', request => { if (request.url().includes('/api/')) { apiRequests.push({ method: request.method(), url: request.url(), headers: request.headers() }); } });

page.on('response', response => { if (response.url().includes('/api/')) { console.log(${response.status()} ${response.url()}); } });

await page.goto(TARGET_URL); await page.waitForLoadState('networkidle');

console.log('API requests captured:', JSON.stringify(apiRequests, null, 2));

await browser.close(); })();

JavaScript Injection

// /tmp/playwright-test-js-inject.js const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage();

await page.goto(TARGET_URL);

// Inject and execute JavaScript const result = await page.evaluate(() => { return { title: document.title, links: document.querySelectorAll('a').length, meta: Array.from(document.querySelectorAll('meta')).map(m => ({ name: m.getAttribute('name'), content: m.getAttribute('content') })).filter(m => m.name), localStorage: Object.keys(window.localStorage), cookies: document.cookie }; });

console.log('Page analysis:', JSON.stringify(result, null, 2));

await browser.close(); })();

Check for Broken Links

const { chromium } = require('playwright');

(async () => { const browser = await chromium.launch({ headless: true }); 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: true }); 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: true }); 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(); })();

Monitor Console Errors During a Flow

Use when verifying a UI flow doesn't produce silent JS errors.

// /tmp/playwright-test-console.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage();

// Start capturing BEFORE navigation const consoleLogs = helpers.startConsoleCapture(page);

await page.goto(TARGET_URL); await page.waitForLoadState('networkidle');

// Interact with the page await page.click('button.submit').catch(() => {}); await page.waitForTimeout(1000);

// Check for errors const errors = helpers.getConsoleErrors(consoleLogs); if (errors.length > 0) { console.log(FAIL: ${errors.length} console error(s):); errors.forEach(e => console.log( [${e.type}] ${e.text})); } else { console.log('PASS: No console errors'); }

// Optionally filter for specific logs const apiLogs = helpers.getConsoleLogs(consoleLogs, /api|fetch/i); console.log(API-related logs: ${apiLogs.length});

await browser.close(); })();

Verify Network Requests During UI Flow

Use when checking that the right API calls fire with the right status codes.

// /tmp/playwright-test-network-verify.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage();

// Capture only API requests const network = helpers.startNetworkCapture(page, '/api/');

await page.goto(${TARGET_URL}/dashboard); await page.waitForLoadState('networkidle');

// Check for failed API calls const failed = helpers.getFailedRequests(network); if (failed.length > 0) { console.log(FAIL: ${failed.length} failed API request(s):); failed.forEach(r => console.log( ${r.method} ${r.url} -> ${r.status || r.failure})); } else { console.log('PASS: All API requests succeeded'); }

// Review all captured requests const all = helpers.getCapturedRequests(network); console.log(Total API requests: ${all.length}); all.forEach(r => console.log( ${r.status} ${r.method} ${r.url}));

await browser.close(); })();

Record Video of a Flow

Use when you need a recording of multi-step browser interaction.

// /tmp/playwright-test-video.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const context = await helpers.createVideoContext(browser, { outputDir: '/tmp/playwright-videos' }); const page = await context.newPage();

await page.goto(TARGET_URL); await page.click('nav a:first-child'); await page.waitForTimeout(1000); await page.click('button.submit').catch(() => {}); await page.waitForTimeout(1000);

// Video is saved when page closes const videoPath = await page.video().path(); await page.close(); await context.close();

console.log(Video saved: ${videoPath}); await browser.close(); })();

Inspect Browser State After Mutation

Use when verifying that a UI action correctly persisted data.

// /tmp/playwright-test-state.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const context = await browser.newContext(); const page = await context.newPage();

await page.goto(TARGET_URL);

// Check state before action const storageBefore = await helpers.getLocalStorage(page); console.log('localStorage before:', JSON.stringify(storageBefore));

const cookies = await helpers.getCookies(context); console.log('Cookies:', cookies.map(c => ${c.name}=${c.value}));

// Perform some action that should change state await page.click('button.save-preferences').catch(() => {}); await page.waitForTimeout(500);

// Check state after action const storageAfter = await helpers.getLocalStorage(page); console.log('localStorage after:', JSON.stringify(storageAfter));

// Clean up for next test await helpers.clearAllStorage(page);

await browser.close(); })();

Discover Page Structure

Use when you don't know a page's DOM structure — third-party sites, authenticated dashboards, or unfamiliar UIs. Get the ARIA snapshot to find the right selectors before writing interactions.

Returns yaml (raw ARIA snapshot string preserving hierarchy), tree (parsed nodes with suggested selectors), and summary (counts by role type).

// /tmp/playwright-test-discover.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const context = await helpers.createContext(browser); const page = await context.newPage(); await page.goto(TARGET_URL, { waitUntil: 'networkidle' });

// Get full page structure const structure = await helpers.getPageStructure(page); console.log('Page:', structure.title); console.log('Elements:', JSON.stringify(structure.summary));

// Raw YAML preserves nesting — useful for understanding page hierarchy console.log('ARIA snapshot:\n', structure.yaml);

// Parsed tree has suggested selectors for each element console.log('Interactive elements:'); structure.tree.filter(el => ['button','link','textbox','checkbox','combobox'].includes(el.role) ).forEach(el => console.log( ${el.role}: "${el.name}" → ${el.selector}));

// Scope to a specific section const formElements = await helpers.getPageStructure(page, { interactiveOnly: true, root: 'form' }); console.log('Form inputs:', JSON.stringify(formElements.tree, null, 2));

await browser.close(); })();

Visual Inspection (look at a page)

Use when you need to see what a page looks like — before taking final screenshots, during exploration, after an action, or to verify a UI state. This is for your own understanding, not for output.

The pattern: take a temporary screenshot, then read it.

// /tmp/playwright-test-inspect.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const context = await helpers.createContext(browser); const page = await context.newPage(); await page.goto(${TARGET_URL}/dashboard, { waitUntil: 'networkidle' });

// Take a quick screenshot to see the page await page.screenshot({ path: '/tmp/inspect.png' });

// Inspect a specific section const section = page.locator('.settings-panel'); await section.screenshot({ path: '/tmp/inspect-section.png' });

await browser.close(); })();

After running the script, read the image file to see what the page looks like:

Read tool → /tmp/inspect.png

Claude renders PNG files visually, so you can see the actual page layout, content, popups, loading states, and any issues.

When to use this vs getPageStructure() :

Need Use

Find selectors, understand DOM hierarchy getPageStructure() (text — faster, more precise)

See what the page actually looks like Visual inspection (screenshot — layout, colors, overlays, rendering)

Both — unfamiliar page Do both: structure first for selectors, then screenshot to see the visual result

Tip: For iterative work (exploring a page, debugging a pre-script), use a persistent session so you don't relaunch the browser each time. The screenshot file gets overwritten on each run.

Capture Screenshots for Documentation

Use when writing docs, help articles, or PR screenshots that need consistent, high-quality images of the running UI.

// /tmp/playwright-test-doc-screenshot.js const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const context = await browser.newContext({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 2, // Retina clarity }); const page = await context.newPage();

await page.goto(${TARGET_URL}/settings); await page.waitForLoadState('networkidle');

// Crop to the relevant section — avoid full-page captures with empty space const section = page.locator('.api-keys-section'); await section.screenshot({ path: '/tmp/doc-settings-api-keys.png', type: 'png', });

// Full-page fallback when you need the whole view await page.screenshot({ path: '/tmp/doc-settings-full.png', type: 'png', fullPage: false, // Viewport-only — keep it tight });

console.log('Doc screenshots saved to /tmp/doc-*.png'); await browser.close(); })();

Key settings for doc screenshots:

• viewport: { width: 1280, height: 720 } — standard docs width

• deviceScaleFactor: 2 — retina resolution for sharp text

• type: 'png' — lossless for UI screenshots

• Use element.screenshot() to crop to a specific panel instead of full-page

• Target <200KB per image — crop aggressively

Media Asset Pipeline

Choose the right preset and conversion for your target. Presets set viewport + DPR automatically — no manual config needed.

Target Preset Output Max size Why

Docs site screenshot docs-retina

2560×1440 PNG <500 KB Retina-sharp for Next.js Image

GitHub PR screenshot pr-standard

1280×720 PNG <200 KB Crisp at GitHub's 894px display width. Use uploadToBunnyStorage() for CDN URLs

GitHub PR GIF gif-compact

800×450 animated GIF <10 MB DPR 1 — GIF's 256-color palette is the bottleneck, not pixel density. Use uploadToBunnyStorage() for CDN URLs

Video (internal or customer-facing) video

2560×1440 WebM → Bunny or Vimeo — uploadToBunny() or uploadToVimeo() — both transcode to ABR. DPR 1 is correct for video (DPR only affects CSS rendering, not video output resolution)

Capture a docs-quality screenshot with a preset:

// /tmp/playwright-test-preset-screenshot.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true });

// Preset sets viewport 1280x720 + DPR 2 → 2560x1440 output const context = await helpers.createPresetContext(browser, 'docs-retina'); const page = await context.newPage();

await page.goto(${TARGET_URL}/settings); await page.waitForLoadState('networkidle');

// Element-level crop for tight framing const section = page.locator('.api-keys-section'); await section.screenshot({ path: '/tmp/doc-api-keys.png', type: 'png' });

console.log('Docs screenshot: 2560x1440 Retina PNG'); await browser.close(); })();

Create a step-by-step GIF for a PR:

// /tmp/playwright-test-pr-gif.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); // gif-compact: 800x450 @ DPR 1 — optimized for GitHub's 10MB limit const context = await helpers.createPresetContext(browser, 'gif-compact'); const page = await context.newPage();

const frames = [];

// Frame 1: Starting state await page.goto(${TARGET_URL}/settings); await page.waitForLoadState('networkidle'); frames.push(await page.screenshot({ type: 'png' }));

// Frame 2: Click action await page.click('button.save'); await page.waitForTimeout(500); frames.push(await page.screenshot({ type: 'png' }));

// Frame 3: Success state await page.waitForSelector('.success-toast'); frames.push(await page.screenshot({ type: 'png' }));

// Assemble GIF — 3 frames at 2fps = 1.5s loop const result = await helpers.screenshotsToGif(frames, '/tmp/pr-demo.gif', { width: 800, height: 450, fps: 2 });

console.log(GIF: ${result.path} (${result.sizeMB} MB, ${result.frames} frames)); await browser.close(); })();

Annotated GIF with click indicators and step labels:

// /tmp/playwright-test-annotated-gif.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const context = await helpers.createPresetContext(browser, 'gif-compact'); const page = await context.newPage();

const frames = []; const annotations = [];

// Frame 1: Navigate to page await page.goto(TARGET_URL); frames.push(await page.screenshot({ type: 'png' })); annotations.push({ label: 'Step 1: Open login page' });

// Frame 2: Click username field await page.click('#username'); frames.push(await page.screenshot({ type: 'png' })); annotations.push({ label: 'Step 2: Click username', click: { x: 640, y: 300 } });

// Frame 3: Type credentials await page.fill('#username', 'admin'); frames.push(await page.screenshot({ type: 'png' })); annotations.push({ label: 'Step 3: Enter username' });

// Frame 4: Click submit await page.click('button[type="submit"]'); frames.push(await page.screenshot({ type: 'png' })); annotations.push({ label: 'Step 4: Submit', click: { x: 640, y: 400 } });

const result = await helpers.screenshotsToGif(frames, '/tmp/login-demo.gif', { width: 800, height: 450, fps: 2, annotations });

console.log(Annotated GIF: ${result.path} (${result.sizeMB} MB, ${result.frames} frames)); await browser.close(); })();

Run Accessibility Audit

Use when checking a page for WCAG violations.

// /tmp/playwright-test-a11y.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage();

await page.goto(TARGET_URL); await page.waitForLoadState('networkidle');

const audit = await helpers.runAccessibilityAudit(page);

console.log(Accessibility audit: ${audit.violationCount} violation(s), ${audit.passes} passes);

if (audit.violationCount > 0) { console.log('\nViolations:'); audit.summary.forEach(v => { console.log( [${v.impact}] ${v.id}: ${v.description} (${v.nodes} element(s))); console.log( Help: ${v.helpUrl}); }); }

// Test keyboard focus order const focusOrder = await helpers.checkFocusOrder(page, [ 'a[href]:first-of-type', 'nav a:nth-child(2)', 'input[type="search"]' ]); focusOrder.forEach(f => { console.log( Tab ${f.step}: expected ${f.expectedSelector} -> ${f.matches ? 'PASS' : 'FAIL'}); });

await browser.close(); })();

Handle Dialogs and Overlays

Use when pages have alert() /confirm() /prompt() dialogs or blocking overlays (cookie banners, modals) that prevent interaction.

// /tmp/playwright-test-dialogs.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage();

// Auto-accept all dialogs (call BEFORE navigating) const dialogLog = helpers.handleDialogs(page);

// Auto-dismiss cookie banners and common overlays await helpers.dismissOverlays(page);

await page.goto(TARGET_URL); await page.click('button.delete'); // triggers confirm()

// Check what dialogs appeared console.log('Dialogs captured:', dialogLog.dialogs.length); dialogLog.dialogs.forEach(d => console.log( ${d.type}: "${d.message}") );

// Custom overlay patterns (beyond the defaults) await helpers.dismissOverlays(page, [ { locator: '.onboarding-modal .close-btn', action: 'click' }, { locator: '.promo-popup', action: 'remove' } // remove from DOM entirely ]);

await browser.close(); })();

Debug with Tracing

Use when a flow fails and you need to understand exactly what happened — DOM state, screenshots, network, and console at each step. Produces a .zip viewable in Playwright Trace Viewer.

// /tmp/playwright-test-trace.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001';

(async () => { const browser = await chromium.launch({ headless: true }); const context = await helpers.createContext(browser);

// Start tracing BEFORE creating pages await helpers.startTracing(context);

const page = await context.newPage(); await page.goto(TARGET_URL); await page.click('button.submit'); await page.waitForSelector('.result');

// Stop and save trace const trace = await helpers.stopTracing(context, '/tmp/trace.zip'); console.log(Trace saved: ${trace.path}); console.log('View with: npx playwright show-trace /tmp/trace.zip');

await browser.close(); })();

Generate PDF

Use when you need a PDF export of a page — documentation, reports, or print-ready output. Chromium headless only.

// /tmp/playwright-test-pdf.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001/report';

(async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage(); await page.goto(TARGET_URL, { waitUntil: 'networkidle' });

// Basic PDF const result = await helpers.generatePdf(page, '/tmp/report.pdf'); console.log('PDF saved:', result.path);

// Accessible PDF with bookmarks await helpers.generatePdf(page, '/tmp/report-accessible.pdf', { tagged: true, // accessible/tagged PDF outline: true, // document outline from headings format: 'Letter', margin: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' } });

await browser.close(); })();

Download Files

Use when a button or link triggers a file download and you need to save or inspect the file.

// /tmp/playwright-test-download.js const { chromium } = require('playwright'); const helpers = require('./lib/helpers');

const TARGET_URL = 'http://localhost:3001/exports';

(async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage(); await page.goto(TARGET_URL);

// Trigger download and save const file = await helpers.waitForDownload( page, () => page.click('#export-csv'), // action that triggers the download '/tmp/export.csv' // optional save path ); console.log(Downloaded: ${file.suggestedFilename} → ${file.path});

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: true }); 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

Session Mode (Persistent Browser) — Default

Session mode is the recommended default for all interactive browser automation. Start a session before running scripts — every subsequent script connects in ~50ms instead of launching a new browser (~2-3s), and login state persists automatically.

Use session mode for: All interactive work — debugging, testing, iterative flows, auth-heavy pages, video recording, multi-step automation. This covers the vast majority of agent use cases.

Use headless (no session) only for: True one-off scripts, CI/CD pipelines, or environments where a persistent daemon is inappropriate.

Quick start

Start a session (do this first)

cd $SKILL_DIR && node run.js --session start

Run scripts — they auto-connect to the session

cd $SKILL_DIR && node run.js /tmp/my-script.js

Cookies, localStorage, and current URL all persist between runs

Check session status

cd $SKILL_DIR && node run.js --session status

Stop when done

cd $SKILL_DIR && node run.js --session stop

How it works

• --session start launches a headless Chromium via Playwright's launchServer()

• The browser runs as a background daemon (detached process)

• Session info is written to /tmp/playwright-session.json

• When you run a script, run.js auto-detects the session and connects via WebSocket

• Your code gets pre-wired browser , context , and page variables

• On script exit, cookies/localStorage/current URL are saved to /tmp/playwright-session-state.json

• Next script reconnects and restores state — same auth, same URL, ready to continue

What your code gets

In session mode, your code has these variables pre-defined:

Variable Description

browser

Connected browser instance (persists across runs)

context

Browser context with restored cookies/localStorage from previous run

page

Page navigated to the last URL from previous run (or blank on first run)

saveState

Call before exiting to persist cookies/localStorage/URL (called automatically by wrapper)

helpers

All helper functions from lib/helpers

chromium , devices

Playwright exports (for creating additional contexts)

Session mode vs headless (no session)

Session mode (default) Headless — no session

Browser launch Once (on --session start ) Every script execution

Startup time ~50ms (WebSocket connect) ~2-3s (browser launch)

Login state Persists automatically (cookies/localStorage saved between runs) Lost each run (use saveAuthState /loadAuthState )

Current URL Restored from previous run Starts at about:blank

page.route()

Full support Full support

Token cost Minimal (no launch/close boilerplate) Higher (launch + close in every script)

Best for All interactive work — debugging, testing, iterating, auth flows CI/CD, isolated tests, one-off scripts

Options

Start with headed browser (visible)

cd $SKILL_DIR && node run.js --session start --headless false

Start with a resolution preset

cd $SKILL_DIR && node run.js --session start --preset video

Auto-cleanup

• Session auto-stops after 10 minutes of inactivity (no scripts run)

• If the session process crashes, the next script detects the stale session and falls back to fresh headless mode

• The session file and state file are cleaned up automatically

Creating fresh contexts in session mode

The default is to reuse the existing context (for state persistence). If you need a clean context:

// Create an isolated context within the session const freshContext = await browser.newContext(); const freshPage = await freshContext.newPage(); await freshPage.goto('https://example.com'); // This context has no cookies/localStorage from previous runs

Available Helpers

All helpers live in lib/helpers.js . Use const helpers = require('./lib/helpers'); in scripts. Organized by what you need to do:

Page Interaction

Helper When to use

helpers.detectDevServers()

CRITICAL — run first for localhost testing. Returns array of detected server URLs.

helpers.createContext(browser, options?)

Create browser context with defaults: viewport 1280x720, locale en-US, timezone America/New_York. Pass { mobile: true } for iPhone UA. Auto-merges env headers.

helpers.waitForPageReady(page, options?)

Smart wait for page load (networkidle by default). Pass { waitForSelector: '.loaded' } for dynamic content.

helpers.retryWithBackoff(fn, maxRetries?, initialDelay?)

Retry an async function with exponential backoff. Default: 3 retries, 1s initial delay.

helpers.safeClick(page, selector, { retries: 3 })

Click elements that may not be immediately visible/clickable. Auto-retries.

helpers.safeType(page, selector, text)

Type into inputs. Clears field first by default.

helpers.extractTexts(page, selector)

Get text from multiple matching elements as array.

helpers.scrollPage(page, 'down', 500)

Scroll page. Directions: 'down' , 'up' , 'top' , 'bottom' .

helpers.handleCookieBanner(page)

Dismiss common cookie consent banners. Run early — clears overlays that block interaction.

helpers.authenticate(page, { username, password })

Login flow with common field selectors. Auto-waits for redirect.

helpers.saveAuthState(context, path?, options?)

Save login session after authenticating. Default path: /tmp/playwright-auth.json . Pass { indexedDB: true } for Firebase/Supabase auth. Reuse with loadAuthState .

helpers.loadAuthState(browser, path?, options?)

Create a context with saved auth state. Skips re-login. Inherits createContext defaults.

helpers.getPageStructure(page, { interactiveOnly, root })

Discover page structure via ARIA snapshot. Returns yaml (raw hierarchy), tree (parsed with selectors), and summary (counts). Use for unfamiliar pages.

helpers.handleDialogs(page, options?)

Auto-handle alert /confirm /prompt dialogs. Call BEFORE navigating. Returns { dialogs } for inspection after.

helpers.dismissOverlays(page, overlays?)

Auto-dismiss cookie banners, modals, and blocking overlays using addLocatorHandler . Pass custom patterns or use defaults.

helpers.extractTableData(page, 'table.results')

Extract structured data from HTML tables (headers + rows).

helpers.takeScreenshot(page, 'name')

Save timestamped screenshot.

Console Monitoring — catch silent JS errors

Helper When to use

helpers.startConsoleCapture(page)

Call BEFORE navigating. Returns a collector that accumulates all console output.

helpers.getConsoleErrors(collector)

Get only error-level messages and uncaught exceptions from collector.

helpers.getConsoleLogs(collector, filter?)

Get all logs, or filter by string/RegExp/function.

Lightweight alternative (Playwright v1.56+): For quick checks without a collector, use page.consoleMessages() and page.pageErrors() after the fact — they return all messages/errors since page creation.

Network Inspection — verify API calls during UI flows

Helper When to use

helpers.startNetworkCapture(page, '/api/')

Call BEFORE navigating. Captures request/response pairs. Optional URL filter.

helpers.getFailedRequests(collector)

Get 4xx, 5xx, and connection failures from collector.

helpers.getCapturedRequests(collector)

Get all captured request/response entries.

helpers.waitForApiResponse(page, '/api/users', { status: 200 })

Wait for a specific API call to complete. Returns { url, status, body, json } .

Lightweight alternative (Playwright v1.56+): page.requests() returns all requests since page creation — useful for quick post-hoc inspection without setting up a collector.

Browser State — inspect storage and cookies

Helper When to use

helpers.getLocalStorage(page)

Get all localStorage entries. Pass a key for a single value.

helpers.getSessionStorage(page)

Get all sessionStorage entries. Pass a key for a single value.

helpers.getCookies(context)

Get all cookies from browser context.

helpers.clearAllStorage(page)

Clear localStorage + sessionStorage + cookies. Use for clean-state testing.

Video Recording — record browser interactions

Helper When to use

helpers.createVideoContext(browser, { outputDir: '/tmp/videos' })

Create a context that records video. Video saved when page/context closes.

helpers.uploadToVimeo(filePath, { name, privacy })

Optional — upload a local video (WebM/MP4) to Vimeo. Only when user asks. Requires VIMEO_CLIENT_ID , VIMEO_CLIENT_SECRET , VIMEO_ACCESS_TOKEN env vars. Returns { videoId, url, embedUrl } .

helpers.uploadToBunny(filePath, { name, collectionId })

Optional — upload a local video (WebM/MP4) to Bunny Stream. For internal videos (team demos, QA recordings). Requires BUNNY_STREAM_API_KEY , BUNNY_STREAM_LIBRARY_ID env vars. VP8 WebM explicitly supported. Returns { videoId, url, embedUrl } .

Image/File Upload — Bunny Edge Storage

Helper When to use

helpers.uploadToBunnyStorage(filePath, remotePath, { region })

Upload any file (PNG, GIF, PDF) to Bunny Edge Storage and get a permanent CDN URL. Use for PR screenshots, annotated images, comparison PNGs. Requires BUNNY_STORAGE_API_KEY , BUNNY_STORAGE_ZONE_NAME , BUNNY_STORAGE_HOSTNAME env vars. Returns { url, storagePath, size } .

Resolution Presets — consistent dimensions per target

Helper When to use

helpers.RESOLUTION_PRESETS

Access preset configs. Keys: docs-retina , pr-standard , gif-compact . Each has viewport and deviceScaleFactor .

helpers.createPresetContext(browser, 'preset')

Create a context with preset viewport + DPR. Replaces manual viewport/DPR config.

Media Conversion — screenshots to GIF

Helper When to use

helpers.screenshotsToGif(frames, path, opts)

Convert PNG buffers to animated GIF. Options: width , height , fps , quality , annotations (per-frame click indicators + labels).

Accessibility — WCAG audits and keyboard navigation

Helper When to use

helpers.runAccessibilityAudit(page)

Inject axe-core and run WCAG 2.0 AA audit. Returns violations with impact/description. Requires internet (CDN).

helpers.checkFocusOrder(page, ['#first', '#second', '#third'])

Tab through elements and verify focus lands on expected selectors in order.

Performance Metrics — measure page speed

Helper When to use

helpers.capturePerformanceMetrics(page)

Capture Navigation Timing (TTFB, DOM interactive) and Web Vitals (FCP, LCP, CLS). Call after page load.

Responsive Screenshots — multi-viewport sweep

Helper When to use

helpers.captureResponsiveScreenshots(page, url)

Screenshot at mobile/tablet/desktop/wide breakpoints. Custom breakpoints and output dir optional.

Network Simulation — test degraded conditions

Helper When to use

helpers.simulateSlowNetwork(page, 500)

Add artificial latency (ms) to all requests.

helpers.simulateOffline(context)

Set browser to offline mode.

helpers.blockResources(page, ['image', 'font'])

Block specific resource types (image, font, stylesheet, script, etc.).

Simulating specific failures: Use route.abort('connectionrefused') for targeted error simulation. Error types: 'connectionrefused' , 'timedout' , 'connectionreset' , 'internetdisconnected' .

Tracing & Debugging

Helper When to use

helpers.startTracing(context, options?)

Start recording a trace (DOM snapshots, screenshots, network). Call before page interactions.

helpers.stopTracing(context, path?)

Stop tracing and save .zip . View with npx playwright show-trace trace.zip .

PDF Generation

Helper When to use

helpers.generatePdf(page, path?, options?)

Generate PDF from current page. Options: format , tagged (accessible), outline (bookmarks), margin . Chromium headless only.

File Downloads

Helper When to use

helpers.waitForDownload(page, triggerAction, savePath?)

Wait for a download triggered by an action, then save it. Returns { path, suggestedFilename, url } .

Layout Inspection — verify element positioning

Helper When to use

helpers.getElementBounds(page, '.selector')

Get bounding box, visibility, viewport presence, and computed styles. Returns null for non-existent selectors, { visible: false } for hidden elements.

Page Structure Internals — parse ARIA snapshots standalone

Helper When to use

helpers.parseAriaSnapshot(yaml)

Parse a Playwright ARIA snapshot YAML string into structured node objects. Each node has role , name , and optional level , checked , disabled , expanded , selected .

helpers.suggestSelector(node)

Generate a getByRole(...) selector string from a parsed ARIA node.

helpers.INTERACTIVE_ROLES

Set of interactive ARIA roles (button, link, textbox, checkbox, radio, combobox, slider, switch, tab, menuitem, searchbox, spinbutton, option).

Local Browser — connect to user's Chrome

These helpers live in lib/local-browser.js . Use const { connectToLocalBrowser, getConnectedPage, extractAuthState } = require('./lib/local-browser'); in scripts. See references/local-browser.md for full docs.

Helper When to use

connectToLocalBrowser(options?)

Connect to user's running Chrome via extension bridge. Returns { browser, context, page, close() } . Requires Playwright MCP Bridge extension. Set PLAYWRIGHT_MCP_EXTENSION_TOKEN env var to bypass the approval dialog.

getConnectedPage(context, url?)

Get the page exposed by the extension and optionally navigate. Note: context.newPage() does NOT work via the extension bridge — use this or the page from connectToLocalBrowser() .

extractAuthState(context, options?)

Extract cookies + localStorage (+ IndexedDB with { indexedDB: true } ) from user's browser. Save to file with { path: '/tmp/auth.json' } for later reuse via helpers.loadAuthState() .

Custom HTTP Headers

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

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:

• Selectors & Locators best practices

• Network interception & API mocking

• Authentication & session management

• Visual regression testing

• Mobile device emulation

• Performance testing

• Debugging techniques

• CI/CD integration

Tips

• 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: Headless browser - Always use headless: true for Docker/CI compatibility

• Headed mode - Use headless: false when user specifically requests visible browser or is debugging locally

• 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

• Docker: The --no-sandbox flag is included by default in helpers for container compatibility

• Time manipulation (Playwright v1.45+): Use page.clock to control time in tests — await page.clock.install() then await page.clock.fastForward('01:00') to advance, or await page.clock.pauseAt(new Date('2025-01-01')) to freeze at a specific moment. Useful for testing timers, countdowns, session expiry, and time-dependent UI.

• WebSocket interception (Playwright v1.48+): Use page.routeWebSocket(url, handler) to mock or monitor WebSocket connections. The handler receives a WebSocketRoute with onMessage() , send() , and close() . Useful for testing real-time features (chat, notifications, live updates) without a running server.

Troubleshooting

Playwright not installed:

cd $SKILL_DIR && npm run setup

Module not found: Ensure running from skill directory via run.js wrapper

Browser doesn't launch in Docker: Ensure --no-sandbox and --disable-setuid-sandbox args are set (included by default in helpers)

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