fingerprint-playwright

Playwright launcher utilities for fingerprint Chromium browsers.

fingerprint-playwright uses playwright-core as a peer dependency. On first launch it downloads the fingerprint browser binary to ~/.fingerprint-browser/releases/v144.0.7559.132/chrome and reuses the cached executable afterward. It does not implement license checks.

Install

pnpm add fingerprint-playwright playwright-core

Usage

import { launch } from 'fingerprint-playwright';

const browser = await launch({
  headless: false,
});

const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

GeoIP can auto-fill timezone and locale from the proxy egress IP. It probes IP echo services through the proxy first, so proxy-pool gateways can resolve to their real exit IP; if that fails, it falls back to the proxy host IP. Install the optional peer dependency first:

pnpm add mmdb-lib

const browser = await launch({
  proxy: 'http://user:[email protected]:8080',
  geoip: true,
});

Authenticated HTTP/HTTPS proxies are passed to patched fingerprint Chromium as inline --proxy-server URLs, with credential components URL-encoded. This lets the browser's native proxy authentication flow handle the challenge instead of Playwright's proxy auth handler. Plain HTTP proxies without credentials continue to use Playwright's proxy option.

Human-like interaction patching is available in the wrapper layer:

const browser = await launch({
  humanize: true,
  humanPreset: 'careful',
});

const page = await browser.newPage();
await page.fill('#email', '[email protected]');
await page.click('button[type="submit"]');

Explicit values always win:

await launch({
  proxy: 'http://user:[email protected]:8080',
  geoip: true,
  timezone: 'America/New_York',
  locale: 'en-US',
});

When geoip discovers a locale, it appends --fingerprint-locale=<locale> instead of --lang or --accept-lang. When it discovers an exit IP, it also appends --fingerprint-webrtc-ip=<exit-ip> unless you already provided a --fingerprint-webrtc-ip argument.

CommonJS is supported too:

const { launch } = require('fingerprint-playwright');

You can also set:

export FINGERPRINT_BROWSER_BINARY_PATH=/path/to/fingerprint/chrome

FINGERPRINT_BROWSER_EXECUTABLE_PATH is also accepted for compatibility. These environment variables skip auto-download and use your local browser.

The built-in browser download URL is:

https://downloads.crowbrowser.com/releases/v144.0.7559.132/fingerprint-browser-linux-x64.tar.xz

You can override the download URL with FINGERPRINT_BROWSER_DOWNLOAD_URL. Set FINGERPRINT_BROWSER_CACHE_DIR to override the default cache directory. The GeoIP database uses the same cache root and is stored at ~/.fingerprint-browser/geoip/GeoLite2-City.mmdb by default.

You can pre-download the browser from the CLI:

npx fingerprint-playwright install

install also pre-downloads the cached GeoIP database used by geoip: true.

Useful CLI commands:

npx fingerprint-playwright info
npx fingerprint-playwright update
npx fingerprint-playwright clear-cache

API

import {
  launch,
  launchContext,
  launchPersistentContext,
  buildLaunchOptions,
  buildContextOptions,
  binaryInfo,
  browserDownloadUrl,
  ensureBinary,
  clearCache,
} from 'fingerprint-playwright';

The launch options mirror the Playwright-focused subset of cloakbrowser:

• headless
• executablePath
• proxy
• args
• extensionPaths
• stealthArgs
• webgpu
• timezone
• locale
• geoip
• humanize
• humanPreset
• humanConfig
• launchOptions
• userAgent, viewport, timezoneId, colorScheme, contextOptions for contexts

For WebGPU-patched 149+ browser builds, set webgpu: true or pass --enable-unsafe-webgpu in args so the browser can expose its patched WebGPU adapter. This is opt-in because older cached browser builds do not include the WebGPU fingerprint patch.

No license, Pro tier, or Puppeteer behavior is included in v1.

Tests

Unit tests live next to source files as src/*.spec.ts:

pnpm test

E2E tests live in tests/*-e2e.spec.ts. They use the same auto-download cache as normal launches:

pnpm test:e2e

The e2e suite uses local pages by default and covers launch, extra args, managed contexts, persistent profiles, and common automation signals.

Humanize e2e also includes external behavioral bot-form coverage. Visual headed humanize walkthroughs are available with:

FINGERPRINT_PLAYWRIGHT_VISUAL_E2E=1 pnpm test:e2e