graceful-playwright 1.5.1 → 1.7.0

package/README.md

@@ -20,6 +20,8 @@ Gracefully handle timeout and network error with auto retry.
 
 - create `Page` instance lazily (on-demand)
 
+- stealth helpers to reduce common Playwright automation signals (`navigator.webdriver`, `HeadlessChrome` user agent, missing `window.chrome`)
+
 ## Installation
 
 ```bash
@@ -33,6 +35,7 @@ You can install the package with yarn, pnpm or slnpm as well.
 More usage examples see: [example.ts](./example.ts) and [core.spec.ts](./core.spec.ts)
 
 ```typescript
+import { chromium } from 'playwright'
 import { GracefulPage } from 'graceful-playwright'
 
 let browser = await chromium.launch()
@@ -122,6 +125,91 @@ export type GotoErrorDetails = {
 }
 ```
 
+Stealth Helpers
+
+```typescript
+/** build a non-HeadlessChrome user agent from bundled chromium version */
+export function getStealthUserAgent(): string
+
+/** launch args for chromium.launch() and chromium.launchPersistentContext() */
+export function getStealthChromiumArgs(options?: {
+  /** opt in for Docker/CI/root; sandbox is enabled by default */
+  noSandbox?: boolean
+  /** @default getStealthUserAgent() */
+  userAgent?: string
+}): string[]
+
+/** pass to context.addInitScript(stealthChromeInitScript) */
+export function stealthChromeInitScript(): void
+```
+
+`getStealthChromiumArgs()` returns:
+
+- `--no-sandbox` (only when `noSandbox: true`)
+- `--disable-setuid-sandbox` (only when `noSandbox: true`)
+- `--disable-dev-shm-usage`
+- `--user-agent=...` (from `options.userAgent` or `getStealthUserAgent()`)
+- `--disable-blink-features=AutomationControlled`
+
+`getStealthUserAgent()` builds a `Chrome/${major}.0.0.0` user agent from the bundled chromium binary (`chrome --product-version`) without launching a browser.
+
+`stealthChromeInitScript` patches missing `window.chrome` fields (`app`, `loadTimes`, `csi`) before page scripts run. Pass the function reference to `addInitScript` — do not call it yourself.
+
+Example (see also [example.ts](./example.ts)):
+
+```typescript
+import { chromium } from 'playwright'
+import {
+  getStealthChromiumArgs,
+  stealthChromeInitScript,
+  GracefulPage,
+} from 'graceful-playwright'
+
+let context = await chromium.launchPersistentContext('.chromium', {
+  args: getStealthChromiumArgs(),
+  // channel: 'chromium', // optional: new headless mode (full chromium engine)
+  // channel: 'chrome', // optional: installed Google Chrome
+  // headless: false,
+})
+await context.addInitScript(stealthChromeInitScript)
+let page = new GracefulPage({ from: context })
+
+await page.goto('https://example.net')
+await context.close()
+```
+
+Notes:
+
+- use `noSandbox: true` only in Docker, CI, or when running as root
+- use `channel: 'chromium'` for new headless mode — closer to real Chrome than the default headless shell
+- use `channel: 'chrome'` when you need installed Google Chrome locally (e.g. codecs, `window.chrome`)
+- default (no `channel`) uses bundled headless shell — best for CI; add `stealthChromeInitScript` if sites check `window.chrome`
+
+Helper Functions: `sleep` and `sleepUntil`
+
+```typescript
+/**
+ * Resolves after the given number of milliseconds.
+ * @param options.extraRandom when true, adds up to `ms` of random jitter;
+ *   when a number, adds up to that many ms of jitter; default off
+ */
+export function sleep(
+  ms: number,
+  options?: { extraRandom?: number | false | true },
+): Promise<void>
+
+/**
+ * Polls `conditionFn` until it returns true, or throws on timeout.
+ * @param options.interval polling interval in ms (default: ~33ms, 30 fps)
+ * @param options.timeout overall timeout in ms (default: 30000)
+ * @param options.extraRandom passed to each `sleep(interval)` poll wait
+ */
+export function sleepUntil(
+  conditionFn: () => boolean | Promise<boolean>,
+  options?: { interval?: number; timeout?: number; extraRandom?: number },
+): Promise<void>
+```
+
 ## License
 
 This project is licensed with [BSD-2-Clause](./LICENSE)

package/core.d.ts

@@ -1,4 +1,14 @@
 import { Browser, BrowserContext, Page } from 'playwright';
+/** build a non-HeadlessChrome user agent without launching a browser */
+export declare function getStealthUserAgent(): string;
+/** can be used in args by `chromium.launch()` and `chromium.launchPersistentContext()` */
+export declare function getStealthChromiumArgs(options?: {
+    noSandbox?: boolean;
+    /** @default getStealthUserAgent() */
+    userAgent?: string;
+}): string[];
+/** run via `context.addInitScript(stealthChromeInitScript)` */
+export declare function stealthChromeInitScript(): void;
 export declare class GracefulPage {
     options: {
         from: Browser | BrowserContext;
@@ -67,4 +77,12 @@ export declare class GotoError extends Error {
     details: GotoErrorDetails;
     constructor(message: string, details: GotoErrorDetails);
 }
+export declare function sleep(ms: number, options?: {
+    extraRandom?: number | false | true;
+}): Promise<unknown>;
+export declare function sleepUntil(conditionFn: () => boolean | Promise<boolean>, options?: {
+    interval?: number;
+    timeout?: number;
+    extraRandom?: number;
+}): Promise<void>;
 export declare function parseRetryAfter(headerValue: string | null): number | null;

package/core.js

@@ -1,7 +1,140 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GotoError = exports.GracefulPage = void 0;
+exports.getStealthUserAgent = getStealthUserAgent;
+exports.getStealthChromiumArgs = getStealthChromiumArgs;
+exports.stealthChromeInitScript = stealthChromeInitScript;
+exports.sleep = sleep;
+exports.sleepUntil = sleepUntil;
 exports.parseRetryAfter = parseRetryAfter;
+const child_process_1 = require("child_process");
+const playwright_1 = require("playwright");
+let cachedChromiumMajorVersion;
+/** read from bundled chromium via `chrome --product-version` */
+function getChromiumMajorVersion() {
+    if (!cachedChromiumMajorVersion) {
+        let output = (0, child_process_1.execSync)(`"${playwright_1.chromium.executablePath()}" --product-version`, {
+            encoding: 'utf8',
+        }).trim();
+        cachedChromiumMajorVersion = output.match(/^(\d+)/)?.[1] ?? '120';
+    }
+    return cachedChromiumMajorVersion;
+}
+function getPlatformToken() {
+    if (process.platform === 'darwin') {
+        return 'Macintosh; Intel Mac OS X 10_15_7';
+    }
+    if (process.platform === 'win32') {
+        return 'Windows NT 10.0; Win64; x64';
+    }
+    let arch = process.arch === 'arm64' ? 'aarch64' : 'x86_64';
+    return `X11; Linux ${arch}`;
+}
+/** build a non-HeadlessChrome user agent without launching a browser */
+function getStealthUserAgent() {
+    let major = getChromiumMajorVersion();
+    let platform = getPlatformToken();
+    return `Mozilla/5.0 (${platform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36`;
+}
+/** can be used in args by `chromium.launch()` and `chromium.launchPersistentContext()` */
+function getStealthChromiumArgs(options = {}) {
+    let args = [];
+    if (options.noSandbox) {
+        args.push('--no-sandbox', '--disable-setuid-sandbox');
+    }
+    args.push('--disable-dev-shm-usage', '--disable-blink-features=AutomationControlled');
+    let userAgent = options.userAgent || getStealthUserAgent();
+    args.push(`--user-agent=${userAgent}`);
+    return args;
+}
+/** run via `context.addInitScript(stealthChromeInitScript)` */
+function stealthChromeInitScript() {
+    let win = window;
+    win.chrome = win.chrome || {};
+    let chrome = win.chrome;
+    function getNavigationTiming() {
+        let navigation = performance.getEntriesByType('navigation')[0];
+        if (navigation) {
+            let timeOrigin = performance.timeOrigin;
+            let domContentLoadedEventEnd = navigation.domContentLoadedEventEnd ||
+                navigation.domContentLoadedEventStart ||
+                0;
+            let loadEventEnd = navigation.loadEventEnd || domContentLoadedEventEnd || 0;
+            let responseStart = navigation.responseStart || 0;
+            return {
+                navigationStartMs: timeOrigin,
+                navigationStartSec: timeOrigin / 1000,
+                domContentLoadedMs: timeOrigin + domContentLoadedEventEnd,
+                domContentLoadedSec: (timeOrigin + domContentLoadedEventEnd) / 1000,
+                loadEventEndMs: timeOrigin + loadEventEnd,
+                loadEventEndSec: (timeOrigin + loadEventEnd) / 1000,
+                responseStartSec: (timeOrigin + responseStart) / 1000,
+                protocol: navigation.nextHopProtocol || 'http/1.1',
+            };
+        }
+        // fallback for very early init script execution
+        let timing = performance.timing;
+        let navigationStartMs = timing.navigationStart;
+        let domContentLoadedMs = timing.domContentLoadedEventEnd || navigationStartMs;
+        let loadEventEndMs = timing.loadEventEnd ||
+            timing.domContentLoadedEventEnd ||
+            navigationStartMs;
+        return {
+            navigationStartMs,
+            navigationStartSec: navigationStartMs / 1000,
+            domContentLoadedMs,
+            domContentLoadedSec: domContentLoadedMs / 1000,
+            loadEventEndMs,
+            loadEventEndSec: loadEventEndMs / 1000,
+            responseStartSec: timing.responseStart / 1000,
+            protocol: 'http/1.1',
+        };
+    }
+    chrome.app ||= {
+        isInstalled: false,
+        InstallState: {
+            DISABLED: 'disabled',
+            INSTALLED: 'installed',
+            NOT_INSTALLED: 'not_installed',
+        },
+        RunningState: {
+            CANNOT_RUN: 'cannot_run',
+            READY_TO_RUN: 'ready_to_run',
+            RUNNING: 'running',
+        },
+    };
+    chrome.loadTimes ||= () => {
+        let timing = getNavigationTiming();
+        let protocol = timing.protocol;
+        let usesHttp2Or3 = protocol === 'h2' || protocol === 'h3';
+        return {
+            requestTime: timing.navigationStartSec,
+            startLoadTime: timing.navigationStartSec,
+            commitLoadTime: timing.domContentLoadedSec,
+            finishDocumentLoadTime: timing.domContentLoadedSec,
+            finishLoadTime: timing.loadEventEndSec,
+            firstPaintTime: timing.responseStartSec,
+            firstPaintAfterLoadTime: 0,
+            navigationType: 'Other',
+            wasFetchedViaSpdy: usesHttp2Or3,
+            wasNpnNegotiated: usesHttp2Or3,
+            npnNegotiatedProtocol: usesHttp2Or3 ? protocol : 'unknown',
+            wasAlternateProtocolAvailable: false,
+            connectionInfo: protocol,
+        };
+    };
+    chrome.csi ||= () => {
+        let timing = getNavigationTiming();
+        let startE = timing.navigationStartMs;
+        let onloadT = timing.domContentLoadedMs || startE;
+        return {
+            startE,
+            onloadT,
+            pageT: performance.now(),
+            tran: 15,
+        };
+    };
+}
 class GracefulPage {
     options;
     constructor(options) {
@@ -159,9 +292,27 @@ class GotoError extends Error {
     }
 }
 exports.GotoError = GotoError;
-function sleep(ms) {
+function sleep(ms, options) {
+    if (options?.extraRandom) {
+        let extraRandom = typeof options.extraRandom === 'number' ? options.extraRandom : ms;
+        ms += Math.random() * extraRandom;
+    }
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+async function sleepUntil(conditionFn, options) {
+    let sleepOptions = options && 'extraRandom' in options
+        ? { extraRandom: options.extraRandom }
+        : undefined;
+    let interval = options?.interval || 1000 / 30; // 30 fps
+    let timeout = options?.timeout || 30_000; // 30 seconds
+    let endTime = Date.now() + timeout;
+    while (Date.now() < endTime) {
+        if (await conditionFn())
+            return;
+        await sleep(interval, sleepOptions);
+    }
+    throw new Error('Timeout');
+}
 function parseRetryAfter(headerValue) {
     if (!headerValue)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graceful-playwright",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "Gracefully handle timeout and network error with auto retry.",
   "keywords": [
     "graceful",
@@ -51,20 +51,20 @@
     "playwright": "^1.41.2"
   },
   "devDependencies": {
-    "@types/chai": "4",
-    "@types/express": "^4.17.21",
-    "@types/mocha": "^10.0.6",
-    "@types/node": "^20.11.17",
-    "@types/sinon": "^17.0.1",
-    "chai": "4",
-    "express": "^4.18.2",
-    "mocha": "^11.2.2",
+    "@types/chai": "^4.3.20",
+    "@types/express": "^4.17.25",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.19.43",
+    "@types/sinon": "^17.0.4",
+    "chai": "^4.5.0",
+    "express": "^4.22.2",
+    "mocha": "^11.7.6",
     "npm-run-all": "^4.1.5",
-    "playwright": "^1.52.0",
-    "rimraf": "^6.0.1",
+    "playwright": "^1.61.1",
+    "rimraf": "^6.1.3",
     "sinon": "^20.0.0",
     "ts-mocha": "^11.1.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.3.3"
+    "typescript": "^6.0.3"
   }
 }