---
title: Run a browser check locally with the same Playwright runtime
description: Reproduce a WatchFor browser check on your machine — the exact npm install for the runtime, a playwright.config that mirrors ours, and how to pass the same variables.
canonical: https://watchfor.io/docs/monitors/browser-checks/run-locally
---

# Run a browser check locally with the same Playwright runtime

Reproduce a WatchFor browser check on your machine — the exact npm install for the runtime, a playwright.config that mirrors ours, and how to pass the same variables.

A browser check is a normal Playwright Test file, so it runs on your laptop or
in CI unchanged. Use the same versions and settings as our runtime and a
failure reproduces the same way.

## 1. Install the runtime's versions

```bash
mkdir my-checks && cd my-checks
npm init -y
npm install -D @playwright/test@1.63.0 otpauth@9.5.2 @faker-js/faker@10.6.0
npx playwright install chromium
```

These are the versions of [runtime 2026.09](/docs/monitors/browser-checks/runtime).
Chromium comes from `npx playwright install`, so it is the same build our
runners use.

## 2. Mirror our config

Save this as `playwright.config.ts`. It sets what every run of ours starts
with:

```ts

// Variables and secrets from a git-ignored .env file, when there is one.
try {
  process.loadEnvFile('.env');
} catch {}

  testDir: './tests',
  workers: 1,
  timeout: 60_000, // the check's Timeout setting
  retries: 1, // the check's "Retry a failed test once" setting
  expect: { timeout: 5_000 },
  use: {
    browserName: 'chromium',
    viewport: { width: 1280, height: 720 },
    locale: 'en-US',
    timezoneId: 'UTC',
    actionTimeout: 15_000,
    navigationTimeout: 30_000,
    acceptDownloads: false,
    ignoreHTTPSErrors: false,
    serviceWorkers: 'allow',
    trace: 'retain-on-failure',
  },
});
```

## 3. Run the check

Copy the script from the check's **Script** tab into `tests/check.spec.ts`, and
put the same variables in `.env` (add it to `.gitignore`). `TARGET_URL` is the
check's URL:

```bash
# .env
TARGET_URL=https://shop.example.com
LOGIN_USERNAME=monitor@example.com
LOGIN_PASSWORD=…
```

```bash
npx playwright test
```

In CI, set the same names from your secret store instead of a file.

- `npx playwright test --headed` watches the browser work.
- `npx playwright show-trace test-results/*/trace.zip` opens the trace of a
  failed run — the same viewer the dashboard hosts.
- `npx playwright codegen https://shop.example.com` records clicks as code to
  paste into a step.

## What still differs

- **Where the browser is.** Our runs come from data-centre locations and reach
  only the public internet, through a guard that refuses private addresses.
  A page that only works on your office network or VPN won't work in a check.
- **User agent.** Our browser's user agent ends in
  `WatchFor-BrowserCheck/1.0 (+https://watchfor.io/bot)`; yours is plain Chrome. Sites
  with bot rules can treat the two differently — see
  [Troubleshooting](/docs/monitors/browser-checks/troubleshooting#passes-locally).
- **One file.** A check is a single spec file with no local imports or extra
  packages. Keep helpers inside the file.

---

Canonical page: https://watchfor.io/docs/monitors/browser-checks/run-locally · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt