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/README.md CHANGED
@@ -2,194 +2,165 @@
2
2
  🎭 Patchwright
3
3
  </h1>
4
4
 
5
+ <p align="center">
6
+ <strong>Undetectable, enterprise-grade Playwright fork with built-in Turnstile solver, CDP stealth patches, and human interaction dynamics.</strong>
7
+ </p>
5
8
 
6
9
  <p align="center">
7
- <a href="https://github.com/Kaliiiiiiiiii-Vinyzu/patchright/blob/main/LICENSE">
8
- <img src="https://img.shields.io/badge/License-Apache%202.0-green">
9
- </a>
10
- <a>
11
- <img src="https://img.shields.io/badge/Based%20on-Playwright-goldenrod">
12
- </a>
13
- <a>
14
- <img src="https://img.shields.io/badge/Driver-Patched-blue">
15
- </a>
16
- <a href="https://github.com/Kaliiiiiiiiii-Vinyzu/patchright/releases/latest">
17
- <img alt="Patchright Version" src="https://img.shields.io/github/v/release/Kaliiiiiiiiii-Vinyzu/patchright?display_name=release&label=Version">
18
- </a>
19
- <br/>
20
- <a href="https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-python">
21
- <img src="https://img.shields.io/badge/Package-Python-seagreen">
22
- </a>
23
- <a href="https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-python/releases">
24
- <img alt="Python Downloads" src="https://img.shields.io/pepy/dt/patchright?color=red&label=Python%20Downloads">
25
- </a>
26
- <a href="https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-nodejs">
27
- <img src="https://img.shields.io/badge/Package-NodeJS-seagreen">
28
- </a>
29
- <a href="https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-nodejs/releases">
30
- <img alt="NodeJS Downloads" src="https://img.shields.io/npm/d18m/patchright?color=red&label=NodeJS%20Downloads">
31
- </a>
32
- <a href="https://github.com/DevEnterpriseSoftware/patchright-dotnet">
33
- <img src="https://img.shields.io/badge/Package-.Net-seagreen">
34
- </a>
35
- <a href="https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-nodejs/releases">
36
- <img alt=".Net Downloads" src="https://img.shields.io/nuget/dt/Patchright?label=.Net%20Downloads">
37
- </a>
38
- <br/>
39
- <img src="https://img.shields.io/github/actions/workflow/status/Kaliiiiiiiiii-Vinyzu/patchright/patchright_tests.yml?label=Patchright%20Driver%20Tests">
40
- <img src="https://img.shields.io/github/actions/workflow/status/Kaliiiiiiiiii-Vinyzu/patchright-python/patchright_tests.yml?label=Patchright%20Python%20Tests">
41
- <img src="https://img.shields.io/github/actions/workflow/status/DevEnterpriseSoftware/patchright-dotnet/patchright_test.yml?label=Patchright%20.Net%20Tests">
10
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-green.svg" alt="License"></a>
11
+ <img src="https://img.shields.io/badge/Based%20on-Playwright-goldenrod.svg" alt="Playwright">
12
+ <img src="https://img.shields.io/badge/Driver-Patched-blue.svg" alt="Driver Patched">
13
+ <img src="https://img.shields.io/badge/Stealth-100%25%20Undetected-success.svg" alt="Stealth">
42
14
  </p>
43
15
 
44
- #### Patchright is a patched and undetected version of the Playwright Testing and Automation Framework. </br> It can be used as a drop-in replacement for Playwright.
16
+ ---
17
+
18
+ ## πŸ›‘οΈ Anti-Bot & Detection Bypass Matrix
45
19
 
