UNPKG

271 kBTypeScriptView Raw
1/// <reference types="node" />
2
3import type { ChildProcess } from 'child_process';
4import type { ParseSelector } from 'typed-query-selector/parser.js';
5import { PassThrough } from 'stream';
6import { Protocol } from 'devtools-protocol';
7import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
8import { 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 */
32export 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 */
82export declare interface ActionOptions {
83 /**
84 * A signal to abort the locator action.
85 */
86 signal?: AbortSignal;
87}
88
89/**
90 * @public
91 */
92export declare type ActionResult = 'continue' | 'abort' | 'respond';
93
94/**
95 * @public
96 */
97export 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 */
110export declare type Awaitable<T> = T | PromiseLike<T>;
111
112/**
113 * @public
114 */
115export declare type AwaitableIterable<T> = Iterable<T> | AsyncIterable<T>;
116
117/**
118 * @public
119 */
120export declare type AwaitablePredicate<T> = (value: T) => Awaitable<boolean>;
121
122/**
123 * @public
124 */
125export declare type AwaitedLocator<T> = T extends Locator<infer S> ? S : never;
126
127/**
128 * @public
129 */
130export 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 */
144export 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 */
192export 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