@namzu/browser 0.1.0
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/CHANGELOG.md +32 -0
- package/LICENSE.md +110 -0
- package/README.md +149 -0
- package/dist/classifier.d.ts +70 -0
- package/dist/classifier.d.ts.map +1 -0
- package/dist/classifier.js +147 -0
- package/dist/classifier.js.map +1 -0
- package/dist/detect.d.ts +126 -0
- package/dist/detect.d.ts.map +1 -0
- package/dist/detect.js +282 -0
- package/dist/detect.js.map +1 -0
- package/dist/errors.d.ts +64 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +99 -0
- package/dist/errors.js.map +1 -0
- package/dist/host.d.ts +167 -0
- package/dist/host.d.ts.map +1 -0
- package/dist/host.js +1024 -0
- package/dist/host.js.map +1 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +10 -0
- package/dist/index.js.map +1 -0
- package/dist/page-scripts.d.ts +51 -0
- package/dist/page-scripts.d.ts.map +1 -0
- package/dist/page-scripts.js +123 -0
- package/dist/page-scripts.js.map +1 -0
- package/dist/policy.d.ts +61 -0
- package/dist/policy.d.ts.map +1 -0
- package/dist/policy.js +150 -0
- package/dist/policy.js.map +1 -0
- package/dist/profiles.d.ts +107 -0
- package/dist/profiles.d.ts.map +1 -0
- package/dist/profiles.js +312 -0
- package/dist/profiles.js.map +1 -0
- package/dist/relay.d.ts +27 -0
- package/dist/relay.d.ts.map +1 -0
- package/dist/relay.js +69 -0
- package/dist/relay.js.map +1 -0
- package/dist/snapshot.d.ts +101 -0
- package/dist/snapshot.d.ts.map +1 -0
- package/dist/snapshot.js +265 -0
- package/dist/snapshot.js.map +1 -0
- package/dist/windows-bridge-script.d.ts +29 -0
- package/dist/windows-bridge-script.d.ts.map +1 -0
- package/dist/windows-bridge-script.js +161 -0
- package/dist/windows-bridge-script.js.map +1 -0
- package/dist/windows-bridge.d.ts +120 -0
- package/dist/windows-bridge.d.ts.map +1 -0
- package/dist/windows-bridge.js +267 -0
- package/dist/windows-bridge.js.map +1 -0
- package/dist/windows-engine.d.ts +55 -0
- package/dist/windows-engine.d.ts.map +1 -0
- package/dist/windows-engine.js +154 -0
- package/dist/windows-engine.js.map +1 -0
- package/dist/wsl.d.ts +52 -0
- package/dist/wsl.d.ts.map +1 -0
- package/dist/wsl.js +134 -0
- package/dist/wsl.js.map +1 -0
- package/package.json +74 -0
- package/src/classifier.ts +191 -0
- package/src/detect.ts +432 -0
- package/src/errors.ts +121 -0
- package/src/host.ts +1217 -0
- package/src/index.ts +79 -0
- package/src/page-scripts.ts +154 -0
- package/src/policy.ts +190 -0
- package/src/profiles.ts +373 -0
- package/src/relay.ts +101 -0
- package/src/snapshot.ts +317 -0
- package/src/windows-bridge-script.ts +160 -0
- package/src/windows-bridge.ts +358 -0
- package/src/windows-engine.ts +208 -0
- package/src/wsl.ts +155 -0
package/src/host.ts
ADDED
|
@@ -0,0 +1,1217 @@
|
|
|
1
|
+
import { randomBytes } from 'node:crypto'
|
|
2
|
+
import type {
|
|
3
|
+
BrowserActAction,
|
|
4
|
+
BrowserCallOptions,
|
|
5
|
+
BrowserCapabilities,
|
|
6
|
+
BrowserHost,
|
|
7
|
+
BrowserObserveAction,
|
|
8
|
+
BrowserPageInfo,
|
|
9
|
+
BrowserRefDescription,
|
|
10
|
+
BrowserResult,
|
|
11
|
+
BrowserSessionInfo,
|
|
12
|
+
BrowserSnapshot,
|
|
13
|
+
BrowserTabInfo,
|
|
14
|
+
} from '@namzu/sdk'
|
|
15
|
+
import { canonicalizeBrowserOrigin, canonicalizeBrowserUrl, resolveNamzuHome } from '@namzu/sdk'
|
|
16
|
+
import {
|
|
17
|
+
type BrowserContext,
|
|
18
|
+
type Dialog,
|
|
19
|
+
type Locator,
|
|
20
|
+
type Page,
|
|
21
|
+
type Route,
|
|
22
|
+
chromium,
|
|
23
|
+
} from 'playwright-core'
|
|
24
|
+
import {
|
|
25
|
+
type BrowserHumanClassifierOptions,
|
|
26
|
+
classifyHumanRequired,
|
|
27
|
+
isCredentialField,
|
|
28
|
+
} from './classifier.js'
|
|
29
|
+
import {
|
|
30
|
+
type BrowserEnginePlan,
|
|
31
|
+
type BrowserEngineSetting,
|
|
32
|
+
type BrowserHeadlessSetting,
|
|
33
|
+
type BrowserRunMode,
|
|
34
|
+
type LocalBrowserPlan,
|
|
35
|
+
type WindowsCdpBrowserPlan,
|
|
36
|
+
detectBrowserEnvironment,
|
|
37
|
+
runnableBrowserPlan,
|
|
38
|
+
} from './detect.js'
|
|
39
|
+
import {
|
|
40
|
+
BrowserHumanRequiredError,
|
|
41
|
+
BrowserOriginMismatchError,
|
|
42
|
+
BrowserOutcomeUnknownError,
|
|
43
|
+
BrowserSiteDeniedError,
|
|
44
|
+
BrowserStaleRefError,
|
|
45
|
+
BrowserUnavailableError,
|
|
46
|
+
ProfileBusyError,
|
|
47
|
+
} from './errors.js'
|
|
48
|
+
import {
|
|
49
|
+
type ElementFieldFacts,
|
|
50
|
+
countCredentialFields,
|
|
51
|
+
fieldFacts,
|
|
52
|
+
focusedFieldFacts,
|
|
53
|
+
} from './page-scripts.js'
|
|
54
|
+
import { BrowserSitePolicy, type BrowserSiteRules, DEFAULT_BROWSER_SITE_RULES } from './policy.js'
|
|
55
|
+
import {
|
|
56
|
+
type BrowserLease,
|
|
57
|
+
BrowserLeaseStore,
|
|
58
|
+
BrowserProfileError,
|
|
59
|
+
BrowserProfileStore,
|
|
60
|
+
DEFAULT_BROWSER_PROFILE,
|
|
61
|
+
} from './profiles.js'
|
|
62
|
+
import {
|
|
63
|
+
PLAYWRIGHT_CORE_VERSION,
|
|
64
|
+
SnapshotPager,
|
|
65
|
+
captureAriaTree,
|
|
66
|
+
locateRef,
|
|
67
|
+
renderAriaTree,
|
|
68
|
+
} from './snapshot.js'
|
|
69
|
+
import { WindowsBridgeError } from './windows-bridge.js'
|
|
70
|
+
import { type WindowsBrowserConnection, connectWindowsBrowser } from './windows-engine.js'
|
|
71
|
+
|
|
72
|
+
export interface PlaywrightBrowserHostOptions {
|
|
73
|
+
/** Profile to run under. Default `default`. Chosen by the operator, never by the model. */
|
|
74
|
+
readonly profile?: string
|
|
75
|
+
/** `NAMZU_HOME`. Default: resolved from the environment when the browser first starts. */
|
|
76
|
+
readonly home?: string
|
|
77
|
+
/** Names this host's lease on the profile. Default: random. */
|
|
78
|
+
readonly sessionId?: string
|
|
79
|
+
/** The engine plan. Default: {@link detectBrowserEnvironment} over `env` and `platform`. */
|
|
80
|
+
readonly plan?: BrowserEnginePlan
|
|
81
|
+
readonly env?: NodeJS.ProcessEnv
|
|
82
|
+
readonly platform?: NodeJS.Platform
|
|
83
|
+
readonly engine?: BrowserEngineSetting
|
|
84
|
+
readonly headless?: BrowserHeadlessSetting
|
|
85
|
+
readonly mode?: BrowserRunMode
|
|
86
|
+
/** Site rules for the checks after the fact. Default `{ '*': 'ask' }`. */
|
|
87
|
+
readonly sites?: BrowserSiteRules
|
|
88
|
+
/**
|
|
89
|
+
* Leave the browser running when this host is disposed. For the Windows
|
|
90
|
+
* engine this also leaves it running if this process dies.
|
|
91
|
+
*/
|
|
92
|
+
readonly keepOpen?: boolean
|
|
93
|
+
/** Default 30 000. */
|
|
94
|
+
readonly navigationTimeoutMs?: number
|
|
95
|
+
/** Default 10 000. */
|
|
96
|
+
readonly actionTimeoutMs?: number
|
|
97
|
+
/** Snapshot page size in characters. Default and ceiling 20 000. */
|
|
98
|
+
readonly snapshotMaxChars?: number
|
|
99
|
+
/** A browser binary to launch instead of the plan's. */
|
|
100
|
+
readonly executablePath?: string
|
|
101
|
+
/** More sign-in addresses for the classifier. */
|
|
102
|
+
readonly signInAddresses?: BrowserHumanClassifierOptions['signInAddresses']
|
|
103
|
+
/** The command that opens a visible window for signing in. Default `namzu browser login <profile> <url>`. */
|
|
104
|
+
readonly loginCommand?: (profile: string, url: string) => string
|
|
105
|
+
/** Windows engine: how long starting and connecting to the browser may take. Default 60 000. */
|
|
106
|
+
readonly windowsLaunchTimeoutMs?: number
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
interface Tab {
|
|
110
|
+
readonly id: string
|
|
111
|
+
readonly page: Page
|
|
112
|
+
/** HTTP status of the main document's last response. */
|
|
113
|
+
status?: number
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
interface PendingDialog {
|
|
117
|
+
readonly tab: Tab
|
|
118
|
+
readonly dialog: Dialog
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const DEFAULT_NAVIGATION_TIMEOUT_MS = 30_000
|
|
122
|
+
const DEFAULT_ACTION_TIMEOUT_MS = 10_000
|
|
123
|
+
/** How long a history move waits for the document after it committed. */
|
|
124
|
+
const HISTORY_LOAD_WAIT_MS = 5_000
|
|
125
|
+
const SNAPSHOT_PAGE_MAX = 20_000
|
|
126
|
+
/** How long the host lets events (popups, downloads, dialogs) arrive after an action. */
|
|
127
|
+
const EVENT_SETTLE_MS = 150
|
|
128
|
+
/** Smallest frame that can hold a CAPTCHA a person is meant to solve. */
|
|
129
|
+
const CAPTCHA_FRAME_MIN_PX = 30
|
|
130
|
+
|
|
131
|
+
function firstLine(error: unknown): string {
|
|
132
|
+
const text = error instanceof Error ? error.message : String(error)
|
|
133
|
+
return (text.split('\n')[0] ?? '').slice(0, 300)
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** The page's origin as the header shows it: canonical, or `null` for anything that is not a web page. */
|
|
137
|
+
function originOf(url: string): string {
|
|
138
|
+
if (url === 'about:blank' || url === '') return 'null'
|
|
139
|
+
const verdict = canonicalizeBrowserUrl(url)
|
|
140
|
+
if (verdict.ok) return verdict.url === 'about:blank' ? 'null' : verdict.origin
|
|
141
|
+
return 'null'
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function withoutQuery(url: string): string {
|
|
145
|
+
try {
|
|
146
|
+
const parsed = new URL(url)
|
|
147
|
+
return `${parsed.origin}${parsed.pathname}`
|
|
148
|
+
} catch {
|
|
149
|
+
return url
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function pngSize(data: Uint8Array): { width: number; height: number } {
|
|
154
|
+
if (data.length < 24) return { width: 0, height: 0 }
|
|
155
|
+
const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
|
|
156
|
+
return { width: view.getUint32(16), height: view.getUint32(20) }
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function quoteShort(value: string, max = 80): string {
|
|
160
|
+
const flat = value.replace(/\s+/g, ' ').trim()
|
|
161
|
+
return JSON.stringify(flat.length > max ? `${flat.slice(0, max - 1)}…` : flat)
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** Keys that type nothing: allowed while a credential field has focus. */
|
|
165
|
+
const NON_TYPING_KEYS = new Set(['Tab', 'Shift+Tab', 'Escape', 'Enter'])
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* A {@link BrowserHost} that runs Chromium (or an installed Chrome or Edge)
|
|
169
|
+
* in this process with Playwright, on a persistent profile. Inside WSL it
|
|
170
|
+
* drives the Windows Chrome or Edge instead, through the PowerShell bridge
|
|
171
|
+
* (`windows-engine.ts`).
|
|
172
|
+
*
|
|
173
|
+
* Nothing starts at construction: the browser is launched by the first call
|
|
174
|
+
* that needs it, so mounting the tools costs nothing until the model uses
|
|
175
|
+
* them.
|
|
176
|
+
*
|
|
177
|
+
* What it enforces, whatever the gate allowed:
|
|
178
|
+
*
|
|
179
|
+
* - every `browser_act` call's `origin` equals the live page's, checked
|
|
180
|
+
* immediately before acting;
|
|
181
|
+
* - a page that a navigation, redirect, script or popup lands on must be
|
|
182
|
+
* allowed by the site rules at `read` or `act`, or be an address the caller
|
|
183
|
+
* asked to open this session, or `about:blank`. A top-level request to
|
|
184
|
+
* anything else is blocked before it is sent; a redirect is caught when it
|
|
185
|
+
* lands, and the tab is cleared to `about:blank`;
|
|
186
|
+
* - acting needs the live origin at `ask` or `act`;
|
|
187
|
+
* - a sign-in, second factor, CAPTCHA, bot wall or HTTP credential prompt
|
|
188
|
+
* stops the call with `browser_human_required`;
|
|
189
|
+
* - nothing is ever typed into a password or one-time-code field;
|
|
190
|
+
* - downloads are cancelled and reported; a leave-page prompt is answered so
|
|
191
|
+
* navigation proceeds; other dialogs wait for `browser_act dialog`.
|
|
192
|
+
*/
|
|
193
|
+
export class PlaywrightBrowserHost implements BrowserHost {
|
|
194
|
+
readonly id: string
|
|
195
|
+
readonly capabilities: BrowserCapabilities
|
|
196
|
+
readonly plan: BrowserEnginePlan
|
|
197
|
+
readonly profile: string
|
|
198
|
+
|
|
199
|
+
private readonly options: PlaywrightBrowserHostOptions
|
|
200
|
+
private readonly policy: BrowserSitePolicy
|
|
201
|
+
private readonly sessionId: string
|
|
202
|
+
private readonly pager: SnapshotPager
|
|
203
|
+
|
|
204
|
+
private context: BrowserContext | undefined
|
|
205
|
+
private windows: WindowsBrowserConnection | undefined
|
|
206
|
+
private launching: Promise<BrowserContext> | undefined
|
|
207
|
+
private lease: BrowserLease | undefined
|
|
208
|
+
private readonly tabs = new Map<string, Tab>()
|
|
209
|
+
private readonly tabOf = new WeakMap<Page, Tab>()
|
|
210
|
+
private tabCounter = 0
|
|
211
|
+
private activeTabId: string | undefined
|
|
212
|
+
private ownPageOpening = false
|
|
213
|
+
private pendingDialog: PendingDialog | undefined
|
|
214
|
+
private readonly notes: string[] = []
|
|
215
|
+
private readonly blanking = new Set<Promise<unknown>>()
|
|
216
|
+
private refs: ReadonlyMap<string, BrowserRefDescription> = new Map()
|
|
217
|
+
|
|
218
|
+
constructor(options: PlaywrightBrowserHostOptions = {}) {
|
|
219
|
+
this.options = options
|
|
220
|
+
this.profile = options.profile ?? DEFAULT_BROWSER_PROFILE
|
|
221
|
+
this.sessionId = options.sessionId ?? `s${randomBytes(6).toString('hex')}`
|
|
222
|
+
this.policy = new BrowserSitePolicy(options.sites ?? DEFAULT_BROWSER_SITE_RULES)
|
|
223
|
+
const detected =
|
|
224
|
+
options.plan ??
|
|
225
|
+
detectBrowserEnvironment(
|
|
226
|
+
options.env ?? process.env,
|
|
227
|
+
options.platform ?? process.platform,
|
|
228
|
+
undefined,
|
|
229
|
+
{
|
|
230
|
+
...(options.engine ? { engine: options.engine } : {}),
|
|
231
|
+
...(options.headless ? { headless: options.headless } : {}),
|
|
232
|
+
...(options.mode ? { mode: options.mode } : {}),
|
|
233
|
+
},
|
|
234
|
+
)
|
|
235
|
+
this.plan = runnableBrowserPlan(detected)
|
|
236
|
+
const pageChars = Math.min(options.snapshotMaxChars ?? SNAPSHOT_PAGE_MAX, SNAPSHOT_PAGE_MAX)
|
|
237
|
+
this.pager = new SnapshotPager(pageChars)
|
|
238
|
+
this.id = `playwright-${this.plan.engine === 'local' ? this.plan.browser : this.plan.engine}`
|
|
239
|
+
this.capabilities = {
|
|
240
|
+
engine: this.plan.engine === 'local' ? `local-${this.plan.browser}` : this.plan.engine,
|
|
241
|
+
headless: this.plan.headless,
|
|
242
|
+
screenshot: true,
|
|
243
|
+
upload: true,
|
|
244
|
+
snapshotMaxChars: pageChars,
|
|
245
|
+
...(this.plan.unavailableReason !== undefined
|
|
246
|
+
? { unavailableReason: this.plan.unavailableReason }
|
|
247
|
+
: {}),
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/** Warnings from engine detection, for the operator. */
|
|
252
|
+
get warnings(): readonly string[] {
|
|
253
|
+
return this.plan.warnings
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/** Whether the browser is running now. */
|
|
257
|
+
get running(): boolean {
|
|
258
|
+
return this.context !== undefined
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
// -------------------------------------------------------------------------
|
|
262
|
+
// Lifecycle
|
|
263
|
+
// -------------------------------------------------------------------------
|
|
264
|
+
|
|
265
|
+
private async ensureContext(): Promise<BrowserContext> {
|
|
266
|
+
if (this.context) return this.context
|
|
267
|
+
if (!this.launching) {
|
|
268
|
+
this.launching = this.launch().finally(() => {
|
|
269
|
+
this.launching = undefined
|
|
270
|
+
})
|
|
271
|
+
}
|
|
272
|
+
return this.launching
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
private async launch(): Promise<BrowserContext> {
|
|
276
|
+
const plan = this.plan
|
|
277
|
+
if (plan.unavailableReason !== undefined)
|
|
278
|
+
throw new BrowserUnavailableError(plan.unavailableReason)
|
|
279
|
+
const context =
|
|
280
|
+
plan.engine === 'local' ? await this.launchLocal(plan) : await this.launchWindows(plan)
|
|
281
|
+
this.context = context
|
|
282
|
+
context.setDefaultTimeout(this.options.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS)
|
|
283
|
+
context.setDefaultNavigationTimeout(
|
|
284
|
+
this.options.navigationTimeoutMs ?? DEFAULT_NAVIGATION_TIMEOUT_MS,
|
|
285
|
+
)
|
|
286
|
+
context.on('page', (page) => this.adopt(page))
|
|
287
|
+
context.on('close', () => this.forget(context))
|
|
288
|
+
context.browser()?.on('disconnected', () => this.forget(context))
|
|
289
|
+
// Before a top-level request leaves: a link, script or popup heading for
|
|
290
|
+
// a site the rules do not allow is stopped here, so its address (and
|
|
291
|
+
// anything a page smuggled into it) never reaches the network.
|
|
292
|
+
await context.route(
|
|
293
|
+
() => true,
|
|
294
|
+
(route) => this.screen(route),
|
|
295
|
+
)
|
|
296
|
+
for (const page of context.pages()) this.adopt(page, false)
|
|
297
|
+
return context
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
private home(): string {
|
|
301
|
+
return this.options.home ?? resolveNamzuHome({ env: this.options.env ?? process.env })
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
private async launchLocal(plan: LocalBrowserPlan): Promise<BrowserContext> {
|
|
305
|
+
const home = this.home()
|
|
306
|
+
const profiles = new BrowserProfileStore(home)
|
|
307
|
+
const descriptor = profiles.ensureLocal(this.profile, plan.browser)
|
|
308
|
+
const lease = new BrowserLeaseStore(home).acquire(this.profile, this.sessionId, {
|
|
309
|
+
exclusive: true,
|
|
310
|
+
})
|
|
311
|
+
let context: BrowserContext
|
|
312
|
+
try {
|
|
313
|
+
context = await chromium.launchPersistentContext(descriptor.userDataDir, {
|
|
314
|
+
headless: plan.headless,
|
|
315
|
+
...(plan.channel ? { channel: plan.channel } : {}),
|
|
316
|
+
...(this.options.executablePath ? { executablePath: this.options.executablePath } : {}),
|
|
317
|
+
acceptDownloads: false,
|
|
318
|
+
// The terminal owns Ctrl-C; the browser closes with the host.
|
|
319
|
+
handleSIGINT: false,
|
|
320
|
+
...(plan.headless ? {} : { viewport: null }),
|
|
321
|
+
timeout: 60_000,
|
|
322
|
+
})
|
|
323
|
+
} catch (error) {
|
|
324
|
+
lease.release()
|
|
325
|
+
throw this.launchError(error)
|
|
326
|
+
}
|
|
327
|
+
this.lease = lease
|
|
328
|
+
return context
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
/**
|
|
332
|
+
* The Windows browser, through the PowerShell bridge. The profile lives on
|
|
333
|
+
* the Windows side; its descriptor here records where. Leases are shared:
|
|
334
|
+
* every namzu process on the profile drives the same browser, and the
|
|
335
|
+
* last one to let go closes it.
|
|
336
|
+
*/
|
|
337
|
+
private async launchWindows(plan: WindowsCdpBrowserPlan): Promise<BrowserContext> {
|
|
338
|
+
const home = this.home()
|
|
339
|
+
const profiles = new BrowserProfileStore(home)
|
|
340
|
+
const existing = profiles.get(this.profile)
|
|
341
|
+
if (existing && existing.engine !== 'windows-cdp') {
|
|
342
|
+
throw new BrowserProfileError(
|
|
343
|
+
`Browser profile "${this.profile}" belongs to the ${existing.engine} engine, not the Windows browser. Use another profile name.`,
|
|
344
|
+
)
|
|
345
|
+
}
|
|
346
|
+
if (existing && existing.browser !== plan.browser) {
|
|
347
|
+
throw new BrowserProfileError(
|
|
348
|
+
`Browser profile "${this.profile}" was made with ${existing.browser}, and this run would use ${plan.browser}. Use another profile name, or the browser the profile was made with.`,
|
|
349
|
+
)
|
|
350
|
+
}
|
|
351
|
+
const lease = new BrowserLeaseStore(home).acquire(this.profile, this.sessionId)
|
|
352
|
+
let connection: WindowsBrowserConnection
|
|
353
|
+
try {
|
|
354
|
+
connection = await connectWindowsBrowser({
|
|
355
|
+
plan,
|
|
356
|
+
profile: this.profile,
|
|
357
|
+
...(existing ? { userDataDir: existing.userDataDir } : {}),
|
|
358
|
+
closeOnExit: !this.options.keepOpen,
|
|
359
|
+
env: this.options.env ?? process.env,
|
|
360
|
+
...(this.options.windowsLaunchTimeoutMs !== undefined
|
|
361
|
+
? { timeoutMs: this.options.windowsLaunchTimeoutMs }
|
|
362
|
+
: {}),
|
|
363
|
+
onDownloadRefused: (name) => {
|
|
364
|
+
this.notes.push(
|
|
365
|
+
`A download of ${quoteShort(name)} was cancelled: the browser does not download files.`,
|
|
366
|
+
)
|
|
367
|
+
},
|
|
368
|
+
})
|
|
369
|
+
} catch (error) {
|
|
370
|
+
lease.release()
|
|
371
|
+
throw this.windowsLaunchError(plan, error)
|
|
372
|
+
}
|
|
373
|
+
try {
|
|
374
|
+
profiles.ensureWindows(this.profile, plan.browser, connection.userDataDir)
|
|
375
|
+
} catch (error) {
|
|
376
|
+
lease.release()
|
|
377
|
+
await connection.detach().catch(() => undefined)
|
|
378
|
+
throw error
|
|
379
|
+
}
|
|
380
|
+
this.lease = lease
|
|
381
|
+
this.windows = connection
|
|
382
|
+
return connection.context
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
private windowsLaunchError(plan: WindowsCdpBrowserPlan, error: unknown): Error {
|
|
386
|
+
const name = plan.browser === 'chrome' ? 'Google Chrome' : 'Microsoft Edge'
|
|
387
|
+
if (error instanceof WindowsBridgeError) {
|
|
388
|
+
if (error.code === 'browser-exited') return new ProfileBusyError(this.profile, [])
|
|
389
|
+
return new BrowserUnavailableError(
|
|
390
|
+
`The Windows ${name} could not be started from WSL: ${error.message}`,
|
|
391
|
+
)
|
|
392
|
+
}
|
|
393
|
+
return new BrowserUnavailableError(
|
|
394
|
+
`The Windows ${name} was started but could not be driven from WSL: ${firstLine(error)}`,
|
|
395
|
+
)
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
private launchError(error: unknown): Error {
|
|
399
|
+
const text = error instanceof Error ? error.message : String(error)
|
|
400
|
+
if (
|
|
401
|
+
/Executable doesn't exist|executable doesn't exist|browserType\.launch.*not found/i.test(text)
|
|
402
|
+
) {
|
|
403
|
+
const which =
|
|
404
|
+
this.plan.engine === 'local' && this.plan.browser !== 'chromium'
|
|
405
|
+
? `The installed ${this.plan.browser === 'chrome' ? 'Google Chrome' : 'Microsoft Edge'} was not found where it should be.`
|
|
406
|
+
: `Playwright's Chromium for playwright-core ${PLAYWRIGHT_CORE_VERSION} is not installed.`
|
|
407
|
+
return new BrowserUnavailableError(
|
|
408
|
+
`${which} Run \`namzu browser install\` (or \`npx playwright-core@${PLAYWRIGHT_CORE_VERSION} install chromium\`).`,
|
|
409
|
+
)
|
|
410
|
+
}
|
|
411
|
+
if (/ProcessSingleton|SingletonLock|already in use|profile.*in use/i.test(text)) {
|
|
412
|
+
return new ProfileBusyError(this.profile, [])
|
|
413
|
+
}
|
|
414
|
+
if (/Missing X server|cannot open display|\$DISPLAY/i.test(text)) {
|
|
415
|
+
return new BrowserUnavailableError(
|
|
416
|
+
'The browser needs a display for a visible window and could not open one. Run headless, or under a desktop session.',
|
|
417
|
+
)
|
|
418
|
+
}
|
|
419
|
+
return new BrowserUnavailableError(`The browser could not start: ${firstLine(error)}`)
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
private forget(context: BrowserContext): void {
|
|
423
|
+
if (this.context !== context) return
|
|
424
|
+
this.context = undefined
|
|
425
|
+
const windows = this.windows
|
|
426
|
+
this.windows = undefined
|
|
427
|
+
if (windows) void windows.detach().catch(() => undefined)
|
|
428
|
+
this.tabs.clear()
|
|
429
|
+
this.activeTabId = undefined
|
|
430
|
+
this.pendingDialog = undefined
|
|
431
|
+
this.refs = new Map()
|
|
432
|
+
this.lease?.release()
|
|
433
|
+
this.lease = undefined
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
async initialize(): Promise<void> {
|
|
437
|
+
// Deliberately nothing: the browser starts on first use.
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* Release this host's lease. The browser closes when that was the last
|
|
442
|
+
* lease on the profile, unless `keepOpen` was set.
|
|
443
|
+
*/
|
|
444
|
+
async dispose(): Promise<void> {
|
|
445
|
+
const lease = this.lease
|
|
446
|
+
this.lease = undefined
|
|
447
|
+
const last = lease ? lease.release().last : true
|
|
448
|
+
if (last && !this.options.keepOpen) {
|
|
449
|
+
await this.close()
|
|
450
|
+
return
|
|
451
|
+
}
|
|
452
|
+
// The Windows browser is shared with every other holder of the
|
|
453
|
+
// profile, or is to stay open: disconnect without closing it.
|
|
454
|
+
const context = this.context
|
|
455
|
+
const windows = this.windows
|
|
456
|
+
if (!context || !windows) return
|
|
457
|
+
this.windows = undefined
|
|
458
|
+
this.forget(context)
|
|
459
|
+
await windows.detach().catch(() => undefined)
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
/** Close the browser now, whatever the leases say. */
|
|
463
|
+
async close(): Promise<void> {
|
|
464
|
+
const context = this.context
|
|
465
|
+
if (!context) return
|
|
466
|
+
const windows = this.windows
|
|
467
|
+
this.windows = undefined
|
|
468
|
+
this.forget(context)
|
|
469
|
+
if (windows) await windows.close().catch(() => undefined)
|
|
470
|
+
else await context.close().catch(() => undefined)
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
// -------------------------------------------------------------------------
|
|
474
|
+
// Tabs and events
|
|
475
|
+
// -------------------------------------------------------------------------
|
|
476
|
+
|
|
477
|
+
private adopt(page: Page, announce = true): Tab {
|
|
478
|
+
const known = this.tabOf.get(page)
|
|
479
|
+
if (known) return known
|
|
480
|
+
this.tabCounter += 1
|
|
481
|
+
const tab: Tab = { id: `t${this.tabCounter}`, page }
|
|
482
|
+
this.tabs.set(tab.id, tab)
|
|
483
|
+
this.tabOf.set(page, tab)
|
|
484
|
+
if (this.activeTabId === undefined) this.activeTabId = tab.id
|
|
485
|
+
if (announce && !this.ownPageOpening) {
|
|
486
|
+
this.notes.push(
|
|
487
|
+
`The page opened a new tab, ${tab.id}; it is not the active tab. Use tabs list or select to look at it.`,
|
|
488
|
+
)
|
|
489
|
+
}
|
|
490
|
+
page.on('framenavigated', (frame) => {
|
|
491
|
+
if (frame === page.mainFrame()) this.checkLanding(tab)
|
|
492
|
+
})
|
|
493
|
+
page.on('response', (response) => {
|
|
494
|
+
try {
|
|
495
|
+
if (response.request().isNavigationRequest() && response.frame() === page.mainFrame()) {
|
|
496
|
+
tab.status = response.status()
|
|
497
|
+
}
|
|
498
|
+
} catch {
|
|
499
|
+
// A response without a frame (a service worker's) says nothing about the page.
|
|
500
|
+
}
|
|
501
|
+
})
|
|
502
|
+
page.on('dialog', (dialog) => this.onDialog(tab, dialog))
|
|
503
|
+
page.on('download', (download) => {
|
|
504
|
+
const name = download.suggestedFilename()
|
|
505
|
+
this.notes.push(
|
|
506
|
+
`A download of ${quoteShort(name)} was cancelled: the browser does not download files.`,
|
|
507
|
+
)
|
|
508
|
+
void download.cancel().catch(() => undefined)
|
|
509
|
+
})
|
|
510
|
+
page.on('close', () => {
|
|
511
|
+
this.tabs.delete(tab.id)
|
|
512
|
+
if (this.pendingDialog?.tab === tab) this.pendingDialog = undefined
|
|
513
|
+
if (this.activeTabId === tab.id) this.activeTabId = [...this.tabs.keys()].pop()
|
|
514
|
+
})
|
|
515
|
+
return tab
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
private onDialog(tab: Tab, dialog: Dialog): void {
|
|
519
|
+
if (dialog.type() === 'beforeunload') {
|
|
520
|
+
// The call that left the page was approved; a "leave site?" prompt
|
|
521
|
+
// would otherwise hold the navigation until it timed out.
|
|
522
|
+
void dialog.accept().catch(() => undefined)
|
|
523
|
+
this.notes.push('The page asked before leaving; it was left.')
|
|
524
|
+
return
|
|
525
|
+
}
|
|
526
|
+
if (this.pendingDialog) {
|
|
527
|
+
void dialog.dismiss().catch(() => undefined)
|
|
528
|
+
return
|
|
529
|
+
}
|
|
530
|
+
this.pendingDialog = { tab, dialog }
|
|
531
|
+
this.notes.push(
|
|
532
|
+
`A ${dialog.type()} dialog is open on tab ${tab.id}. Take a snapshot to read it, then answer it with browser_act dialog.`,
|
|
533
|
+
)
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
/** The route handler: stop top-level navigations the policy does not allow. */
|
|
537
|
+
private async screen(route: Route): Promise<void> {
|
|
538
|
+
const request = route.request()
|
|
539
|
+
let topLevel = false
|
|
540
|
+
if (request.isNavigationRequest()) {
|
|
541
|
+
try {
|
|
542
|
+
topLevel = request.frame().parentFrame() === null
|
|
543
|
+
} catch {
|
|
544
|
+
// A popup's first request is issued before its frame exists; it is
|
|
545
|
+
// the top-level document of the new tab.
|
|
546
|
+
topLevel = true
|
|
547
|
+
}
|
|
548
|
+
}
|
|
549
|
+
if (topLevel) {
|
|
550
|
+
const verdict = this.policy.landing(request.url())
|
|
551
|
+
if (!verdict.allowed) {
|
|
552
|
+
this.notes.push(
|
|
553
|
+
`A navigation to ${verdict.origin} was blocked before it was sent: ${verdict.reason}. To go there, open it with navigate.`,
|
|
554
|
+
)
|
|
555
|
+
// `aborted`, not `blockedbyclient`: Chromium commits an error page
|
|
556
|
+
// for the latter, which would replace the page the tab was on.
|
|
557
|
+
await route.abort('aborted').catch(() => undefined)
|
|
558
|
+
return
|
|
559
|
+
}
|
|
560
|
+
}
|
|
561
|
+
await route.fallback().catch(() => undefined)
|
|
562
|
+
}
|
|
563
|
+
|
|
564
|
+
/** After a navigation lands: clear the tab if the policy does not allow where it is. */
|
|
565
|
+
private checkLanding(tab: Tab): void {
|
|
566
|
+
const url = tab.page.url()
|
|
567
|
+
const verdict = this.policy.landing(url)
|
|
568
|
+
if (verdict.allowed) return
|
|
569
|
+
this.notes.push(
|
|
570
|
+
`Tab ${tab.id} ended up on ${verdict.origin}: ${verdict.reason}. It was cleared to about:blank.`,
|
|
571
|
+
)
|
|
572
|
+
const blank = tab.page
|
|
573
|
+
.goto('about:blank')
|
|
574
|
+
.catch(() => undefined)
|
|
575
|
+
.finally(() => this.blanking.delete(blank))
|
|
576
|
+
this.blanking.add(blank)
|
|
577
|
+
}
|
|
578
|
+
|
|
579
|
+
private async settle(): Promise<void> {
|
|
580
|
+
await new Promise((resolve) => setTimeout(resolve, EVENT_SETTLE_MS))
|
|
581
|
+
while (this.blanking.size > 0) await Promise.all([...this.blanking])
|
|
582
|
+
}
|
|
583
|
+
|
|
584
|
+
private async activeTab(): Promise<Tab> {
|
|
585
|
+
const context = await this.ensureContext()
|
|
586
|
+
const current = this.activeTabId ? this.tabs.get(this.activeTabId) : undefined
|
|
587
|
+
if (current && !current.page.isClosed()) return current
|
|
588
|
+
const page = await this.openOwnPage(context)
|
|
589
|
+
const tab = this.adopt(page, false)
|
|
590
|
+
this.activeTabId = tab.id
|
|
591
|
+
return tab
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
private async openOwnPage(context: BrowserContext): Promise<Page> {
|
|
595
|
+
this.ownPageOpening = true
|
|
596
|
+
try {
|
|
597
|
+
return await context.newPage()
|
|
598
|
+
} finally {
|
|
599
|
+
this.ownPageOpening = false
|
|
600
|
+
}
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
private drainNotes(): string | undefined {
|
|
604
|
+
if (this.notes.length === 0) return undefined
|
|
605
|
+
const text = this.notes.join(' ')
|
|
606
|
+
this.notes.length = 0
|
|
607
|
+
return text
|
|
608
|
+
}
|
|
609
|
+
|
|
610
|
+
private async title(tab: Tab): Promise<string> {
|
|
611
|
+
if (this.pendingDialog?.tab === tab) return ''
|
|
612
|
+
return Promise.race([
|
|
613
|
+
tab.page.title().catch(() => ''),
|
|
614
|
+
new Promise<string>((resolve) => setTimeout(() => resolve(''), 1000)),
|
|
615
|
+
])
|
|
616
|
+
}
|
|
617
|
+
|
|
618
|
+
private async pageInfo(tab: Tab): Promise<BrowserPageInfo> {
|
|
619
|
+
const url = tab.page.url()
|
|
620
|
+
return { origin: originOf(url), url, title: await this.title(tab), tab: tab.id }
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
private result(extra: Omit<BrowserResult, 'message'>): BrowserResult {
|
|
624
|
+
const message = this.drainNotes()
|
|
625
|
+
return { ...extra, ...(message !== undefined ? { message } : {}) }
|
|
626
|
+
}
|
|
627
|
+
|
|
628
|
+
// -------------------------------------------------------------------------
|
|
629
|
+
// Human handoff
|
|
630
|
+
// -------------------------------------------------------------------------
|
|
631
|
+
|
|
632
|
+
private loginCommandFor(url: string): string {
|
|
633
|
+
const target = withoutQuery(url)
|
|
634
|
+
return this.options.loginCommand
|
|
635
|
+
? this.options.loginCommand(this.profile, target)
|
|
636
|
+
: `namzu browser login ${this.profile} ${target}`
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
private humanRequired(
|
|
640
|
+
reason: BrowserHumanRequiredError['reason'],
|
|
641
|
+
tab: Tab,
|
|
642
|
+
): BrowserHumanRequiredError {
|
|
643
|
+
const url = tab.page.url()
|
|
644
|
+
return new BrowserHumanRequiredError(reason, originOf(url), {
|
|
645
|
+
profile: this.profile,
|
|
646
|
+
loginCommand: this.loginCommandFor(url),
|
|
647
|
+
})
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
/** Throw `browser_human_required` if the page needs a person. */
|
|
651
|
+
private async checkHuman(tab: Tab): Promise<void> {
|
|
652
|
+
const page = tab.page
|
|
653
|
+
const url = page.url()
|
|
654
|
+
if (originOf(url) === 'null' || this.pendingDialog?.tab === tab) return
|
|
655
|
+
const counts = await page
|
|
656
|
+
.evaluate(countCredentialFields)
|
|
657
|
+
.catch(() => ({ passwordFields: 0, oneTimeCodeFields: 0 }))
|
|
658
|
+
const frameUrls: string[] = []
|
|
659
|
+
for (const frame of page.frames()) {
|
|
660
|
+
if (frame === page.mainFrame()) continue
|
|
661
|
+
try {
|
|
662
|
+
const element = await frame.frameElement()
|
|
663
|
+
const box = await element.boundingBox()
|
|
664
|
+
if (box && box.width >= CAPTCHA_FRAME_MIN_PX && box.height >= CAPTCHA_FRAME_MIN_PX) {
|
|
665
|
+
frameUrls.push(frame.url())
|
|
666
|
+
}
|
|
667
|
+
} catch {
|
|
668
|
+
// A frame that went away while we looked is not a challenge.
|
|
669
|
+
}
|
|
670
|
+
}
|
|
671
|
+
const reason = classifyHumanRequired(
|
|
672
|
+
{
|
|
673
|
+
url,
|
|
674
|
+
title: await this.title(tab),
|
|
675
|
+
...(tab.status !== undefined ? { status: tab.status } : {}),
|
|
676
|
+
...counts,
|
|
677
|
+
frameUrls,
|
|
678
|
+
},
|
|
679
|
+
this.options.signInAddresses ? { signInAddresses: this.options.signInAddresses } : {},
|
|
680
|
+
)
|
|
681
|
+
if (reason) throw this.humanRequired(reason, tab)
|
|
682
|
+
}
|
|
683
|
+
|
|
684
|
+
// -------------------------------------------------------------------------
|
|
685
|
+
// Calls
|
|
686
|
+
// -------------------------------------------------------------------------
|
|
687
|
+
|
|
688
|
+
private async guarded<T>(signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
|
|
689
|
+
if (signal?.aborted) throw new Error('The browser call was cancelled.')
|
|
690
|
+
if (!signal) return run()
|
|
691
|
+
let onAbort: (() => void) | undefined
|
|
692
|
+
const aborted = new Promise<never>((_, reject) => {
|
|
693
|
+
onAbort = () => reject(new Error('The browser call was cancelled.'))
|
|
694
|
+
signal.addEventListener('abort', onAbort, { once: true })
|
|
695
|
+
})
|
|
696
|
+
try {
|
|
697
|
+
return await Promise.race([run(), aborted])
|
|
698
|
+
} finally {
|
|
699
|
+
if (onAbort) signal.removeEventListener('abort', onAbort)
|
|
700
|
+
}
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
async observe(
|
|
704
|
+
action: BrowserObserveAction,
|
|
705
|
+
options?: BrowserCallOptions,
|
|
706
|
+
): Promise<BrowserResult> {
|
|
707
|
+
return this.guarded(options?.signal, () => this.runObserve(action))
|
|
708
|
+
}
|
|
709
|
+
|
|
710
|
+
async act(action: BrowserActAction, options?: BrowserCallOptions): Promise<BrowserResult> {
|
|
711
|
+
return this.guarded(options?.signal, () => this.runAct(action))
|
|
712
|
+
}
|
|
713
|
+
|
|
714
|
+
private async runObserve(action: BrowserObserveAction): Promise<BrowserResult> {
|
|
715
|
+
switch (action.action) {
|
|
716
|
+
case 'navigate':
|
|
717
|
+
return this.navigate(await this.activeTab(), action.url)
|
|
718
|
+
case 'back':
|
|
719
|
+
case 'forward':
|
|
720
|
+
case 'reload':
|
|
721
|
+
return this.history(action.action)
|
|
722
|
+
case 'snapshot':
|
|
723
|
+
return this.snapshot(action.ref, action.cursor)
|
|
724
|
+
case 'screenshot':
|
|
725
|
+
return this.screenshot(action.ref, action.fullPage)
|
|
726
|
+
case 'scroll':
|
|
727
|
+
return this.scroll(action.direction, action.ref, action.amount)
|
|
728
|
+
case 'wait_for':
|
|
729
|
+
return this.waitFor(action)
|
|
730
|
+
case 'tabs':
|
|
731
|
+
return this.tabsCall(action)
|
|
732
|
+
}
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
private async navigate(tab: Tab, rawUrl: string): Promise<BrowserResult> {
|
|
736
|
+
const verdict = canonicalizeBrowserUrl(rawUrl)
|
|
737
|
+
if (!verdict.ok)
|
|
738
|
+
throw new BrowserSiteDeniedError('', `The address was refused: ${verdict.reason}`)
|
|
739
|
+
if (verdict.url !== 'about:blank') {
|
|
740
|
+
const level = this.policy.levelOf(verdict.origin)
|
|
741
|
+
if (level === 'deny') throw new BrowserSiteDeniedError(verdict.origin)
|
|
742
|
+
this.policy.approve(verdict.origin)
|
|
743
|
+
}
|
|
744
|
+
await this.dismissPendingDialog(tab)
|
|
745
|
+
tab.status = undefined
|
|
746
|
+
try {
|
|
747
|
+
await tab.page.goto(verdict.url, { waitUntil: 'domcontentloaded' })
|
|
748
|
+
} catch (error) {
|
|
749
|
+
if (!/ERR_BLOCKED_BY_CLIENT|ERR_ABORTED|Download is starting/.test(firstLine(error))) {
|
|
750
|
+
throw new Error(`Could not open ${verdict.url}: ${firstLine(error)}`)
|
|
751
|
+
}
|
|
752
|
+
}
|
|
753
|
+
return this.afterNavigation(tab)
|
|
754
|
+
}
|
|
755
|
+
|
|
756
|
+
private async afterNavigation(tab: Tab): Promise<BrowserResult> {
|
|
757
|
+
await this.settle()
|
|
758
|
+
this.checkLanding(tab)
|
|
759
|
+
await this.settle()
|
|
760
|
+
await this.checkHuman(tab)
|
|
761
|
+
return this.result({ page: await this.pageInfo(tab) })
|
|
762
|
+
}
|
|
763
|
+
|
|
764
|
+
private async history(which: 'back' | 'forward' | 'reload'): Promise<BrowserResult> {
|
|
765
|
+
const tab = await this.activeTab()
|
|
766
|
+
await this.dismissPendingDialog(tab)
|
|
767
|
+
tab.status = undefined
|
|
768
|
+
// `commit`, then the document as a bonus: a page restored from the
|
|
769
|
+
// back-forward cache fires no `domcontentloaded`, so waiting for it
|
|
770
|
+
// timed out after a history move that had long finished (measured
|
|
771
|
+
// with the Windows engine: 30 s, then a failure, on a page that was
|
|
772
|
+
// already back).
|
|
773
|
+
const options = { waitUntil: 'commit' as const }
|
|
774
|
+
const before = tab.page.url()
|
|
775
|
+
let response: unknown = true
|
|
776
|
+
try {
|
|
777
|
+
response =
|
|
778
|
+
which === 'back'
|
|
779
|
+
? await tab.page.goBack(options)
|
|
780
|
+
: which === 'forward'
|
|
781
|
+
? await tab.page.goForward(options)
|
|
782
|
+
: await tab.page.reload(options)
|
|
783
|
+
} catch (error) {
|
|
784
|
+
if (!/ERR_BLOCKED_BY_CLIENT|ERR_ABORTED/.test(firstLine(error))) throw error
|
|
785
|
+
}
|
|
786
|
+
if (response !== null) {
|
|
787
|
+
await tab.page
|
|
788
|
+
.waitForLoadState('domcontentloaded', { timeout: HISTORY_LOAD_WAIT_MS })
|
|
789
|
+
.catch(() => undefined)
|
|
790
|
+
}
|
|
791
|
+
// `null` is also what a restore from the back-forward cache returns:
|
|
792
|
+
// no network response. Only an unchanged address means nowhere to go.
|
|
793
|
+
if (response === null && which !== 'reload' && tab.page.url() === before) {
|
|
794
|
+
this.notes.push(`There is no page to go ${which} to.`)
|
|
795
|
+
}
|
|
796
|
+
return this.afterNavigation(tab)
|
|
797
|
+
}
|
|
798
|
+
|
|
799
|
+
private async dismissPendingDialog(tab: Tab): Promise<void> {
|
|
800
|
+
const pending = this.pendingDialog
|
|
801
|
+
if (!pending || pending.tab !== tab) return
|
|
802
|
+
this.pendingDialog = undefined
|
|
803
|
+
await pending.dialog.dismiss().catch(() => undefined)
|
|
804
|
+
this.notes.push('The open dialog was dismissed.')
|
|
805
|
+
}
|
|
806
|
+
|
|
807
|
+
private async takeSnapshot(tab: Tab, ref?: string): Promise<BrowserSnapshot> {
|
|
808
|
+
const pending = this.pendingDialog
|
|
809
|
+
if (pending && pending.tab === tab) {
|
|
810
|
+
const dialog = pending.dialog
|
|
811
|
+
const lines = [
|
|
812
|
+
`- dialog (${dialog.type()}) ${JSON.stringify(dialog.message().replace(/\s+/g, ' ').trim())}`,
|
|
813
|
+
]
|
|
814
|
+
if (dialog.type() === 'prompt')
|
|
815
|
+
lines.push(` - /default: ${JSON.stringify(dialog.defaultValue())}`)
|
|
816
|
+
lines.push(' - (the page is paused until the dialog is answered)')
|
|
817
|
+
return { page: await this.pageInfo(tab), text: lines.join('\n') }
|
|
818
|
+
}
|
|
819
|
+
const { nodes, hidden, redact } = await captureAriaTree(
|
|
820
|
+
tab.page,
|
|
821
|
+
this.options.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS,
|
|
822
|
+
)
|
|
823
|
+
const whole = renderAriaTree(nodes, hidden, undefined, redact)
|
|
824
|
+
if (!whole) throw new Error('The page could not be read.')
|
|
825
|
+
this.refs = whole.refs
|
|
826
|
+
let text = whole.text
|
|
827
|
+
if (ref !== undefined) {
|
|
828
|
+
const region = renderAriaTree(nodes, hidden, ref, redact)
|
|
829
|
+
if (!region || !whole.refs.has(ref)) throw new BrowserStaleRefError(ref)
|
|
830
|
+
text = region.text
|
|
831
|
+
}
|
|
832
|
+
if (text.trim() === '') text = '(nothing readable on this page)'
|
|
833
|
+
const first = this.pager.start(text)
|
|
834
|
+
return {
|
|
835
|
+
page: await this.pageInfo(tab),
|
|
836
|
+
text: first.text,
|
|
837
|
+
...(first.nextCursor !== undefined ? { nextCursor: first.nextCursor } : {}),
|
|
838
|
+
}
|
|
839
|
+
}
|
|
840
|
+
|
|
841
|
+
private async snapshot(ref?: string, cursor?: string): Promise<BrowserResult> {
|
|
842
|
+
const tab = await this.activeTab()
|
|
843
|
+
if (cursor !== undefined) {
|
|
844
|
+
const next = this.pager.resume(cursor)
|
|
845
|
+
if (!next) {
|
|
846
|
+
throw new Error(
|
|
847
|
+
'That cursor belongs to an older snapshot. Take a new snapshot and page through it.',
|
|
848
|
+
)
|
|
849
|
+
}
|
|
850
|
+
return this.result({
|
|
851
|
+
snapshot: {
|
|
852
|
+
page: await this.pageInfo(tab),
|
|
853
|
+
text: next.text,
|
|
854
|
+
...(next.nextCursor !== undefined ? { nextCursor: next.nextCursor } : {}),
|
|
855
|
+
},
|
|
856
|
+
})
|
|
857
|
+
}
|
|
858
|
+
await this.settle()
|
|
859
|
+
return this.result({ snapshot: await this.takeSnapshot(tab, ref) })
|
|
860
|
+
}
|
|
861
|
+
|
|
862
|
+
private async resolveRef(tab: Tab, ref: string): Promise<Locator> {
|
|
863
|
+
if (!this.refs.has(ref)) throw new BrowserStaleRefError(ref)
|
|
864
|
+
const locator = locateRef(tab.page, ref)
|
|
865
|
+
let count = 0
|
|
866
|
+
try {
|
|
867
|
+
count = await locator.count()
|
|
868
|
+
} catch {
|
|
869
|
+
count = 0
|
|
870
|
+
}
|
|
871
|
+
if (count !== 1) throw new BrowserStaleRefError(ref)
|
|
872
|
+
return locator
|
|
873
|
+
}
|
|
874
|
+
|
|
875
|
+
private async screenshot(ref?: string, fullPage?: boolean): Promise<BrowserResult> {
|
|
876
|
+
const tab = await this.activeTab()
|
|
877
|
+
if (this.pendingDialog?.tab === tab) {
|
|
878
|
+
throw new Error(
|
|
879
|
+
'A dialog is open; answer it with browser_act dialog before taking a screenshot.',
|
|
880
|
+
)
|
|
881
|
+
}
|
|
882
|
+
const data =
|
|
883
|
+
ref !== undefined
|
|
884
|
+
? await (await this.resolveRef(tab, ref)).screenshot({ type: 'png' })
|
|
885
|
+
: await tab.page.screenshot({ type: 'png', fullPage: fullPage === true })
|
|
886
|
+
const bytes = new Uint8Array(data)
|
|
887
|
+
const size = pngSize(bytes)
|
|
888
|
+
return this.result({
|
|
889
|
+
screenshot: {
|
|
890
|
+
page: await this.pageInfo(tab),
|
|
891
|
+
data: bytes,
|
|
892
|
+
mimeType: 'image/png',
|
|
893
|
+
width: size.width,
|
|
894
|
+
height: size.height,
|
|
895
|
+
},
|
|
896
|
+
})
|
|
897
|
+
}
|
|
898
|
+
|
|
899
|
+
private async scroll(
|
|
900
|
+
direction: 'up' | 'down' | 'left' | 'right',
|
|
901
|
+
ref?: string,
|
|
902
|
+
amount?: number,
|
|
903
|
+
): Promise<BrowserResult> {
|
|
904
|
+
const tab = await this.activeTab()
|
|
905
|
+
const screens = amount ?? 1
|
|
906
|
+
const vector = { up: [0, -1], down: [0, 1], left: [-1, 0], right: [1, 0] }[direction]
|
|
907
|
+
const [dx, dy] = vector as [number, number]
|
|
908
|
+
if (ref !== undefined) {
|
|
909
|
+
const locator = await this.resolveRef(tab, ref)
|
|
910
|
+
await locator.evaluate(
|
|
911
|
+
(el, [x, y, n]) => {
|
|
912
|
+
el.scrollBy({
|
|
913
|
+
left: x * el.clientWidth * 0.9 * n,
|
|
914
|
+
top: y * el.clientHeight * 0.9 * n,
|
|
915
|
+
})
|
|
916
|
+
},
|
|
917
|
+
[dx, dy, screens] as const,
|
|
918
|
+
)
|
|
919
|
+
} else {
|
|
920
|
+
await tab.page.evaluate(
|
|
921
|
+
([x, y, n]) => {
|
|
922
|
+
window.scrollBy({
|
|
923
|
+
left: x * window.innerWidth * 0.9 * n,
|
|
924
|
+
top: y * window.innerHeight * 0.9 * n,
|
|
925
|
+
})
|
|
926
|
+
},
|
|
927
|
+
[dx, dy, screens] as const,
|
|
928
|
+
)
|
|
929
|
+
}
|
|
930
|
+
this.notes.unshift(`Scrolled ${direction}.`)
|
|
931
|
+
return this.result({ page: await this.pageInfo(tab) })
|
|
932
|
+
}
|
|
933
|
+
|
|
934
|
+
private async waitFor(
|
|
935
|
+
action: Extract<BrowserObserveAction, { action: 'wait_for' }>,
|
|
936
|
+
): Promise<BrowserResult> {
|
|
937
|
+
const tab = await this.activeTab()
|
|
938
|
+
const timeout = Math.min(action.timeMs ?? 30_000, 30_000)
|
|
939
|
+
if (this.pendingDialog?.tab === tab) {
|
|
940
|
+
return this.result({ page: await this.pageInfo(tab) })
|
|
941
|
+
}
|
|
942
|
+
if (action.text !== undefined || action.textGone !== undefined) {
|
|
943
|
+
const text = (action.text ?? action.textGone) as string
|
|
944
|
+
const state = action.text !== undefined ? 'visible' : 'hidden'
|
|
945
|
+
try {
|
|
946
|
+
await tab.page.getByText(text).first().waitFor({ state, timeout })
|
|
947
|
+
this.notes.unshift(
|
|
948
|
+
action.text !== undefined
|
|
949
|
+
? `${quoteShort(text)} is on the page.`
|
|
950
|
+
: `${quoteShort(text)} is gone.`,
|
|
951
|
+
)
|
|
952
|
+
} catch {
|
|
953
|
+
this.notes.unshift(
|
|
954
|
+
action.text !== undefined
|
|
955
|
+
? `${quoteShort(text)} did not appear within ${timeout} ms.`
|
|
956
|
+
: `${quoteShort(text)} was still there after ${timeout} ms.`,
|
|
957
|
+
)
|
|
958
|
+
}
|
|
959
|
+
} else {
|
|
960
|
+
await tab.page.waitForTimeout(timeout)
|
|
961
|
+
this.notes.unshift(`Waited ${timeout} ms.`)
|
|
962
|
+
}
|
|
963
|
+
return this.result({ page: await this.pageInfo(tab) })
|
|
964
|
+
}
|
|
965
|
+
|
|
966
|
+
private async tabsCall(
|
|
967
|
+
action: Extract<BrowserObserveAction, { action: 'tabs' }>,
|
|
968
|
+
): Promise<BrowserResult> {
|
|
969
|
+
const context = await this.ensureContext()
|
|
970
|
+
await this.activeTab()
|
|
971
|
+
switch (action.op) {
|
|
972
|
+
case 'list':
|
|
973
|
+
return this.result({ tabs: await this.tabList() })
|
|
974
|
+
case 'select': {
|
|
975
|
+
const tab = this.tabs.get(action.tab ?? '')
|
|
976
|
+
if (!tab) throw new Error(`There is no tab ${action.tab}. List the tabs to see their ids.`)
|
|
977
|
+
this.activeTabId = tab.id
|
|
978
|
+
await tab.page.bringToFront().catch(() => undefined)
|
|
979
|
+
this.refs = new Map()
|
|
980
|
+
return this.result({ page: await this.pageInfo(tab) })
|
|
981
|
+
}
|
|
982
|
+
case 'close': {
|
|
983
|
+
const tab = this.tabs.get(action.tab ?? '')
|
|
984
|
+
if (!tab) throw new Error(`There is no tab ${action.tab}. List the tabs to see their ids.`)
|
|
985
|
+
await tab.page.close().catch(() => undefined)
|
|
986
|
+
this.tabs.delete(tab.id)
|
|
987
|
+
if (this.activeTabId === tab.id) {
|
|
988
|
+
this.activeTabId = [...this.tabs.keys()].pop()
|
|
989
|
+
this.refs = new Map()
|
|
990
|
+
}
|
|
991
|
+
return this.result({ tabs: await this.tabList() })
|
|
992
|
+
}
|
|
993
|
+
case 'new': {
|
|
994
|
+
const page = await this.openOwnPage(context)
|
|
995
|
+
const tab = this.adopt(page, false)
|
|
996
|
+
this.activeTabId = tab.id
|
|
997
|
+
this.refs = new Map()
|
|
998
|
+
if (action.url === undefined || action.url === 'about:blank') {
|
|
999
|
+
return this.result({ page: await this.pageInfo(tab) })
|
|
1000
|
+
}
|
|
1001
|
+
return this.navigate(tab, action.url)
|
|
1002
|
+
}
|
|
1003
|
+
}
|
|
1004
|
+
}
|
|
1005
|
+
|
|
1006
|
+
private async tabList(): Promise<BrowserTabInfo[]> {
|
|
1007
|
+
const out: BrowserTabInfo[] = []
|
|
1008
|
+
for (const tab of this.tabs.values()) {
|
|
1009
|
+
if (tab.page.isClosed()) continue
|
|
1010
|
+
out.push({ ...(await this.pageInfo(tab)), active: tab.id === this.activeTabId })
|
|
1011
|
+
}
|
|
1012
|
+
return out
|
|
1013
|
+
}
|
|
1014
|
+
|
|
1015
|
+
// -------------------------------------------------------------------------
|
|
1016
|
+
// Acting
|
|
1017
|
+
// -------------------------------------------------------------------------
|
|
1018
|
+
|
|
1019
|
+
private async guardField(tab: Tab, locator: Locator): Promise<ElementFieldFacts> {
|
|
1020
|
+
const facts = await locator.evaluate(fieldFacts)
|
|
1021
|
+
if (isCredentialField(facts)) throw this.humanRequired('credential-field', tab)
|
|
1022
|
+
return facts
|
|
1023
|
+
}
|
|
1024
|
+
|
|
1025
|
+
private async runAct(action: BrowserActAction): Promise<BrowserResult> {
|
|
1026
|
+
const tab = await this.activeTab()
|
|
1027
|
+
await this.settle()
|
|
1028
|
+
const expected = canonicalizeBrowserOrigin(action.origin)
|
|
1029
|
+
const live = originOf(tab.page.url())
|
|
1030
|
+
if (!expected.ok || expected.origin !== live) {
|
|
1031
|
+
throw new BrowserOriginMismatchError(
|
|
1032
|
+
expected.ok ? expected.origin : action.origin,
|
|
1033
|
+
live === 'null' ? 'about:blank' : live,
|
|
1034
|
+
)
|
|
1035
|
+
}
|
|
1036
|
+
if (!this.policy.canAct(live)) {
|
|
1037
|
+
throw new BrowserSiteDeniedError(
|
|
1038
|
+
live,
|
|
1039
|
+
`${live} may be read but not changed under the site rules.`,
|
|
1040
|
+
)
|
|
1041
|
+
}
|
|
1042
|
+
if (action.action === 'dialog') return this.answerDialog(tab, action)
|
|
1043
|
+
if (this.pendingDialog?.tab === tab) {
|
|
1044
|
+
throw new Error('A dialog is open on this tab; answer it with browser_act dialog first.')
|
|
1045
|
+
}
|
|
1046
|
+
|
|
1047
|
+
await this.perform(tab, action)
|
|
1048
|
+
await this.settle()
|
|
1049
|
+
this.checkLanding(tab)
|
|
1050
|
+
await this.settle()
|
|
1051
|
+
await this.checkHuman(tab)
|
|
1052
|
+
const after = this.tabs.get(tab.id) ?? tab
|
|
1053
|
+
if (action.snapshot) return this.result({ snapshot: await this.takeSnapshot(after) })
|
|
1054
|
+
return this.result({ page: await this.pageInfo(after) })
|
|
1055
|
+
}
|
|
1056
|
+
|
|
1057
|
+
private async answerDialog(
|
|
1058
|
+
tab: Tab,
|
|
1059
|
+
action: Extract<BrowserActAction, { action: 'dialog' }>,
|
|
1060
|
+
): Promise<BrowserResult> {
|
|
1061
|
+
const pending = this.pendingDialog
|
|
1062
|
+
if (!pending || pending.tab !== tab) throw new Error('No dialog is open on this tab.')
|
|
1063
|
+
this.pendingDialog = undefined
|
|
1064
|
+
try {
|
|
1065
|
+
if (action.accept) await pending.dialog.accept(action.promptText)
|
|
1066
|
+
else await pending.dialog.dismiss()
|
|
1067
|
+
} catch (error) {
|
|
1068
|
+
throw new BrowserOutcomeUnknownError('dialog', error)
|
|
1069
|
+
}
|
|
1070
|
+
this.notes.unshift(action.accept ? 'The dialog was accepted.' : 'The dialog was dismissed.')
|
|
1071
|
+
await this.settle()
|
|
1072
|
+
this.checkLanding(tab)
|
|
1073
|
+
await this.settle()
|
|
1074
|
+
if (action.snapshot) return this.result({ snapshot: await this.takeSnapshot(tab) })
|
|
1075
|
+
return this.result({ page: await this.pageInfo(tab) })
|
|
1076
|
+
}
|
|
1077
|
+
|
|
1078
|
+
/**
|
|
1079
|
+
* Do the action. Everything that can refuse — refs, credential fields,
|
|
1080
|
+
* actionability — is checked before anything happens; a failure after
|
|
1081
|
+
* the first change is `browser_outcome_unknown`.
|
|
1082
|
+
*/
|
|
1083
|
+
private async perform(tab: Tab, action: BrowserActAction): Promise<void> {
|
|
1084
|
+
switch (action.action) {
|
|
1085
|
+
case 'click': {
|
|
1086
|
+
const locator = await this.resolveRef(tab, action.ref)
|
|
1087
|
+
await locator.click({ trial: true })
|
|
1088
|
+
await this.unknownOnFailure('click', () =>
|
|
1089
|
+
action.doubleClick ? locator.dblclick() : locator.click(),
|
|
1090
|
+
)
|
|
1091
|
+
return
|
|
1092
|
+
}
|
|
1093
|
+
case 'hover': {
|
|
1094
|
+
const locator = await this.resolveRef(tab, action.ref)
|
|
1095
|
+
await locator.hover({ trial: true })
|
|
1096
|
+
await this.unknownOnFailure('hover', () => locator.hover())
|
|
1097
|
+
return
|
|
1098
|
+
}
|
|
1099
|
+
case 'type': {
|
|
1100
|
+
const locator = await this.resolveRef(tab, action.ref)
|
|
1101
|
+
await this.guardField(tab, locator)
|
|
1102
|
+
await locator.click({ trial: true })
|
|
1103
|
+
await this.unknownOnFailure('type', async () => {
|
|
1104
|
+
await locator.fill(action.text)
|
|
1105
|
+
if (action.submit) await locator.press('Enter')
|
|
1106
|
+
})
|
|
1107
|
+
return
|
|
1108
|
+
}
|
|
1109
|
+
case 'fill_form': {
|
|
1110
|
+
const plan: { locator: Locator; facts: ElementFieldFacts; value: string }[] = []
|
|
1111
|
+
for (const field of action.fields) {
|
|
1112
|
+
const locator = await this.resolveRef(tab, field.ref)
|
|
1113
|
+
const facts = await this.guardField(tab, locator)
|
|
1114
|
+
if (facts.kind === 'file') {
|
|
1115
|
+
throw new Error(`${field.ref} is a file input; use browser_act upload for it.`)
|
|
1116
|
+
}
|
|
1117
|
+
plan.push({ locator, facts, value: field.value })
|
|
1118
|
+
}
|
|
1119
|
+
await this.unknownOnFailure('fill_form', async () => {
|
|
1120
|
+
for (const step of plan) {
|
|
1121
|
+
if (step.facts.kind === 'checkbox' || step.facts.kind === 'radio') {
|
|
1122
|
+
await step.locator.setChecked(step.value === 'true')
|
|
1123
|
+
} else if (step.facts.kind === 'select') {
|
|
1124
|
+
await step.locator
|
|
1125
|
+
.selectOption([{ label: step.value }])
|
|
1126
|
+
.catch(() => step.locator.selectOption(step.value))
|
|
1127
|
+
} else {
|
|
1128
|
+
await step.locator.fill(step.value)
|
|
1129
|
+
}
|
|
1130
|
+
}
|
|
1131
|
+
})
|
|
1132
|
+
return
|
|
1133
|
+
}
|
|
1134
|
+
case 'select': {
|
|
1135
|
+
const locator = await this.resolveRef(tab, action.ref)
|
|
1136
|
+
await this.unknownOnFailure('select', () => locator.selectOption([...action.values]))
|
|
1137
|
+
return
|
|
1138
|
+
}
|
|
1139
|
+
case 'press': {
|
|
1140
|
+
if (action.ref !== undefined) {
|
|
1141
|
+
const locator = await this.resolveRef(tab, action.ref)
|
|
1142
|
+
const facts = await locator.evaluate(fieldFacts)
|
|
1143
|
+
if (isCredentialField(facts) && !NON_TYPING_KEYS.has(action.key)) {
|
|
1144
|
+
throw this.humanRequired('credential-field', tab)
|
|
1145
|
+
}
|
|
1146
|
+
await this.unknownOnFailure('press', () => locator.press(action.key))
|
|
1147
|
+
return
|
|
1148
|
+
}
|
|
1149
|
+
const focused = await tab.page.evaluate(focusedFieldFacts).catch(() => null)
|
|
1150
|
+
if (focused && isCredentialField(focused) && !NON_TYPING_KEYS.has(action.key)) {
|
|
1151
|
+
throw this.humanRequired('credential-field', tab)
|
|
1152
|
+
}
|
|
1153
|
+
await this.unknownOnFailure('press', () => tab.page.keyboard.press(action.key))
|
|
1154
|
+
return
|
|
1155
|
+
}
|
|
1156
|
+
case 'upload': {
|
|
1157
|
+
const locator = await this.resolveRef(tab, action.ref)
|
|
1158
|
+
const facts = await locator.evaluate(fieldFacts)
|
|
1159
|
+
if (facts.kind === 'file') {
|
|
1160
|
+
await this.unknownOnFailure('upload', () => locator.setInputFiles(action.path))
|
|
1161
|
+
return
|
|
1162
|
+
}
|
|
1163
|
+
await locator.click({ trial: true })
|
|
1164
|
+
await this.unknownOnFailure('upload', async () => {
|
|
1165
|
+
const [chooser] = await Promise.all([
|
|
1166
|
+
tab.page.waitForEvent('filechooser'),
|
|
1167
|
+
locator.click(),
|
|
1168
|
+
])
|
|
1169
|
+
await chooser.setFiles(action.path)
|
|
1170
|
+
})
|
|
1171
|
+
return
|
|
1172
|
+
}
|
|
1173
|
+
case 'dialog':
|
|
1174
|
+
return
|
|
1175
|
+
}
|
|
1176
|
+
}
|
|
1177
|
+
|
|
1178
|
+
/**
|
|
1179
|
+
* Run the change. A failure once it has started is `outcome unknown`. A
|
|
1180
|
+
* dialog the action opens ends the wait: the page is paused until the
|
|
1181
|
+
* dialog is answered, and so is anything Playwright was still waiting for.
|
|
1182
|
+
*/
|
|
1183
|
+
private async unknownOnFailure(
|
|
1184
|
+
action: BrowserActAction['action'],
|
|
1185
|
+
run: () => Promise<unknown>,
|
|
1186
|
+
): Promise<void> {
|
|
1187
|
+
const running = run()
|
|
1188
|
+
let timer: ReturnType<typeof setInterval> | undefined
|
|
1189
|
+
const dialogOpened = new Promise<'dialog'>((resolve) => {
|
|
1190
|
+
timer = setInterval(() => {
|
|
1191
|
+
if (this.pendingDialog) resolve('dialog')
|
|
1192
|
+
}, 50)
|
|
1193
|
+
})
|
|
1194
|
+
try {
|
|
1195
|
+
const outcome = await Promise.race([running, dialogOpened])
|
|
1196
|
+
if (outcome === 'dialog') running.catch(() => undefined)
|
|
1197
|
+
} catch (error) {
|
|
1198
|
+
throw new BrowserOutcomeUnknownError(action, error)
|
|
1199
|
+
} finally {
|
|
1200
|
+
clearInterval(timer)
|
|
1201
|
+
}
|
|
1202
|
+
}
|
|
1203
|
+
|
|
1204
|
+
// -------------------------------------------------------------------------
|
|
1205
|
+
// Labels
|
|
1206
|
+
// -------------------------------------------------------------------------
|
|
1207
|
+
|
|
1208
|
+
describeRef(ref: string): BrowserRefDescription | undefined {
|
|
1209
|
+
return this.refs.get(ref)
|
|
1210
|
+
}
|
|
1211
|
+
|
|
1212
|
+
session(): BrowserSessionInfo {
|
|
1213
|
+
const tab = this.activeTabId ? this.tabs.get(this.activeTabId) : undefined
|
|
1214
|
+
const origin = tab && !tab.page.isClosed() ? originOf(tab.page.url()) : 'null'
|
|
1215
|
+
return { profile: this.profile, ...(origin !== 'null' ? { origin } : {}) }
|
|
1216
|
+
}
|
|
1217
|
+
}
|