How to Run a Playwright Script in Chrome

To run Playwright in Google Chrome, install Playwright, make sure Google Chrome is installed, and launch the Chromium browser type with channel: 'chrome'. Playwright’s bundled Chromium and Google’s branded Chrome are different browser targets. The bundled browser is the default and is usually suitable for routine automation; use the Chrome channel when you need to validate behavior in Google’s branded browser.

Playwright does not install branded Chrome for you. Install Chrome separately, then keep your Playwright package and browser binaries aligned with the Playwright version you use. The official browser guide covers supported channels and installation details: Playwright browsers.

1. Install Playwright and its browser binaries

JavaScript or TypeScript

npm install -D playwright
npx playwright install chromium

The playwright package provides the browser automation library. Projects built around the Playwright test runner commonly install @playwright/test instead:

npm install -D @playwright/test
npx playwright install chromium

After upgrading Playwright, run the browser installation command again so the browser revision matches the package version. On Linux, install required operating-system dependencies if the browser cannot start:

npx playwright install --with-deps chromium

Python

pip install playwright
playwright install

You can install only Chromium when that is all your project needs:

playwright install chromium

The Python setup pattern is documented in the Playwright Python library guide.

2. Confirm that Google Chrome is installed

The chrome channel asks Playwright to launch a branded Google Chrome installation. If Chrome is absent, or a managed machine hides it behind an enterprise policy, the launch can fail even when Playwright itself is installed correctly. Install Chrome through your normal operating-system or company software process before running the script.

Do not make executablePath your routine workaround. Playwright warns that arbitrary browser executable versions are not guaranteed to be compatible; use a documented browser channel when it matches your requirement.

3. Run a JavaScript script in branded Chrome

Create run-chrome.js:

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

(async () => {
  const browser = await chromium.launch({
    channel: 'chrome'
  });

  try {
    const page = await browser.newPage();
    await page.goto('https://playwright.dev', {
      waitUntil: 'domcontentloaded'
    });
    console.log(await page.title());
  } finally {
    await browser.close();
  }
})();

Run it with:

node run-chrome.js

Playwright is headless by default. To see the Chrome window while developing, set headless: false:

const browser = await chromium.launch({
  channel: 'chrome',
  headless: false
});

Use a deliberate wait condition for the page you are automating. domcontentloaded waits for the document structure; pages that render data after JavaScript runs may need a locator assertion or an explicit readiness condition instead of a fixed sleep.

4. Run a Python script in branded Chrome

Synchronous API

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(channel="chrome")
    try:
        page = browser.new_page()
        page.goto("https://playwright.dev", wait_until="domcontentloaded")
        print(page.title())
    finally:
        browser.close()

Asynchronous API

import asyncio
from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(channel="chrome")
        try:
            page = await browser.new_page()
            await page.goto("https://playwright.dev", wait_until="domcontentloaded")
            print(await page.title())
        finally:
            await browser.close()

asyncio.run(main())

Use the async form when your application already runs an asyncio event loop. The browser channel is still selected on p.chromium.launch().

5. Configure Playwright Test to use Chrome

For a test suite, define a project whose use options include channel: 'chrome':

import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Google Chrome',
      use: {
        channel: 'chrome'
      }
    }
  ]
});

Run every configured project:

npx playwright test

Run only this project:

npx playwright test --project="Google Chrome"

You can keep a separate project for Playwright’s bundled Chromium and compare results:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    { name: 'Bundled Chromium', use: {} },
    { name: 'Google Chrome', use: { channel: 'chrome' } }
  ]
});

6. Choose between bundled Chromium and branded Chrome

Question	Bundled Chromium	Chrome channel
What is launched?	The browser revision Playwright manages	An installed Google Chrome build
Is Chrome installed separately?	No, Playwright installs its browser binary	Yes
Best fit	Routine automation and repeatable test environments	Chrome-specific validation or an explicit branded-Chrome requirement
Launch setting	Default launch	channel: 'chrome'

