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 +116 -145
- package/helpers.mjs +387 -0
- package/lib/cli/testActions.js +0 -1
- package/lib/common/index.js +142 -65
- package/lib/common/index.js.txt +7 -7
- package/lib/matchers/expect.js +56 -30
- package/lib/matchers/expect.js.LICENSE +3 -3
- package/lib/matchers/expect.js.txt +4 -4
- package/lib/mcp/test/testContext.js +2 -8
- package/lib/runner/index.js +500 -401
- package/lib/runner/index.js.txt +24 -23
- package/lib/transform/babelBundle.js +81 -57
- package/lib/transform/babelBundle.js.txt +2 -2
- package/lib/transform/esmLoader.js +361 -163
- package/lib/transform/esmLoader.js.LICENSE +3 -3
- package/lib/transform/esmLoader.js.txt +9 -8
- package/lib/worker/workerProcessEntry.js +6 -14
- package/lib/worker/workerProcessEntry.js.txt +2 -2
- package/package.json +6 -5
- package/types/test.d.ts +365 -41
- package/types/testReporter.d.ts +22 -2
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://
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
<
|
|
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
|
-
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## π‘οΈ Anti-Bot & Detection Bypass Matrix
|
|
45
19
|
|
|
46
|
-
|
|
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
|
-
|
|
50
|
-
|
|
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
|
-
|
|
57
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
72
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
83
|
-
|
|
64
|
+
### Prerequisites
|
|
65
|
+
- **Node.js:** v18, v20, or v24+
|
|
66
|
+
- **Git**
|
|
84
67
|
|
|
85
|
-
###
|
|
86
|
-
|
|
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
|
-
##
|
|
77
|
+
## π οΈ Patching & Driver Build Commands
|
|
91
78
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
92
|
+
```bash
|
|
93
|
+
npm test
|
|
94
|
+
```
|
|
142
95
|
|
|
143
|
-
|
|
144
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
127
|
+
await page.navigate('https://bot.sannysoft.com/');
|
|
128
|
+
await page.random_scroll({ direction: 'smart', smooth: true });
|
|
170
129
|
|
|
171
|
-
|
|
130
|
+
await browser.close();
|
|
131
|
+
```
|
|
172
132
|
|
|
173
|
-
|
|
133
|
+
### 2. Standard Usage with Human Primitives
|
|
174
134
|
|
|
175
|
-
|
|
176
|
-
|
|
135
|
+
```javascript
|
|
136
|
+
import { chromium } from 'patchwright';
|
|
137
|
+
import { enhancePage } from './helpers.mjs';
|
|
177
138
|
|
|
178
|
-
|
|
139
|
+
const browser = await chromium.launch({
|
|
140
|
+
headless: false,
|
|
141
|
+
args: ['--no-sandbox', '--disable-blink-features=AutomationControlled']
|
|
142
|
+
});
|
|
179
143
|
|
|
180
|
-
|
|
181
|
-
|
|
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
|
-
|
|
150
|
+
// 1. Resilient navigation
|
|
151
|
+
await page.navigate('https://bot.sannysoft.com/');
|
|
186
152
|
|
|
187
|
-
|
|
188
|
-
|
|
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
|
-
|
|
163
|
+
---
|
|
194
164
|
|
|
195
|
-
|
|
165
|
+
## π License
|
|
166
|
+
This project is licensed under the [Apache License 2.0](./LICENSE).
|