Playwright

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:

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

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

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