How to Verify Your Playwright Installation

Verify Playwright in three layers: confirm the project-local package and CLI, confirm the matching browser binaries, then run a smoke test that launches a browser. A version string alone does not prove that a browser executable is installed or usable.

1. Check the project-local Playwright package

Run these commands from the directory that contains your package.json:

npx --no-install playwright --version
npm ls @playwright/test playwright --depth=0

npx --no-install playwright --version is the safest first check. It resolves only a package already available in the project and refuses to download a missing package. If it prints a version, the local Playwright CLI is available. The npm ls command shows whether your project depends on @playwright/test, playwright, or both.

What the result proves

Check	Proves	Does not prove
`npx --no-install playwright --version`	A local CLI can be resolved	Browsers are installed or can launch
`npm ls`	The package is in the dependency tree	The package version matches browser binaries
`npx playwright install --list`	Playwright can find registered browser installations	OS libraries, permissions, or runtime launch are healthy
`npx playwright test`	The runner can execute a test and launch the selected browser	Every configured browser project works

2. Confirm browser binaries are installed

Playwright packages and browser binaries are separate installations. Each Playwright version needs specific browser versions, so reinstall browsers after upgrading the package.

npx playwright install
npx playwright install --list

The first command downloads the browser revisions required by the installed Playwright version. The second lists the browsers Playwright can find, including their locations and revisions.

Install only the browsers you use

npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

Compare the output of --list with the projects in playwright.config.ts, playwright.config.js, or another configuration file:

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

export default defineConfig({
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

If your configuration names Chromium, Firefox, and WebKit, install and verify all three. A Chromium-only installation cannot satisfy Firefox or WebKit projects.

3. Run a smoke test

A smoke test is the decisive check because it exercises package resolution, browser launch, page creation, and test execution.

mkdir -p tests
cat > tests/playwright-smoke.spec.ts <<'EOF'
import { test, expect } from '@playwright/test';

test('Playwright can launch a browser', async ({ page }) => {
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  await expect(page).toHaveTitle(/Example Domain/);
});
EOF
npx playwright test tests/playwright-smoke.spec.ts

For a headed check on a workstation, use:

npx playwright test tests/playwright-smoke.spec.ts --headed

To test one configured browser project:

npx playwright test tests/playwright-smoke.spec.ts --project=chromium

To run the complete configured suite:

npx playwright test

4. Verify a plain Playwright script

If you use the browser automation library without the test runner, launch it directly:

import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
await browser.close();

Save this as smoke.mjs and run:

node smoke.mjs

A successful title print confirms that the library can locate and launch Chromium outside the test runner.

5. Verify Playwright in CI

CI must install both the Node dependencies and the browser binaries. A typical sequence is:

npm ci
npx playwright install --with-deps chromium
npx playwright test

Use --with-deps on Linux runners when required system libraries are not preinstalled. If your suite uses Firefox or WebKit, install those browsers too.

Minimal CI checklist

Lock dependencies and use npm ci.
Run npx --no-install playwright --version to detect a missing local package.
Install browser revisions after dependency installation.
Run npx playwright install --list and retain its output in CI logs when diagnosing failures.
Run at least one smoke test before the full suite.
Cache browser downloads only when the cache key includes the Playwright version and operating system.

6. Fix missing operating-system dependencies

On Linux, a browser can be present but fail at launch because shared libraries are missing. Install the dependencies with:

npx playwright install-deps
# Or, for one browser:
npx playwright install --with-deps chromium

Container images and restricted CI workers commonly need this step. A launch error mentioning a missing shared object, sandbox, or display library points to the operating system rather than the JavaScript package.

7. Check browser cache paths and permissions

When install --list shows no browsers, inspect the standard cache locations:

Windows: %USERPROFILE%\AppData\Local\ms-playwright
macOS: ~/Library/Caches/ms-playwright
Linux: ~/.cache/ms-playwright

Use PLAYWRIGHT_BROWSERS_PATH when a shared or custom cache is intentional:

PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers npx playwright install chromium
PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers npx playwright test

The account that runs the test must be able to read and execute the cached browser files. A browser installed as one user may be invisible or inaccessible to another CI user.

8. Handle proxies, certificates, and internal mirrors

Browser downloads often fail in corporate networks. Set an HTTPS proxy for the install process:

HTTPS_PROXY=http://proxy.example:8080 npx playwright install

If TLS interception uses an internal certificate authority, point Node at the corporate root certificate:

NODE_EXTRA_CA_CERTS=/path/to/corporate-root.pem npx playwright install

If your organization mirrors Playwright browser archives, set the internal download host:

PLAYWRIGHT_DOWNLOAD_HOST=https://artifacts.example.internal/playwright npx playwright install

Keep these variables in the CI secret or environment configuration rather than committing credentials to the repository.

9. Troubleshooting common verification failures

Symptom	Likely cause	Fix
`npx --no-install playwright --version` fails	Playwright is not installed locally, or the command is run outside the project	Change to the project directory and run `npm ci` or `npm install -D @playwright/test`.
Version prints, but launch says executable is missing	Browser binaries were never installed or the cache is different	Run `npx playwright install`; check `PLAYWRIGHT_BROWSERS_PATH`.
Browser revision mismatch after an upgrade	The package changed but old binaries remain	Run `npx playwright install` again.
Linux launch reports missing libraries	OS dependencies are absent	Run `npx playwright install --with-deps chromium` or install the required packages through the image.
Download fails with certificate errors	Proxy TLS interception or an untrusted CA	Set `HTTPS_PROXY` and `NODE_EXTRA_CA_CERTS` to the approved values.
CI works for one browser but another project fails	Only one browser was installed	Install every browser named in the configuration and compare with `--list`.
Headed mode fails on a server	No graphical display is available	Use headless mode, or provide the CI runner’s supported display setup.
Permission denied in a shared cache	The test user cannot execute cached files	Fix ownership and execute permissions, or choose a writable `PLAYWRIGHT_BROWSERS_PATH`.

10. Make verification fast and reliable

Use --no-install for the package check so a typo or missing dependency fails immediately instead of triggering a download.
Install only the browser engines your projects require.
Cache browser binaries with a key containing the Playwright version, OS, and architecture.
Keep the smoke test small: one navigation and one assertion are enough to prove launch.
Run the smoke test before expensive parallel jobs so environment failures fail early.
Use the same Node version and dependency lockfile locally and in CI.
Record the CLI version, install --list output, and runner error when opening a failure report.

11. Or skip the browser setup

If your goal is a clean website image rather than browser automation, ScreenshotNeo provides a single screenshot API request. See the ScreenshotNeo API documentation for the full option list.

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

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

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server lets Claude, Cursor, and other MCP clients 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 shots. Create a free ScreenshotNeo account.

12. Frequently asked questions

How do I know Playwright is installed?

Run npx --no-install playwright --version from the project directory. Then run a smoke test because package availability alone does not prove a browser can launch.

Why does the version command work but the browser will not launch?

The package and browser binaries are separate. Install matching revisions with npx playwright install, then check operating-system dependencies, cache paths, and permissions.

Does `npx playwright install --list` run a test?

No. It reports browsers Playwright can find. A smoke test is still required to prove that the executable launches and a page can be created.

Do I need to reinstall browsers after every dependency install?

No. Reinstall when the Playwright package version changes, when the cache is removed, or when the browser list does not contain the revisions required by your configuration.

What is the best CI verification order?

Install locked Node dependencies, verify the local CLI, install browsers and system dependencies, run install --list, then run a small smoke test before the full suite.