1 | /// <reference types="node" />
|
2 |
|
3 | import type { ChildProcess } from 'child_process';
|
4 | import type { ParseSelector } from 'typed-query-selector/parser.js';
|
5 | import { PassThrough } from 'stream';
|
6 | import { Protocol } from 'devtools-protocol';
|
7 | import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
|
8 | import { Session } from 'chromium-bidi/lib/cjs/protocol/protocol.js';
|
9 |
|
10 | /**
|
11 | * The Accessibility class provides methods for inspecting the browser's
|
12 | * accessibility tree. The accessibility tree is used by assistive technology
|
13 | * such as {@link https://en.wikipedia.org/wiki/Screen_reader | screen readers} or
|
14 | * {@link https://en.wikipedia.org/wiki/Switch_access | switches}.
|
15 | *
|
16 | * @remarks
|
17 | *
|
18 | * Accessibility is a very platform-specific thing. On different platforms,
|
19 | * there are different screen readers that might have wildly different output.
|
20 | *
|
21 | * Blink - Chrome's rendering engine - has a concept of "accessibility tree",
|
22 | * which is then translated into different platform-specific APIs. Accessibility
|
23 | * namespace gives users access to the Blink Accessibility Tree.
|
24 | *
|
25 | * Most of the accessibility tree gets filtered out when converting from Blink
|
26 | * AX Tree to Platform-specific AX-Tree or by assistive technologies themselves.
|
27 | * By default, Puppeteer tries to approximate this filtering, exposing only
|
28 | * the "interesting" nodes of the tree.
|
29 | *
|
30 | * @public
|
31 | */
|
32 | export declare class Accessibility {
|
33 | #private;
|
34 |
|
35 | /**
|
36 | * Captures the current state of the accessibility tree.
|
37 | * The returned object represents the root accessible node of the page.
|
38 | *
|
39 | * @remarks
|
40 | *
|
41 | * **NOTE** The Chrome accessibility tree contains nodes that go unused on
|
42 | * most platforms and by most screen readers. Puppeteer will discard them as
|
43 | * well for an easier to process tree, unless `interestingOnly` is set to
|
44 | * `false`.
|
45 | *
|
46 | * @example
|
47 | * An example of dumping the entire accessibility tree:
|
48 | *
|
49 | * ```ts
|
50 | * const snapshot = await page.accessibility.snapshot();
|
51 | * console.log(snapshot);
|
52 | * ```
|
53 | *
|
54 | * @example
|
55 | * An example of logging the focused node's name:
|
56 | *
|
57 | * ```ts
|
58 | * const snapshot = await page.accessibility.snapshot();
|
59 | * const node = findFocusedNode(snapshot);
|
60 | * console.log(node && node.name);
|
61 | *
|
62 | * function findFocusedNode(node) {
|
63 | * if (node.focused) return node;
|
64 | * for (const child of node.children || []) {
|
65 | * const foundNode = findFocusedNode(child);
|
66 | * return foundNode;
|
67 | * }
|
68 | * return null;
|
69 | * }
|
70 | * ```
|
71 | *
|
72 | * @returns An AXNode object representing the snapshot.
|
73 | */
|
74 | snapshot(options?: SnapshotOptions): Promise<SerializedAXNode | null>;
|
75 | private serializeTree;
|
76 | private collectInterestingNodes;
|
77 | }
|
78 |
|
79 | /**
|
80 | * @public
|
81 | */
|
82 | export declare interface ActionOptions {
|
83 | /**
|
84 | * A signal to abort the locator action.
|
85 | */
|
86 | signal?: AbortSignal;
|
87 | }
|
88 |
|
89 | /**
|
90 | * @public
|
91 | */
|
92 | export declare type ActionResult = 'continue' | 'abort' | 'respond';
|
93 |
|
94 | /**
|
95 | * @public
|
96 | */
|
97 | export declare interface AutofillData {
|
98 | creditCard: {
|
99 | number: string;
|
100 | name: string;
|
101 | expiryMonth: string;
|
102 | expiryYear: string;
|
103 | cvc: string;
|
104 | };
|
105 | }
|
106 |
|
107 | /**
|
108 | * @public
|
109 | */
|
110 | export declare type Awaitable<T> = T | PromiseLike<T>;
|
111 |
|
112 | /**
|
113 | * @public
|
114 | */
|
115 | export declare type AwaitableIterable<T> = Iterable<T> | AsyncIterable<T>;
|
116 |
|
117 | /**
|
118 | * @public
|
119 | */
|
120 | export declare type AwaitablePredicate<T> = (value: T) => Awaitable<boolean>;
|
121 |
|
122 | /**
|
123 | * @public
|
124 | */
|
125 | export declare type AwaitedLocator<T> = T extends Locator<infer S> ? S : never;
|
126 |
|
127 | /**
|
128 | * @public
|
129 | */
|
130 | export declare interface BoundingBox extends Point {
|
131 | /**
|
132 | * the width of the element in pixels.
|
133 | */
|
134 | width: number;
|
135 | /**
|
136 | * the height of the element in pixels.
|
137 | */
|
138 | height: number;
|
139 | }
|
140 |
|
141 | /**
|
142 | * @public
|
143 | */
|
144 | export declare interface BoxModel {
|
145 | content: Quad;
|
146 | padding: Quad;
|
147 | border: Quad;
|
148 | margin: Quad;
|
149 | width: number;
|
150 | height: number;
|
151 | }
|
152 |
|
153 | /**
|
154 | * {@link Browser} represents a browser instance that is either:
|
155 | *
|
156 | * - connected to via {@link Puppeteer.connect} or
|
157 | * - launched by {@link PuppeteerNode.launch}.
|
158 | *
|
159 | * {@link Browser} {@link EventEmitter.emit | emits} various events which are
|
160 | * documented in the {@link BrowserEvent} enum.
|
161 | *
|
162 | * @example Using a {@link Browser} to create a {@link Page}:
|
163 | *
|
164 | * ```ts
|
165 | * import puppeteer from 'puppeteer';
|
166 | *
|
167 | * const browser = await puppeteer.launch();
|
168 | * const page = await browser.newPage();
|
169 | * await page.goto('https://example.com');
|
170 | * await browser.close();
|
171 | * ```
|
172 | *
|
173 | * @example Disconnecting from and reconnecting to a {@link Browser}:
|
174 | *
|
175 | * ```ts
|
176 | * import puppeteer from 'puppeteer';
|
177 | *
|
178 | * const browser = await puppeteer.launch();
|
179 | * // Store the endpoint to be able to reconnect to the browser.
|
180 | * const browserWSEndpoint = browser.wsEndpoint();
|
181 | * // Disconnect puppeteer from the browser.
|
182 | * await browser.disconnect();
|
183 | *
|
184 | * // Use the endpoint to reestablish a connection
|
185 | * const browser2 = await puppeteer.connect({browserWSEndpoint});
|
186 | * // Close the browser.
|
187 | * await browser2.close();
|
188 | * ```
|
189 | *
|
190 | * @public
|
191 | */
|
192 | export declare abstract class Browser extends EventEmitter<BrowserEvents> {
|
193 |
|
194 | /**
|
195 | * Gets the associated
|
196 | * {@link https://nodejs.org/api/child_process.html#class-childprocess | ChildProcess}.
|
197 | *
|
198 | * @returns `null` if this instance was connected to via
|
199 | * {@link Puppeteer.connect}.
|
200 | */
|
201 | abstract process(): ChildProcess | null;
|
202 | /**
|
203 | * Creates a new {@link BrowserContext | browser context}.
|
204 | *
|
205 | * This won't share cookies/cache with other {@link BrowserContext | browser contexts}.
|
206 | *
|
207 | * @example
|
208 | *
|
209 | * ```ts
|
210 | * import puppeteer from 'puppeteer';
|
211 | *
|
212 | * const browser = await puppeteer.launch();
|
213 | * // Create a new browser context.
|
214 | * const context = await browser.createBrowserContext();
|
215 | * // Create a new page in a pristine context.
|
216 | * const page = await context.newPage();
|
217 | * // Do stuff
|
218 | * await page.goto('https://example.com');
|
219 | * ```
|
220 | */
|
221 | abstract createBrowserContext(options?: BrowserContextOptions): Promise<BrowserContext>;
|
222 | /**
|
223 | * Gets a list of open {@link BrowserContext | browser contexts}.
|
224 | *
|
225 | * In a newly-created {@link Browser | browser}, this will return a single
|
226 | * instance of {@link BrowserContext}.
|
227 | */
|
228 | abstract browserContexts(): BrowserContext[];
|
229 | /**
|
230 | * Gets the default {@link BrowserContext | browser context}.
|
231 | *
|
232 | * @remarks The default {@link BrowserContext | browser context} cannot be
|
233 | * closed.
|
234 | */
|
235 | abstract defaultBrowserContext(): BrowserContext;
|
236 | /**
|
237 | * Gets the WebSocket URL to connect to this {@link Browser | browser}.
|
238 | *
|
239 | * This is usually used with {@link Puppeteer.connect}.
|
240 | *
|
241 | * You can find the debugger URL (`webSocketDebuggerUrl`) from
|
242 | * `http://HOST:PORT/json/version`.
|
243 | *
|
244 | * See {@link https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target |