Playwright — Browser Screenshots & Interaction

Use Playwright to open a real browser, navigate to URLs, take screenshots, and interact with pages. This is the go-to approach for visual verification of any web content — Penpot designs, local dev servers, production sites, etc.

Setup

Playwright is installed at /Users/espen/node_modules/playwright.

When writing scripts, always require from the absolute path:

const { chromium } = require('/Users/espen/node_modules/playwright');

Quick Screenshot

Write a .cjs script to /tmp/, run it with node, then read the resulting PNG.

const { chromium } = require('/Users/espen/node_modules/playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded', timeout: 30000 });
    await page.waitForTimeout(3000);
    await page.screenshot({ path: '/tmp/screenshot.png' });
  } finally {
    await browser.close();
  }
})();

node /tmp/screenshot.cjs

Then view it:

read /tmp/screenshot.png

Key Rules

Always use headless: false

Many SPAs (Penpot, React apps, ClojureScript apps) fail or render blank in headless mode. Always launch headed:

chromium.launch({ headless: false })

Always use CommonJS (.cjs)

Write scripts as .cjs files with require(). ESM imports fail because Playwright isn't in the local node_modules:

// ✅ Works
const { chromium } = require('/Users/espen/node_modules/playwright');

// ❌ Fails — "Cannot find package 'playwright'"
import { chromium } from 'playwright';

Wait for SPA rendering

SPAs need time to hydrate after the initial HTML loads. Always add a wait:

Site type	Wait time
Static HTML	1-2 seconds
Simple SPA (React, Svelte)	3-4 seconds
Complex SPA (Penpot, Figma)	6-8 seconds

await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
await page.waitForTimeout(6000); // adjust per site type

Use waitUntil: 'domcontentloaded' instead of 'networkidle' — network-idle can time out on SPAs that keep WebSocket connections open.

Write to /tmp

Always save screenshots and scripts to /tmp/ to avoid polluting the workspace:

await page.screenshot({ path: '/tmp/my-screenshot.png' });

Viewport & Device Emulation

Custom viewport

const context = await browser.newContext({ viewport: { width: 1400, height: 1000 } });
const page = await context.newPage();

Mobile device

const { devices } = require('/Users/espen/node_modules/playwright');
const iPhone = devices['iPhone 15'];
const context = await browser.newContext({ ...iPhone });

Common viewports

Use case	Width × Height
Desktop (default)	1400 × 1000
Mobile	390 × 844
Tablet	768 × 1024
Wide	1920 × 1080

Interactions

Click, type, scroll

await page.click('button.submit');
await page.fill('input[name="email"]', 'test@example.com');
await page.keyboard.press('Enter');
await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));

Hover states

await page.hover('.card');
await page.waitForTimeout(500);
await page.screenshot({ path: '/tmp/card-hover.png' });

Wait for specific elements

await page.waitForSelector('.loaded-content', { timeout: 10000 });

Multi-Page Screenshots

Loop over multiple URLs and save each:

const pages_to_capture = [
  { url: 'https://example.com/', name: 'home' },
  { url: 'https://example.com/about', name: 'about' },
];

for (const p of pages_to_capture) {
  await page.goto(p.url, { waitUntil: 'domcontentloaded', timeout: 30000 });
  await page.waitForTimeout(3000);
  await page.screenshot({ path: `/tmp/${p.name}.png` });
}

Setting Cookies / Auth

For pages that require authentication:

const context = await browser.newContext({ viewport: { width: 1400, height: 1000 } });
await context.addCookies([{
  name: 'auth-token',
  value: 'your-token-here',
  domain: 'example.com',
  path: '/',
}]);
const page = await context.newPage();

Troubleshooting

Symptom	Cause	Fix
"Internal Error" / blank page	Headless mode	Use headless: false
"Cannot find package"	ESM import or wrong cwd	Use absolute require() path, .cjs extension
Black / empty screenshot	SPA not rendered yet	Increase waitForTimeout
Timeout on goto	networkidle on WebSocket app	Switch to domcontentloaded
Wrong page content	Auth required	Set cookies or use share link
Blurry screenshots	Low DPR	Set deviceScaleFactor: 2 in context

Full Example — Screenshot with Console Debugging

When a page isn't rendering as expected, capture console output:

const { chromium } = require('/Users/espen/node_modules/playwright');

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

    page.on('console', msg => {
      if (msg.type() === 'error') console.log('CONSOLE ERROR:', msg.text());
    });
    page.on('pageerror', err => console.log('PAGE ERROR:', err.message));

    await page.goto('https://example.com', { waitUntil: 'domcontentloaded', timeout: 30000 });
    await page.waitForTimeout(4000);

    const title = await page.title();
    console.log('Title:', title);

    await page.screenshot({ path: '/tmp/debug.png' });
  } finally {
    await browser.close();
  }
})();