Playwright Core

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to import `playwright-core` using CommonJS `require()` syntax in an ES Module context, or generally in newer Node.js versions where Playwright is published as an ESM module.
  fix Change your import statements from `const { chromium } = require('playwright-core');` to `import { chromium } from 'playwright-core';`. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions.

• Error: Browser type 'chromium' is not found. Close all running browsers and try again.

  cause The required browser binaries (e.g., Chromium) have not been installed or are corrupted for `playwright-core`.
  fix Run `npx playwright install chromium` to download and install the Chromium browser binaries. For all browsers, use `npx playwright install`.

• Error: Node.js v16.x is not supported. Please upgrade to Node.js v18 or higher.

  cause The installed Node.js version is below the minimum requirement for the Playwright Core package.
  fix Upgrade your Node.js environment to version 18 or newer. Use NVM (`nvm install 18 && nvm use 18`) or update through your system's package manager.

• TimeoutError: locator.click: Timeout 30000ms exceeded.

  cause The specified element could not be found, was not visible, or was not actionable within the default timeout period.
  fix Ensure the selector is correct and the element is present and visible on the page. Use `page.waitForSelector()` with appropriate state options (`'visible'`, `'attached'`, `'loaded'`) before interacting, or increase the locator's timeout: `page.locator('selector').click({ timeout: 60000 })`.

Warnings

• breaking Playwright Core dropped support for Chromium extension manifest v2. Projects relying on these older manifest versions for browser extensions will need to update their extensions or browser versions.
  Fix: Migrate Chromium extensions to Manifest V3. Consult Chromium documentation for migration guides.
• gotcha The `playwright-core` package provides only the low-level browser automation API. It does not include the Playwright Test runner or the pre-built browser binaries (Chromium, Firefox, WebKit). Attempting to use `playwright-core` without explicitly installing or managing browser binaries will lead to errors.
  Fix: For a complete testing solution including test runner and auto-downloaded browsers, install `playwright` (`npm i -D playwright`). If you only need `playwright-core`, ensure you manually install browser binaries using `npx playwright install` or `npx playwright install chromium`.
• breaking Playwright Core requires Node.js version 18 or higher. Running with older Node.js versions will result in execution errors.
  Fix: Upgrade your Node.js environment to version 18 or newer. Use a Node Version Manager (NVM) for easy switching (e.g., `nvm install 18 && nvm use 18`).
• gotcha The console window when spawning browser processes on Windows was reverted from being hidden, which previously caused regressions in features like `codegen`, `--ui`, and `show` commands.
  Fix: This fix is included in `v1.59.1`. If encountering issues with `codegen`, `--ui`, or `show` commands on Windows with older versions, update to `v1.59.1` or newer. The console window will now be visible during browser spawning on Windows.

Install

• npm install playwright-core npm
• yarn add playwright-core yarn
• pnpm add playwright-core pnpm

Imports

• chromium
  wrong:

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

  correct:

  import { chromium } from 'playwright-core';

  For modern Node.js environments and Playwright versions >= 1.20, ES Modules (`import`) are the primary consumption method. CommonJS (`require`) may lead to `ERR_REQUIRE_ESM`.
• Browser, Page
  wrong:

  import { Browser, Page } from 'playwright-core';

  correct:

  import type { Browser, Page } from 'playwright-core';

  When only importing types for TypeScript, use `import type` to prevent bundling unnecessary runtime code and ensure cleaner type-checking.
• firefox, webkit

  import { firefox, webkit } from 'playwright-core';

  Similar to `chromium`, these are named exports for launching specific browser types directly from the core library.

Quickstart

Demonstrates launching a headless Chromium browser, navigating to multiple pages, taking a screenshot, interacting with an element, and verifying the URL after navigation using Playwright Core.

import { chromium, type Browser, type Page } from 'playwright-core';
import * as fs from 'fs';

async function runBrowserAutomation() {
  let browser: Browser | undefined;
  try {
    // Launch a headless Chromium browser
    browser = await chromium.launch({ headless: true });
    const page: Page = await browser.newPage();

    // Navigate to a website
    await page.goto('https://www.example.com');
    console.log('Navigated to example.com');

    // Take a screenshot and save it
    const screenshotPath = 'example_screenshot.png';
    await page.screenshot({ path: screenshotPath });
    console.log(`Screenshot saved to ${screenshotPath}`);

    // Get and print the page title
    const title = await page.title();
    console.log(`Page title: "${title}"`);

    // Navigate to another page and interact with an element
    await page.goto('https://playwright.dev');
    const getStartedButton = page.locator('a', { hasText: 'Get started' }).first();
    await getStartedButton.click();
    console.log('Clicked "Get started" on Playwright.dev');

    // Wait for navigation to complete and verify the URL
    await page.waitForURL('**/docs/intro');
    console.log(`Current URL after click: ${page.url()}`);

  } catch (error) {
    console.error('An error occurred during automation:', error);
  } finally {
    // Ensure the browser is closed even if an error occurs
    if (browser) {
      await browser.close();
      console.log('Browser closed.');
    }
  }
}

runBrowserAutomation();