Playwright CLI

Playwright CLI

Use Playwright's CLI to visually verify web pages, take screenshots, and debug UI issues — all from the terminal without writing test files. For complex interactions (click, scroll, type), use inline Playwright scripts.

For the full flag/option reference, see REFERENCE.md.

Prerequisites

Installed as a dev dependency with Chromium browser:

bun add -d playwright
npx playwright install chromium

Quick reference

Typical workflow

1. Start the dev server (check package.json scripts for the right command)
2. Take a screenshot to verify:

npx playwright screenshot --wait-for-timeout 3000 http://localhost:3000 .agents/.tmp/screenshot.png

3. Read the screenshot image to inspect the result
4. If something looks wrong, iterate on the code and re-screenshot

Advanced: interaction scripts

The CLI screenshot command cannot click, scroll, or type. For interactions, write a short inline script using Playwright as a library.

Important: Use node (not bun) for Playwright scripts — Bun has known compatibility issues with chromium.launch().

Click an element, then screenshot

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('http://localhost:3000');
  await page.locator('button.play').click();
  await page.waitForTimeout(1000);
  await page.screenshot({ path: '.agents/.tmp/after-click.png' });
  await browser.close();
})();
"

Scroll, then screenshot

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('http://localhost:3000');
  await page.evaluate(() => window.scrollBy(0, 800));
  await page.waitForTimeout(500);
  await page.screenshot({ path: '.agents/.tmp/scrolled.png' });
  await browser.close();
})();
"

Screenshot a specific element

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('http://localhost:3000');
  await page.locator('.video-preview').screenshot({ path: '.agents/.tmp/element.png' });
  await browser.close();
})();
"

Fill a form and submit

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('http://localhost:3000');
  await page.locator('#search').fill('test query');
  await page.locator('button[type=submit]').click();
  await page.waitForTimeout(1000);
  await page.screenshot({ path: '.agents/.tmp/search-results.png' });
  await browser.close();
})();
"

Custom viewport + device emulation in scripts

node -e "
const { chromium, devices } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext({ ...devices['iPhone 14'] });
  const page = await context.newPage();
  await page.goto('http://localhost:3000');
  await page.screenshot({ path: '.agents/.tmp/mobile.png' });
  await browser.close();
})();
"

Mobile device interactions

The CLI --device flag emulates viewport, user agent, and pixel ratio, but not touch. For touch-enabled mobile testing, use scripts with hasTouch: true.

Mobile context with touch (tap, swipe)

node -e "
const { chromium, devices } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext({
    ...devices['iPhone 14'],
    hasTouch: true,
  });
  const page = await context.newPage();
  await page.goto('http://localhost:3000');

  // Tap an element (touch equivalent of click)
  await page.tap('#menu-button');
  await page.waitForTimeout(500);
  await page.screenshot({ path: '.agents/.tmp/after-tap.png' });
  await browser.close();
})();
"

Key differences from desktop

Swipe gesture (pan)

node -e "
const { chromium, devices } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext({ ...devices['Pixel 7'], hasTouch: true });
  const page = await context.newPage();
  await page.goto('http://localhost:3000');

  // Swipe up on an element
  const el = page.locator('.scrollable');
  const box = await el.boundingBox();
  const cx = box.x + box.width / 2;
  const cy = box.y + box.height / 2;
  const touches = [{ identifier: 0, clientX: cx, clientY: cy }];
  await el.dispatchEvent('touchstart', { touches, changedTouches: touches, targetTouches: touches });
  for (let i = 1; i <= 5; i++) {
    const moved = [{ identifier: 0, clientX: cx, clientY: cy - i * 60 }];
    await el.dispatchEvent('touchmove', { touches: moved, changedTouches: moved, targetTouches: moved });
  }
  await el.dispatchEvent('touchend', { touches: [], changedTouches: [], targetTouches: [] });

  await page.waitForTimeout(500);
  await page.screenshot({ path: '.agents/.tmp/after-swipe.png' });
  await browser.close();
})();
"

Note: page.tap() requires hasTouch: true in the browser context — it will throw otherwise. The Touchscreen class natively supports only tap; swipe, pinch, and other multi-touch gestures require manual dispatchEvent calls with touch point coordinates. See REFERENCE.md for the full touch API.

Capturing browser console output

Essential for debugging. Attach a console event listener before navigating — otherwise you miss logs emitted during page load.

Print all console messages

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  // Attach BEFORE navigating
  page.on('console', msg => {
    console.log(\`[\${msg.type()}] \${msg.text()}\`);
  });

  await page.goto('http://localhost:3000');
  await page.waitForTimeout(3000);
  await browser.close();
})();
"

Filter errors and warnings only

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  page.on('console', msg => {
    if (['error', 'warning'].includes(msg.type())) {
      console.log(\`[\${msg.type().toUpperCase()}] \${msg.text()}\`);
      const loc = msg.location();
      if (loc.url) console.log(\`  at \${loc.url}:\${loc.lineNumber}\`);
    }
  });

  // Also capture uncaught page errors
  page.on('pageerror', err => {
    console.error('[PAGE ERROR]', err.message);
  });

  await page.goto('http://localhost:3000');
  await page.waitForTimeout(3000);
  await browser.close();
})();
"

Collect logs and screenshot together

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  const logs = [];

  page.on('console', msg => {
    logs.push({ type: msg.type(), text: msg.text() });
  });
  page.on('pageerror', err => {
    logs.push({ type: 'pageerror', text: err.message });
  });

  await page.goto('http://localhost:3000');
  await page.waitForTimeout(3000);
  await page.screenshot({ path: '.agents/.tmp/debug.png' });

  console.log(JSON.stringify(logs, null, 2));
  await browser.close();
})();
"

Console message properties

Page-level error events

Common Playwright API methods (for scripts)

Tips

• Always use --wait-for-timeout when the page has async loading (Studio, SPAs)
• Screenshots go to the workspace root by default — use .agents/.tmp/ to avoid committing them
• The --device flag is useful for testing responsive layouts (e.g., YouTube Shorts at 9:16)
• Chromium is the default browser; use -b firefox or -b webkit if needed
• Runs headless by default — no display needed
• Use --viewport-size "1080,1920" for custom dimensions (e.g., vertical video)
• Use --save-har <file> to capture network activity for debugging API calls
• Use --ignore-https-errors for self-signed certs in development
• For authenticated pages, use --save-storage / --load-storage to persist and reuse session state
• For interaction scripts, always use node not bun (Bun has compatibility issues with chromium.launch())

Converted and distributed by TomeVault — claim your Tome and manage your conversions.