Selecting the channel does not guarantee compatibility with every enterprise-managed Chrome installation. Browser policies can restrict automation, downloads, extensions, or remote debugging.

7. Headless and headed Chrome behavior

Headless mode is the default and is normally the fastest choice for CI. Set headless: false (JavaScript) or headless=False (Python) when you need to watch the browser during debugging.

Chrome’s newer headless implementation is the real Chrome browser rather than Playwright’s default headless shell. Playwright’s browser documentation quotes Chrome documentation describing that mode as more authentic and featureful. Choose the mode that matches what you need to verify, and test headed behavior when diagnosing differences that appear only with a visible window.

8. Common errors and fixes

Error or symptom	Likely cause	Fix
Executable missing	Playwright’s browser binaries were not installed for the current package version.	Run npx playwright install chromium or playwright install chromium.
channel: 'chrome' cannot launch	Branded Chrome is not installed or is unavailable to the current user.	Install Chrome separately and verify the machine’s enterprise policy permits automation.
Linux reports missing shared libraries	System dependencies required by Chromium are absent.	Run npx playwright install --with-deps chromium where your environment permits it.
Works locally but fails in CI	The CI image lacks Chrome, dependencies, display access, or the matching browser revision.	Install dependencies during image setup, use headless mode, and rerun the Playwright browser install step after package changes.
Page title is empty or content is missing	The page’s application code has not finished rendering.	Wait for a meaningful locator or application-specific readiness signal instead of relying only on a short timeout.
Tests behave differently across machines	Different Chrome versions, policies, profiles, or extensions are involved.	Pin the Playwright package, keep browser installation consistent, and use a clean context for each test.

For command-line options and diagnostics, see the Playwright command-line documentation.

9. Reliability and performance practices

• Reuse a browser process carefully. Launching one browser and creating isolated contexts is usually cheaper than launching a new browser for every URL. Close contexts and pages when each unit of work finishes.
• Use locators and assertions. They wait for the state your test needs and are less fragile than arbitrary sleeps.
• Keep package and browser versions aligned. Reinstall browser binaries after Playwright upgrades.
• Use headless mode in CI. Switch to headed mode only when debugging or when visible-window behavior is the subject of the test.
• Control external state. Use a clean browser context, explicit viewport and timezone settings, and stable test data when results must be repeatable.
• Capture diagnostics on failure. Record the URL, browser channel, Playwright version, operating system, and relevant console or network errors.

There is no fixed current download size you should budget from documentation examples: cache sizes vary by version and platform. Measure the image or cache footprint in your own CI environment.

Or skip the browser setup

If your goal is a clean screenshot rather than browser-test control, ScreenshotNeo returns an image or PDF from one API request. It handles the browser setup for you, and its API documentation lists the available options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
require('fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie banners, newsletter popups and chat widgets are removed before the shot. Bot checks, blank pages and failed loads are never billed, and response headers report the page verdict and whether the request was billed. ScreenshotNeo also provides an MCP server so Claude, Cursor and other MCP clients can call take_screenshot, get_page_info and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Does Playwright use Chrome by default?

No. Playwright normally uses its bundled Chromium. Add channel: 'chrome' when you specifically need branded Google Chrome.

Can I use Chrome Beta or another Chrome channel?

Use only channels supported by the Playwright version you installed and verify the browser is present on the machine. The examples here target the documented chrome channel.

Should I install Chrome or Chromium for CI?

Install the browser that matches your test requirement. Bundled Chromium is generally simpler and more repeatable; branded Chrome is appropriate when Chrome-specific behavior is part of the requirement.

Why does a script pass headless but fail headed?

Headed and headless modes can differ in display environment, browser implementation and enterprise policy. Reproduce the failure in the same mode used by deployment, then inspect readiness, permissions and policy restrictions.

Is executablePath better than channel?

No routine preference is implied. The channel is the documented choice for branded Chrome; arbitrary executable paths can pair Playwright with an unsupported browser version.