patchwright 1.64.1 → 1.65.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/helpers.mjs ADDED
@@ -0,0 +1,387 @@
1
+ /**
2
+ * Patchwright Core Action & Universal Stealth Helpers
3
+ *
4
+ * Provides:
5
+ * 1. Humanized Action Primitives (attached to Page):
6
+ * - page.navigate(url, options): resilient navigation with blank retry & status validation
7
+ * - page.press_key(key, options): human-like typing with modifier combos & realistic delays
8
+ * - page.random_scroll(options): humanized wheel scrolling with lazy-load & direction detection
9
+ *
10
+ * 2. Universal Browser Auto-Finder & Installer (All OS & Architectures):
11
+ * - findSystemBrowser(): prioritizes Brave -> Edge -> Chrome across Win/Mac/Linux
12
+ * - installBrowserForServer(): auto-installs Brave silently across x64, arm64, x86, arm
13
+ *
14
+ * 3. VPS / Headless Virtual Display (Xvfb) Manager:
15
+ * - ensureAndStartXvfb(): spins up 1920x1080x24 virtual monitor so browsers run in headful mode
16
+ * - launchStealthBrowser(): one-line bulletproof launch for VPS, cloud VM, and desktop
17
+ */
18
+
19
+ import fs from 'fs';
20
+ import os from 'os';
21
+ import path from 'path';
22
+ import { spawn, execSync } from 'child_process';
23
+
24
+ const PLATFORM = process.platform;
25
+ const ARCH = process.arch;
26
+ const IS_ROOT = process.getuid ? process.getuid() === 0 : false;
27
+ let xvfbProcess = null;
28
+
29
+ /**
30
+ * Enhanced Page with Humanized Interaction Primitives
31
+ */
32
+ export function enhancePage(page) {
33
+ if (!page || page._enhanced) return page;
34
+ page._enhanced = true;
35
+
36
+ /**
37
+ * Resilient page navigation with blank retry and smart wait
38
+ */
39
+ page.navigate = async function (url, options = {}) {
40
+ const {
41
+ waitUntil = 'domcontentloaded',
42
+ timeout = 45000,
43
+ retries = 2
44
+ } = options;
45
+
46
+ let lastErr;
47
+ for (let attempt = 0; attempt <= retries; attempt++) {
48
+ try {
49
+ const response = await page.goto(url, { waitUntil, timeout });
50
+ return {
51
+ success: true,
52
+ url: page.url(),
53
+ status: response?.status() || 200,
54
+ attempt: attempt + 1
55
+ };
56
+ } catch (err) {
57
+ lastErr = err;
58
+ if (attempt < retries) {
59
+ await page.goto('about:blank').catch(() => {});
60
+ await new Promise(r => setTimeout(r, 1000));
61
+ }
62
+ }
63
+ }
64
+ throw new Error(`navigate failed for "${url}" after ${retries + 1} attempts: ${lastErr?.message}`);
65
+ };
66
+
67
+ /**
68
+ * Human-like keyboard press with modifier combo support and natural typing intervals
69
+ */
70
+ page.press_key = async function (key, options = {}) {
71
+ const { modifiers = [], count = 1, humanDelay = true } = options;
72
+ const clampedCount = Math.min(Math.max(count, 1), 100);
73
+
74
+ for (let i = 0; i < clampedCount; i++) {
75
+ let targetKey = key;
76
+ if (modifiers.some(m => m.toLowerCase() === 'shift') && targetKey.length === 1) {
77
+ targetKey = targetKey.toUpperCase();
78
+ }
79
+ if (modifiers.length > 0) {
80
+ const combo = [...modifiers, targetKey].join('+');
81
+ await page.keyboard.press(combo);
82
+ } else {
83
+ await page.keyboard.press(targetKey);
84
+ }
85
+ if (humanDelay && clampedCount > 1 && i < clampedCount - 1) {
86
+ await new Promise(r => setTimeout(r, 50 + Math.random() * 100));
87
+ }
88
+ }
89
+ return { success: true, key, modifiers, count: clampedCount };
90
+ };
91
+
92
+ /**
93
+ * Humanized random and smart scrolling with lazy-load detection & smooth wheel events
94
+ */
95
+ page.random_scroll = async function (options = {}) {
96
+ const {
97
+ direction = 'smart',
98
+ amount = 0,
99
+ smooth = true,
100
+ aiDetectLazyLoad = true
101
+ } = options;
102
+
103
+ let scrollAmount = amount || Math.floor(Math.random() * 450) + 200;
104
+
105
+ if (aiDetectLazyLoad) {
106
+ const lazyInfo = await page.evaluate(() => {
107
+ const lazyImages = document.querySelectorAll('img[loading="lazy"], img[data-src], [data-lazy]');
108
+ const infiniteScroll = !!document.querySelector('[class*="infinite"], [class*="load-more"]');
109
+ return { lazyImages: lazyImages.length, infiniteScroll };
110
+ }).catch(() => ({ lazyImages: 0, infiniteScroll: false }));
111
+
112
+ if (lazyInfo.lazyImages > 0) {
113
+ scrollAmount = Math.min(scrollAmount, 300);
114
+ }
115
+ }
116
+
117
+ let scrollDirection = direction;
118
+ if (direction === 'random') {
119
+ scrollDirection = Math.random() > 0.5 ? 'down' : 'up';
120
+ } else if (direction === 'smart') {
121
+ const scrollInfo = await page.evaluate(() => ({
122
+ scrollY: window.scrollY || window.pageYOffset || 0,
123
+ scrollHeight: document.body ? document.body.scrollHeight : 1000,
124
+ innerHeight: window.innerHeight || 800
125
+ })).catch(() => ({ scrollY: 0, scrollHeight: 1000, innerHeight: 800 }));
126
+
127
+ const atBottom = scrollInfo.scrollY + scrollInfo.innerHeight >= scrollInfo.scrollHeight - 100;
128
+ const atTop = scrollInfo.scrollY <= 10;
129
+ scrollDirection = atBottom ? 'up' : atTop ? 'down' : (Math.random() > 0.5 ? 'down' : 'up');
130
+ }
131
+
132
+ const y = scrollDirection === 'down' ? scrollAmount : -scrollAmount;
133
+
134
+ if (smooth) {
135
+ const steps = 6;
136
+ const stepY = Math.round(y / steps);
137
+ for (let i = 0; i < steps; i++) {
138
+ await page.mouse.wheel(0, stepY).catch(async () => {
139
+ await page.evaluate(({ delta }) => window.scrollBy({ top: delta, behavior: 'smooth' }), { delta: stepY });
140
+ });
141
+ await new Promise(r => setTimeout(r, 35 + Math.random() * 25));
142
+ }
143
+ } else {
144
+ await page.mouse.wheel(0, y).catch(async () => {
145
+ await page.evaluate(({ delta }) => window.scrollBy(0, delta), { delta: y });
146
+ });
147
+ }
148
+
149
+ return { success: true, direction: scrollDirection, amount: scrollAmount };
150
+ };
151
+
152
+ return page;
153
+ }
154
+
155
+ /**
156
+ * Get OS Browser Path Candidates (Priority: Brave -> Edge -> Chrome)
157
+ */
158
+ function getPlatformCandidates() {
159
+ const localAppData = process.env.LOCALAPPDATA || '';
160
+ const programFiles = process.env.ProgramFiles || 'C:\\Program Files';
161
+ const programFilesX86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
162
+ const home = os.homedir();
163
+
164
+ if (PLATFORM === 'win32') {
165
+ return {
166
+ brave: [
167
+ path.join(programFiles, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
168
+ path.join(programFilesX86, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
169
+ path.join(localAppData, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe')
170
+ ],
171
+ edge: [
172
+ path.join(programFilesX86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
173
+ path.join(programFiles, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
174
+ path.join(localAppData, 'Microsoft', 'Edge', 'Application', 'msedge.exe')
175
+ ],
176
+ chrome: [
177
+ path.join(programFiles, 'Google', 'Chrome', 'Application', 'chrome.exe'),
178
+ path.join(programFilesX86, 'Google', 'Chrome', 'Application', 'chrome.exe'),
179
+ path.join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe')
180
+ ]
181
+ };
182
+ } else if (PLATFORM === 'darwin') {
183
+ return {
184
+ brave: [
185
+ '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
186
+ path.join(home, 'Applications/Brave Browser.app/Contents/MacOS/Brave Browser')
187
+ ],
188
+ edge: [
189
+ '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
190
+ path.join(home, 'Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge')
191
+ ],
192
+ chrome: [
193
+ '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
194
+ path.join(home, 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome')
195
+ ]
196
+ };
197
+ } else {
198
+ // Linux (Ubuntu, Debian, CentOS, Alma, Arch)
199
+ return {
200
+ brave: [
201
+ '/usr/bin/brave-browser',
202
+ '/usr/bin/brave-browser-stable',
203
+ '/usr/bin/brave',
204
+ '/snap/bin/brave'
205
+ ],
206
+ edge: [
207
+ '/usr/bin/microsoft-edge',
208
+ '/usr/bin/microsoft-edge-stable'
209
+ ],
210
+ chrome: [
211
+ '/usr/bin/google-chrome',
212
+ '/usr/bin/google-chrome-stable',
213
+ '/usr/bin/chromium',
214
+ '/usr/bin/chromium-browser'
215
+ ]
216
+ };
217
+ }
218
+ }
219
+
220
+ /**
221
+ * 2. Find System Installed Browser (Brave -> Edge -> Chrome)
222
+ */
223
+ export function findSystemBrowser() {
224
+ const candidates = getPlatformCandidates();
225
+
226
+ // 1st Priority: Brave
227
+ for (const p of candidates.brave) {
228
+ if (p && fs.existsSync(p)) return { name: 'Brave Browser', type: 'brave', path: p };
229
+ }
230
+ // 2nd Priority: Edge
231
+ for (const p of candidates.edge) {
232
+ if (p && fs.existsSync(p)) return { name: 'Microsoft Edge', type: 'edge', path: p };
233
+ }
234
+ // 3rd Priority: Chrome
235
+ for (const p of candidates.chrome) {
236
+ if (p && fs.existsSync(p)) return { name: 'Google Chrome', type: 'chrome', path: p };
237
+ }
238
+
239
+ return null;
240
+ }
241
+
242
+ /**
243
+ * 3. Auto-Installer for Headless Servers / VPS (Cross-OS & Cross-Arch)
244
+ */
245
+ export async function installBrowserForServer() {
246
+ console.log(`⚡ No browser found on system. Auto-installing for [OS: ${PLATFORM}, Arch: ${ARCH}]...`);
247
+ const sudo = IS_ROOT ? '' : (PLATFORM !== 'win32' ? 'sudo ' : '');
248
+
249
+ if (PLATFORM === 'win32') {
250
+ let archTag = 'winx64';
251
+ if (ARCH === 'arm64') archTag = 'winarm64';
252
+ if (ARCH === 'ia32') archTag = 'winia32';
253
+
254
+ const setupPath = path.join(os.tmpdir(), 'BraveStandaloneSetup.exe');
255
+ const url = `https://laptop-updates.brave.com/latest/${archTag}`;
256
+ console.log(`⬇️ Downloading Brave standalone installer: ${url}`);
257
+ execSync(`curl.exe -sL "${url}" -o "${setupPath}"`);
258
+ execSync(`"${setupPath}" /silent /install`, { stdio: 'inherit' });
259
+ } else if (PLATFORM === 'darwin') {
260
+ const archTag = ARCH === 'arm64' ? 'osxarm64' : 'osx';
261
+ const dmgPath = path.join(os.tmpdir(), 'Brave.dmg');
262
+ const url = `https://laptop-updates.brave.com/latest/${archTag}`;
263
+ console.log(`⬇️ Downloading Brave DMG: ${url}`);
264
+ execSync(`curl -sL "${url}" -o "${dmgPath}"`);
265
+ execSync(`hdiutil attach "${dmgPath}" -nobrowse -quiet`);
266
+ execSync(`${sudo}cp -R "/Volumes/Brave Browser/Brave Browser.app" /Applications/`);
267
+ execSync(`hdiutil detach "/Volumes/Brave Browser" -quiet`);
268
+ } else {
269
+ // Linux (x64, arm64, 32-bit arm)
270
+ if (ARCH === 'x64' || ARCH === 'arm64') {
271
+ console.log('📦 Installing Brave Browser via official Linux distribution script...');
272
+ try {
273
+ if (fs.existsSync('/usr/bin/apt-get')) {
274
+ execSync(`${sudo}apt-get update -y && ${sudo}apt-get install -y curl gnupg`, { stdio: 'inherit' });
275
+ execSync(`curl -fsS https://dl.brave.com/install.sh | ${sudo}sh`, { stdio: 'inherit' });
276
+ } else if (fs.existsSync('/usr/bin/dnf') || fs.existsSync('/usr/bin/yum')) {
277
+ execSync(`curl -fsS https://dl.brave.com/install.sh | ${sudo}sh`, { stdio: 'inherit' });
278
+ }
279
+ } catch (err) {
280
+ console.warn('Fallback: installing chromium-browser via package manager...');
281
+ execSync(`${sudo}apt-get update -y && ${sudo}apt-get install -y chromium-browser || true`, { stdio: 'inherit' });
282
+ }
283
+ } else {
284
+ console.log('📦 32-bit ARM detected: installing system chromium package...');
285
+ execSync(`${sudo}apt-get update -y && ${sudo}apt-get install -y chromium-browser chromium`, { stdio: 'inherit' });
286
+ }
287
+ }
288
+
289
+ const browser = findSystemBrowser();
290
+ if (!browser) {
291
+ throw new Error(`Browser auto-installation completed but executable path could not be located. [OS: ${PLATFORM}, Arch: ${ARCH}]`);
292
+ }
293
+ return browser;
294
+ }
295
+
296
+ /**
297
+ * 4. Ensure and Start Xvfb Virtual Display for Headless Linux
298
+ */
299
+ export function ensureAndStartXvfb(display = ':99', resolution = '1920x1080x24') {
300
+ if (PLATFORM !== 'linux') return null;
301
+ if (process.env.DISPLAY) return null;
302
+
303
+ const sudo = IS_ROOT ? '' : 'sudo ';
304
+
305
+ try {
306
+ execSync('which Xvfb', { stdio: 'ignore' });
307
+ } catch {
308
+ console.log('📦 Installing Xvfb for virtual display headful execution...');
309
+ try {
310
+ if (fs.existsSync('/usr/bin/apt-get')) {
311
+ execSync(`${sudo}apt-get update -y && ${sudo}apt-get install -y xvfb`, { stdio: 'inherit' });
312
+ } else if (fs.existsSync('/usr/bin/dnf') || fs.existsSync('/usr/bin/yum')) {
313
+ const pm = fs.existsSync('/usr/bin/dnf') ? 'dnf' : 'yum';
314
+ execSync(`${sudo}${pm} install -y xorg-x11-server-Xvfb`, { stdio: 'inherit' });
315
+ }
316
+ } catch (e) {
317
+ console.warn('Xvfb installation notice:', e.message);
318
+ }
319
+ }
320
+
321
+ try {
322
+ const lockFile = `/tmp/.X${display.replace(':', '')}-lock`;
323
+ if (fs.existsSync(lockFile)) fs.unlinkSync(lockFile);
324
+ } catch {}
325
+
326
+ xvfbProcess = spawn('Xvfb', [
327
+ display,
328
+ '-screen', '0', resolution,
329
+ '-ac',
330
+ '+extension', 'GLX',
331
+ '+render',
332
+ '-noreset'
333
+ ], {
334
+ detached: true,
335
+ stdio: 'ignore'
336
+ });
337
+
338
+ xvfbProcess.unref();
339
+ process.env.DISPLAY = display;
340
+
341
+ try { execSync('sleep 0.5'); } catch {}
342
+ console.log(`✅ Xvfb virtual display active: DISPLAY=${process.env.DISPLAY}`);
343
+
344
+ const cleanXvfb = () => {
345
+ if (xvfbProcess && !xvfbProcess.killed) {
346
+ try { process.kill(-xvfbProcess.pid); } catch {}
347
+ }
348
+ };
349
+ process.on('exit', cleanXvfb);
350
+ process.on('SIGINT', cleanXvfb);
351
+ process.on('SIGTERM', cleanXvfb);
352
+
353
+ return xvfbProcess;
354
+ }
355
+
356
+ /**
357
+ * 5. One-Line Bulletproof Browser Launcher (combines Xvfb + Auto-Finder + Stealth)
358
+ */
359
+ export async function launchStealthBrowser(chromiumModule, options = {}) {
360
+ if (PLATFORM === 'linux' && !process.env.DISPLAY && options.useXvfb !== false) {
361
+ ensureAndStartXvfb(':99', options.resolution || '1920x1080x24');
362
+ }
363
+
364
+ let browserInfo = findSystemBrowser();
365
+ if (!browserInfo && options.autoInstall !== false) {
366
+ browserInfo = await installBrowserForServer();
367
+ }
368
+
369
+ const defaultFlags = [
370
+ '--no-sandbox',
371
+ '--disable-setuid-sandbox',
372
+ '--disable-dev-shm-usage',
373
+ '--no-first-run',
374
+ '--no-default-browser-check',
375
+ '--window-size=1920,1080'
376
+ ];
377
+
378
+ const launchConfig = {
379
+ ...(browserInfo ? { executablePath: browserInfo.path } : {}),
380
+ headless: options.headless !== undefined ? options.headless : (PLATFORM === 'linux' && process.env.DISPLAY ? false : true),
381
+ args: [...defaultFlags, ...(options.args || [])],
382
+ ...options
383
+ };
384
+
385
+ const browser = await chromiumModule.launch(launchConfig);
386
+ return { browser, browserInfo };
387
+ }
@@ -118,7 +118,6 @@ function overridesFromOptions(options) {
118
118
  globalTimeout: options.globalTimeout ? parseInt(options.globalTimeout, 10) : void 0,
119
119
  maxFailures: options.x ? 1 : options.maxFailures ? parseInt(options.maxFailures, 10) : void 0,
120
120
  outputDir: options.output ? import_path.default.resolve(process.cwd(), options.output) : void 0,
121
- pause: !!process.env.PWPAUSE,
122
121
  quiet: options.quiet ? options.quiet : void 0,
123
122
  repeatEach: options.repeatEach ? parseInt(options.repeatEach, 10) : void 0,
124
123
  retries: options.retries ? parseInt(options.retries, 10) : void 0,