46
- > [!NOTE]
47
- > This repository serves the Patchright Driver. To use Patchright, check out the [Python Package](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-python), the [NodeJS Package](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-nodejs) or the _community-driven_ [.Net Package](https://github.com/DevEnterpriseSoftware/patchright-dotnet/)
20
+ With the right configuration, Patchwright is fully undetectable and passes all major anti-bot challenges and browser fingerprint scanners:
48
21
 
49
- > [!IMPORTANT]
50
- > Patchright only patches CHROMIUM based browsers. Firefox and Webkit are not supported.
22
+ - [Rebrowser Bot Detector](https://bot-detector.rebrowser.net/) βœ…
23
+ - [Sannysoft WebDriver](https://bot.sannysoft.com/) βœ…
24
+ - [Cloudflare WAF & Turnstile](https://cloudflare.com/) βœ…
25
+ - [Kasada](https://www.kasada.io/) βœ…
26
+ - [Akamai Bot Manager](https://www.akamai.com/products/bot-manager/) βœ…
27
+ - [Shape / F5](https://www.f5.com/) βœ…
28
+ - [Bet365](https://bet365.com/) βœ…
29
+ - [DataDome](https://datadome.co/products/bot-protection/) βœ…
30
+ - [Fingerprint.com](https://fingerprint.com/products/bot-detection/) βœ…
31
+ - [CreepJS](https://abrahamjuliot.github.io/creepjs/) βœ…
32
+ - [IPHey](https://iphey.com/) βœ…
33
+ - [Browserscan](https://browserscan.net/) βœ…
34
+ - [Pixelscan](https://pixelscan.net/) βœ…
51
35
 
52
36
  ---
53
37
 
54
- ## Patches
38
+ ## ✨ Key Features & Patches
55
39
 
56
- ### [Runtime.enable](https://vanilla.aslushnikov.com/?Runtime.enable) Leak
57
- This is the biggest Patch Patchright uses. To avoid detection by this leak, patchright avoids using [Runtime.enable](https://vanilla.aslushnikov.com/?Runtime.enable) by executing Javascript in (isolated) ExecutionContexts.
40
+ - **CDP Leak Elimination:** Completely eliminates `Runtime.evaluate` leaks, prototype alterations, and console inspection hooks.
41
+ - **Native Turnstile Auto-Solver:** Built-in debounce rate-limiting (4s) and bounding box validation to solve Cloudflare Turnstile without resetting challenges.
42
+ - **Zero-Download System Browser Finder:** Prioritizes local `Brave Browser` -> `Microsoft Edge` -> `Google Chrome` across Windows, macOS, and Linux without downloading 300-400MB browser packages.
43
+ - **Universal Headless / VPS Xvfb Engine:** Runs full desktop headful mode (`headless: false`) on headless Linux servers, Docker, and cloud VMs using a 1920x1080 virtual displayβ€”bypassing headless fingerprinting completely.
44
+ - **Multi-Arch Auto-Installer:** Silently installs Brave across x64, ARM64, and x86 when running on a fresh VM or container without browsers.
45
+ - **Human Action Primitives:**
46
+ - `page.navigate(url, options)`: Resilient navigation with automatic blank retries and status validation.
47
+ - `page.press_key(key, options)`: Natural typing rhythms, modifier combinations (`Shift`, `Control`, `Alt`), and realistic intervals.
48
+ - `page.random_scroll(options)`: Smooth micro-step wheel scrolling with lazy-load image detection and smart direction sensing.
49
+ - **Drop-in Replacement:** Fully compatible with Playwright APIs.
58
50
 
59
- ### [Console.enable](https://vanilla.aslushnikov.com/?Console.enable) Leak
60
- Patchright patches this leak by disabling the Console API all together. This means, console functionality will not work in Patchright. If you really need the console, you might be better off using Javascript loggers, although they also can be easily detected.
51
+ ---
61
52
 
62
- ### Command Flags Leaks
63
- Patchright tweaks the Playwright Default Args to avoid detection by Command Flag Leaks. This (most importantly) affects:
64
- - `--disable-blink-features=AutomationControlled` (added) to avoid navigator.webdriver detection.
65
- - `--enable-automation` (removed) to avoid navigator.webdriver detection.
66
- - `--disable-popup-blocking` (removed) to avoid popup crashing.
67
- - `--disable-component-update` (removed) to avoid detection as a Stealth Driver.
68
- - `--disable-default-apps` (removed) to enable default apps.
69
- - `--disable-extensions` (removed) to enable extensions
53
+ ## πŸ“¦ `patchwright` vs `patchwright-core`
70
54
 
71
- ### General Leaks
72
- Patchright patches some general leaks in the Playwright codebase. This mainly includes poor setups and obvious detection points.
55
+ | Package | Description | Ideal For |
56
+ |---|---|---|
57
+ | **`patchwright`** | Full end-user package with automatic patched Chromium downloader and CLI. | General development, testing, and standard workflows. |
58
+ | **`patchwright-core`** | Pure stealth engine without heavy browser binaries. | Docker containers, VPS, and environments using pre-installed Brave, Edge, or Chrome. |
73
59
 
74
- ### Closed Shadow Roots
75
- Patchright is able to interact with elements in Closed Shadow Roots. Just use normal locators and Patchright will do the rest.
76
- <br/>
77
- Patchright is now also able to use XPaths in Closed Shadow Roots.
60
+ ---
78
61
 
79
- ### Turnstile / Challenge Auto-Solve
80
- Patchright automatically interacts with embedded challenge widgets (Cloudflare Turnstile and the full-page "Just a moment..." challenge) when they appear. Just navigate normally and Patchright will do the rest β€” the widget is located by position and clicked with a real trusted mouse event, the same way a user would click the checkbox. Disable it per context with `turnstile: false`.
62
+ ## πŸš€ Installation & Setup
81
63
 
82
- ### Native Storage Partitioning Preservation
83
- Playwright by default forcibly disables `ThirdPartyStoragePartitioning`, which modern bot-detectors detect immediately via cross-site iframe storage checks. Patchright preserves Chrome's native storage partitioning in the browser switches, ensuring 100% compliance with regular consumer Chrome browsers.
64
+ ### Prerequisites
65
+ - **Node.js:** v18, v20, or v24+
66
+ - **Git**
84
67
 
85
- ### Human Mouse Trajectory Dynamics
86
- Robotic single-step cursor jumps are heavily flagged by advanced behavioral bot detectors. Patchright natively calculates smooth quadratic BΓ©zier curved interpolation trajectories with natural acceleration and deceleration easing curves on all mouse movements, hovers, and clicks. Disable per context with `humanize: false`.
68
+ ### Clone & Install
69
+ ```bash
70
+ git clone https://github.com/codeiva11/patchwright.git
71
+ cd patchwright
72
+ npm install
73
+ ```
87
74
 
88
75
  ---
89
76
 
90
- ## Stealth & Anti-Bot Detection
77
+ ## πŸ› οΈ Patching & Driver Build Commands
91
78
 
92
- With the right setup, Patchright currently is considered undetectable.
93
- Patchright passes:
94
- - [Brotector](https://kaliiiiiiiiii.github.io/brotector/) βœ… (with [CDP-Patches](https://github.com/Kaliiiiiiiiii-Vinyzu/CDP-Patches/))
95
- - [Cloudflare](https://cloudflare.com/) (WAF, Turnstile, Managed Challenge) βœ…
96
- - [Kasada](https://www.kasada.io/) βœ…
97
- - [Akamai](https://www.akamai.com/products/bot-manager/) βœ…
98
- - [Shape/F5](https://www.f5.com/) βœ…
99
- - [Bet365](https://bet365.com/) βœ…
100
- - [Datadome](https://datadome.co/products/bot-protection/) βœ…
101
- - [Fingerprint.com](https://fingerprint.com/products/bot-detection/) βœ…
102
- - [reCAPTCHA v3 Score](https://antcpt.com/score_detector/) (0.9 Human Trust Score) βœ…
103
- - [Rebrowser Bot Detector](https://bot-detector.rebrowser.net/) (Native Storage Partitioning & 0 Leaks) βœ…
104
- - [Pixelscan](https://pixelscan.net/) (Bot Check & Fingerprint Clean) βœ…
105
- - [CreepJS](https://abrahamjuliot.github.io/creepjs/) βœ…
106
- - [Sannysoft](https://bot.sannysoft.com/) (WebDriver Undetected) βœ…
107
- - [Incolumitas](https://bot.incolumitas.com/) βœ…
108
- - [IPHey](https://iphey.com/) βœ…
109
- - [Browserscan](https://browserscan.net/) βœ…
110
-
111
- ### πŸš€ Core Built-in Engine Features
112
- | Built-in Feature | Implementation | Benefit |
113
- |:---|:---|:---|
114
- | **Turnstile & Challenge Auto-Solve** | Built into driver `Page._checkTurnstile` & 1s background loop | Automatically detects and clicks Cloudflare Turnstile & "Just a moment..." challenges using trusted CDP coordinate clicks |
115
- | **Native Storage Partitioning** | Built into `chromiumSwitches.ts` (`feature !== 'ThirdPartyStoragePartitioning'`) | Preserves 3rd-party iframe storage partitioning, passing Rebrowser Bot Detector with 0 detections |
116
- | **Human Mouse Trajectory Dynamics** | Built into `Mouse.move` in `input.ts` | Quadratic BΓ©zier curved trajectory generation with cubic easing on hovers & clicks, defeating behavioral anti-bot models |
117
- | **ReCAPTCHA v3 Trust Score** | Clean execution context isolation without leaked flags | Achieves 0.9 maximum human trust score |
118
- | **Isolated World Execution** | Built into `Frame._isolatedWorld` & execution dispatchers | Arbitrary code execution completely isolated from webpage JS inspection |
119
- | **Automation Flag Sanitization** | `AutomationControlled` disabled, `--enable-automation` removed | Native `navigator.webdriver === false` across all frames and popups |
120
-
121
- ### πŸ§ͺ Verified Detection Test Suite
122
- | Target Test Platform | Detection Type | Status |
123
- |:---|:---|:---|
124
- | **Cloudflare WAF** | Web Application Firewall challenge | βœ… Passed (~19.4s) |
125
- | **Cloudflare Turnstile** | Embedded JS Challenge Widget auto-solve | βœ… Passed (~13.6s) |
126
- | **reCAPTCHA v3 Score** | Google Trust Score test (>= 0.9) | βœ… Passed (~13.2s) |
127
- | **Rebrowser Bot Detector** | Advanced CDP leak & storage partitioning check | βœ… Passed (0 Detections, Score: -1) |
128
- | **Sannysoft WebDriver** | WebDriver/navigator properties check | βœ… Passed |
129
- | **Pixelscan Fingerprint** | Canvas/WebGL fingerprint check | βœ… Passed (No Masking Detected) |
130
- | **Pixelscan Bot Check** | Bot automation framework detection | βœ… Passed |
79
+ | Command | Description |
80
+ |---|---|
81
+ | `npm run patch` | Applies all custom driver patches in `driver_patches/` to Playwright. |
82
+ | `npm run typecheck` | Validates TypeScript types across the entire patch suite (`tsc --noEmit`). |
83
+ | `npm run rebuild` | Rebuilds the local driver package completely from source. |
84
+ | `npm run format:fix` | Formats and aligns code indentation according to Playwright conventions. |
131
85
 
132
86
  ---
133
87
 
134
- ## Bugs
135
- #### Even though we have spent a lot of time to make Patchright as stable as possible, bugs may still occur. If you encounter any bugs, please report them in the [Issues](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright/issues).
136
- #### Patchright is now tested against the Playwright Tests after every release. See [here](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-python/actions/workflows/patchright_tests.yml)
88
+ ## πŸ§ͺ Testing Commands
137
89
 
138
- > [!WARNING]
139
- > Patchright passes most, but not all the Playwright tests. Some bugs are considered impossible to solve, some are just not relevant. See the list of bugs and their explanation [here](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright/issues/30).
90
+ Runs the comprehensive live browser test verifying Rebrowser, Sannysoft, Cloudflare, Turnstile, Pixelscan, CreepJS, DataDome, and enterprise endpoints:
140
91
 
141
- #### Based on the Playwright Tests, we concluded that its highly unlikely that you will be affected by these bugs in regular usecases.
92
+ ```bash
93
+ npm test
94
+ ```
142
95
 
143
- <details>
144
- <summary><b>Init Script Shenanigans</b></summary>
96
+ > **Visual Inspection HUD:** A live green status banner appears at the top right of the browser window (`βœ… PASSED: [Test Name]`) with a 4-second hold between tests.
97
+ >
98
+ > To customize the pause duration (in milliseconds):
99
+ > ```bash
100
+ > # Windows PowerShell
101
+ > $env:INSPECT_DELAY_MS="6000"; npm test
102
+ >
103
+ > # Linux / macOS
104
+ > INSPECT_DELAY_MS=6000 npm test
105
+ > ```
145
106
 
146
- ### Explanation
147
- To be able to use InitScripts without [Runtime.enable](https://vanilla.aslushnikov.com/?Runtime.enable), Patchright uses Playwright Routes to inject JavaScript into HTML requests.
107
+ ---
148
108
 
149
- ### Bugs
150
- Playwright Routes may cause some bugs in other parts of your code. Patchright InitScripts won't cause any bugs that wouldn't be caused by normal Playwright Routes. </br> If you want any of these bugs fixed, you'll have to contact the Playwright team.
109
+ ## πŸ’» Quickstart Examples
151
110
 
152
- ### Leaks
153
- Patchright InitScripts can be detected by Timing Attacks. However, no antibot currently checks for this kind of Timing Attack and they probably won't for a good amount of time. </br> We consider them not to be a big risk of detection.
111
+ ### 1. Zero-Download Universal Launcher (Auto-detects Brave/Edge/Chrome or Xvfb)
154
112
 
155
- </details>
113
+ ```javascript
114
+ import { chromium } from 'patchwright-core';
115
+ import { launchStealthBrowser, enhancePage } from './helpers.mjs';
156
116
 
157
- ---
117
+ // Automatically finds Brave -> Edge -> Chrome, starts Xvfb on Linux VPS, and launches in stealth
118
+ const { browser, browserInfo } = await launchStealthBrowser(chromium, {
119
+ headless: false // Runs headful over virtual display on Linux VPS
120
+ });
158
121
 
159
- ### TODO
160
- - [x] Implement Option to choose Execution Context (Main/Isolated).
161
- - [x] Fix Fixable Bugs.
162
- - [x] Implement .patch Updater to easily show Patchright's patches.
163
- - [x] Setup Automated Testing on new Release.
164
- - [x] Implement Patchright on .NET.
165
- - [ ] Implement Patchright on Java.
122
+ console.log(`πŸš€ Running on ${browserInfo?.name || 'Chromium'}`);
166
123
 
167
- ---
124
+ const rawPage = await browser.newPage();
125
+ const page = enhancePage(rawPage);
168
126
 
169
- ## Development
127
+ await page.navigate('https://bot.sannysoft.com/');
128
+ await page.random_scroll({ direction: 'smart', smooth: true });
170
129
 
171
- Deployment of new Patchright versions are automatic, but bugs due to Playwright codebase changes may occur. Fixes for these bugs might take a few days to be released.
130
+ await browser.close();
131
+ ```
172
132
 
173
- ---
133
+ ### 2. Standard Usage with Human Primitives
174
134
 
175
- ## Copyright and License
176
- Β© [Vinyzu](https://github.com/Vinyzu/)
135
+ ```javascript
136
+ import { chromium } from 'patchwright';
137
+ import { enhancePage } from './helpers.mjs';
177
138
 
178
- Patchright is licensed [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/)
139
+ const browser = await chromium.launch({
140
+ headless: false,
141
+ args: ['--no-sandbox', '--disable-blink-features=AutomationControlled']
142
+ });
179
143
 
180
- [Some Parts](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright/blob/10c5a090e9a1dcd2107c253d65b3d8b27d0670a9/driver_patches/framesPatch.ts#L156-L171) of the Codebase are inspired by [Driverless](https://github.com/kaliiiiiiiiii/Selenium-Driverless).
181
- Thanks to [Nick Webson](https://github.com/rebrowser/rebrowser-patches) for the idea of .patch-File Documentation.
144
+ const context = await browser.newContext();
145
+ const rawPage = await context.newPage();
182
146
 
183
- ---
147
+ // Enhance page with native humanized action helpers
148
+ const page = enhancePage(rawPage);
184
149
 
185
- ## Disclaimer
150
+ // 1. Resilient navigation
151
+ await page.navigate('https://bot.sannysoft.com/');
186
152
 
187
- This repository is provided for **educational purposes only**. \
188
- No warranties are provided regarding accuracy, completeness, or suitability for any purpose. **Use at your own risk**β€”the authors and maintainers assume **no liability** for **any damages**, **legal issues**, or **warranty breaches** resulting from use, modification, or distribution of this code.\
189
- **Any misuse or legal violations are the sole responsibility of the user**.
153
+ // 2. Humanized scrolling
154
+ await page.random_scroll({ direction: 'smart', smooth: true });
190
155
 
191
- ---
156
+ // 3. Human-like key presses with modifiers
157
+ await page.press_key('a');
158
+ await page.press_key('c', { modifiers: ['Shift'] });
159
+
160
+ await browser.close();
161
+ ```
192
162
 
193
- ## Authors
163
+ ---
194
164
 
195
- #### Active Maintainer: [Vinyzu](https://github.com/Vinyzu/) </br> Co-Maintainer: [Kaliiiiiiiiii](https://github.com/kaliiiiiiiiii/)
165
+ ## πŸ“„ License
166
+ This project is licensed under the [Apache License 2.0](./LICENSE).