123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688
import { Protocol } from "../../vendor/devtools-protocol/types/protocol.d.ts";import { CDPSession } from "./Connection.js";import { ElementHandle } from "./ElementHandle.js";import { ExecutionContext } from "./ExecutionContext.js";import { FrameManager } from "./FrameManager.js";import { HTTPResponse } from "./HTTPResponse.js";import { MouseButton } from "./Input.js";import { IsolatedWorldChart, WaitForSelectorOptions } from "./IsolatedWorld.js";import { PuppeteerLifeCycleEvent } from "./LifecycleWatcher.js";import { Page } from "./Page.js";import { EvaluateFunc, HandleFor, NodeFor } from "./types.js";/** * @public */export interface FrameWaitForFunctionOptions {  /**   * An interval at which the `pageFunction` is executed, defaults to `raf`. If   * `polling` is a number, then it is treated as an interval in milliseconds at   * which the function would be executed. If `polling` is a string, then it can   * be one of the following values:   *   * - `raf` - to constantly execute `pageFunction` in `requestAnimationFrame`   *   callback. This is the tightest polling mode which is suitable to observe   *   styling changes.   *   * - `mutation` - to execute `pageFunction` on every DOM mutation.   */  polling?: string | number;  /**   * Maximum time to wait in milliseconds. Defaults to `30000` (30 seconds).   * Pass `0` to disable the timeout. Puppeteer's default timeout can be changed   * using {@link Page.setDefaultTimeout}.   */  timeout?: number;}/** * @public */export interface FrameAddScriptTagOptions {  /**   * the URL of the script to be added.   */  url?: string;  /**   * The path to a JavaScript file to be injected into the frame.   * @remarks   * If `path` is a relative path, it is resolved relative to the current   * working directory (`process.cwd()` in Node.js).   */  path?: string;  /**   * Raw JavaScript content to be injected into the frame.   */  content?: string;  /**   * Set the script's `type`. Use `module` in order to load an ES2015 module.   */  type?: string;}/** * @public */export interface FrameAddStyleTagOptions {  /**   * the URL of the CSS file to be added.   */  url?: string;  /**   * The path to a CSS file to be injected into the frame.   * @remarks   * If `path` is a relative path, it is resolved relative to the current   * working directory (`process.cwd()` in Node.js).   */  path?: string;  /**   * Raw CSS content to be injected into the frame.   */  content?: string;}/** * Represents a DOM frame. * * To understand frames, you can think of frames as `<iframe>` elements. Just * like iframes, frames can be nested, and when JavaScript is executed in a * frame, the JavaScript does not effect frames inside the ambient frame the * JavaScript executes in. * * @example * At any point in time, {@link Page | pages} expose their current frame * tree via the {@link Page.mainFrame} and {@link Frame.childFrames} methods. * * @example * An example of dumping frame tree: * * ```ts * const puppeteer = require('puppeteer'); * * (async () => { *   const browser = await puppeteer.launch(); *   const page = await browser.newPage(); *   await page.goto('https://www.google.com/chrome/browser/canary.html'); *   dumpFrameTree(page.mainFrame(), ''); *   await browser.close(); * *   function dumpFrameTree(frame, indent) { *     console.log(indent + frame.url()); *     for (const child of frame.childFrames()) { *       dumpFrameTree(child, indent + '  '); *     } *   } * })(); * ``` * * @example * An example of getting text from an iframe element: * * ```ts * const frame = page.frames().find(frame => frame.name() === 'myframe'); * const text = await frame.$eval('.selector', element => element.textContent); * console.log(text); * ``` * * @remarks * Frame lifecycles are controlled by three events that are all dispatched on * the parent {@link Frame.page | page}: * * - {@link PageEmittedEvents.FrameAttached} * - {@link PageEmittedEvents.FrameNavigated} * - {@link PageEmittedEvents.FrameDetached} * * @public */export declare class Frame {  #private;  /**   * @internal   */  worlds: IsolatedWorldChart;  /**   * @internal   */  _frameManager: FrameManager;  /**   * @internal   */  _id: string;  /**   * @internal   */  _loaderId: string;  /**   * @internal   */  _name?: string;  /**   * @internal   */  _hasStartedLoading: boolean;  /**   * @internal   */  _lifecycleEvents: Set<string>;  /**   * @internal   */  _childFrames: Set<Frame>;  /**   * @internal   */  constructor(    frameManager: FrameManager,    parentFrame: Frame | null,    frameId: string,    client: CDPSession,  );  /**   * @internal   */  updateClient(client: CDPSession): void;  /**   * @returns The page associated with the frame.   */  page(): Page;  /**   * @returns `true` if the frame is an out-of-process (OOP) frame. Otherwise,   * `false`.   */  isOOPFrame(): boolean;  /**   * Navigates a frame to the given url.   *   * @remarks   * Navigation to `about:blank` or navigation to the same URL with a different   * hash will succeed and return `null`.   *   * :::warning   *   * Headless mode doesn't support navigation to a PDF document. See the {@link   * https://bugs.chromium.org/p/chromium/issues/detail?id=761295 | upstream   * issue}.   *   * :::   *   * @param url - the URL to navigate the frame to. This should include the   * scheme, e.g. `https://`.   * @param options - navigation options. `waitUntil` is useful to define when   * the navigation should be considered successful - see the docs for   * {@link PuppeteerLifeCycleEvent} for more details.   *   * @returns A promise which resolves to the main resource response. In case of   * multiple redirects, the navigation will resolve with the response of the   * last redirect.   * @throws This method will throw an error if:   *   * - there's an SSL error (e.g. in case of self-signed certificates).   * - target URL is invalid.   * - the `timeout` is exceeded during navigation.   * - the remote server does not respond or is unreachable.   * - the main resource failed to load.   *   * This method will not throw an error when any valid HTTP status code is   * returned by the remote server, including 404 "Not Found" and 500 "Internal   * Server Error". The status code for such responses can be retrieved by   * calling {@link HTTPResponse.status}.   */  goto(url: string, options?: {    referer?: string;    timeout?: number;    waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];  }): Promise<HTTPResponse | null>;  /**   * Waits for the frame to navigate. It is useful for when you run code which   * will indirectly cause the frame to navigate.   *   * Usage of the   * {@link https://developer.mozilla.org/en-US/docs/Web/API/History_API | History API}   * to change the URL is considered a navigation.   *   * @example   *   * ```ts   * const [response] = await Promise.all([   *   // The navigation promise resolves after navigation has finished   *   frame.waitForNavigation(),   *   // Clicking the link will indirectly cause a navigation   *   frame.click('a.my-link'),   * ]);   * ```   *   * @param options - options to configure when the navigation is consided   * finished.   * @returns a promise that resolves when the frame navigates to a new URL.   */  waitForNavigation(options?: {    timeout?: number;    waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];  }): Promise<HTTPResponse | null>;  /**   * @internal   */  _client(): CDPSession;  /**   * @deprecated Do not use the execution context directly.   *   * @returns a promise that resolves to the frame's default execution context.   */  executionContext(): Promise<ExecutionContext>;  /**   * Behaves identically to {@link Page.evaluateHandle} except it's run within   * the context of this frame.   *   * @see {@link Page.evaluateHandle} for details.   */  evaluateHandle<    Params extends unknown[],    Func extends EvaluateFunc<Params> = EvaluateFunc<Params>,  >(    pageFunction: Func | string,    ...args: Params  ): Promise<HandleFor<Awaited<ReturnType<Func>>>>;  /**   * Behaves identically to {@link Page.evaluate} except it's run within the   * the context of this frame.   *   * @see {@link Page.evaluate} for details.   */  evaluate<    Params extends unknown[],    Func extends EvaluateFunc<Params> = EvaluateFunc<Params>,  >(    pageFunction: Func | string,    ...args: Params  ): Promise<Awaited<ReturnType<Func>>>;  /**   * Queries the frame for an element matching the given selector.   *   * @param selector - The selector to query for.   * @returns A {@link ElementHandle | element handle} to the first element   * matching the given selector. Otherwise, `null`.   */  $<Selector extends string>(    selector: Selector,  ): Promise<ElementHandle<NodeFor<Selector>> | null>;  /**   * Queries the frame for all elements matching the given selector.   *   * @param selector - The selector to query for.   * @returns An array of {@link ElementHandle | element handles} that point to   * elements matching the given selector.   */  $$<Selector extends string>(    selector: Selector,  ): Promise<Array<ElementHandle<NodeFor<Selector>>>>;  /**   * Runs the given function on the first element matching the given selector in   * the frame.   *   * If the given function returns a promise, then this method will wait till   * the promise resolves.   *   * @example   *   * ```ts   * const searchValue = await frame.$eval('#search', el => el.value);   * ```   *   * @param selector - The selector to query for.   * @param pageFunction - The function to be evaluated in the frame's context.   * The first element matching the selector will be passed to the function as   * its first argument.   * @param args - Additional arguments to pass to `pageFunction`.   * @returns A promise to the result of the function.   */  $eval<    Selector extends string,    Params extends unknown[],    Func extends EvaluateFunc<[      ElementHandle<NodeFor<Selector>>,      ...Params,    ]> = EvaluateFunc<[ElementHandle<NodeFor<Selector>>, ...Params]>,  >(    selector: Selector,    pageFunction: Func | string,    ...args: Params  ): Promise<Awaited<ReturnType<Func>>>;  /**   * Runs the given function on an array of elements matching the given selector   * in the frame.   *   * If the given function returns a promise, then this method will wait till   * the promise resolves.   *   * @example   *   * ```js   * const divsCounts = await frame.$$eval('div', divs => divs.length);   * ```   *   * @param selector - The selector to query for.   * @param pageFunction - The function to be evaluated in the frame's context.   * An array of elements matching the given selector will be passed to the   * function as its first argument.   * @param args - Additional arguments to pass to `pageFunction`.   * @returns A promise to the result of the function.   */  $$eval<    Selector extends string,    Params extends unknown[],    Func extends EvaluateFunc<[      Array<NodeFor<Selector>>,      ...Params,    ]> = EvaluateFunc<[Array<NodeFor<Selector>>, ...Params]>,  >(    selector: Selector,    pageFunction: Func | string,    ...args: Params  ): Promise<Awaited<ReturnType<Func>>>;  /**   * @deprecated Use {@link Frame.$$} with the `xpath` prefix.   *   * This method evaluates the given XPath expression and returns the results.   * @param expression - the XPath expression to evaluate.   */  $x(expression: string): Promise<Array<ElementHandle<any>>>;  /**   * Waits for an element matching the given selector to appear in the frame.   *   * This method works across navigations.   *   * @example   *   * ```ts   * const puppeteer = require('puppeteer');   *   * (async () => {   *   const browser = await puppeteer.launch();   *   const page = await browser.newPage();   *   let currentURL;   *   page   *     .mainFrame()   *     .waitForSelector('img')   *     .then(() => console.log('First URL with image: ' + currentURL));   *   *   for (currentURL of [   *     'https://example.com',   *     'https://google.com',   *     'https://bbc.com',   *   ]) {   *     await page.goto(currentURL);   *   }   *   await browser.close();   * })();   * ```   *   * @param selector - The selector to query and wait for.   * @param options - Options for customizing waiting behavior.   * @returns An element matching the given selector.   * @throws Throws if an element matching the given selector doesn't appear.   */  waitForSelector<Selector extends string>(    selector: Selector,    options?: WaitForSelectorOptions,  ): Promise<ElementHandle<NodeFor<Selector>> | null>;  /**   * @deprecated Use {@link Frame.waitForSelector} with the `xpath` prefix.   *   * Wait for the `xpath` to appear in page. If at the moment of calling the   * method the `xpath` already exists, the method will return immediately. If   * the xpath doesn't appear after the `timeout` milliseconds of waiting, the   * function will throw.   *   * For a code example, see the example for {@link Frame.waitForSelector}. That   * function behaves identically other than taking a CSS selector rather than   * an XPath.   *   * @param xpath - the XPath expression to wait for.   * @param options - options to configure the visiblity of the element and how   * long to wait before timing out.   */  waitForXPath(    xpath: string,    options?: WaitForSelectorOptions,  ): Promise<ElementHandle<any> | null>;  /**   * @example   * The `waitForFunction` can be used to observe viewport size change:   *   * ```ts   * const puppeteer = require('puppeteer');   *   * (async () => {   * .  const browser = await puppeteer.launch();   * .  const page = await browser.newPage();   * .  const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');   * .  page.setViewport({width: 50, height: 50});   * .  await watchDog;   * .  await browser.close();   * })();   * ```   *   * To pass arguments from Node.js to the predicate of `page.waitForFunction` function:   *   * ```ts   * const selector = '.foo';   * await frame.waitForFunction(   *   selector => !!document.querySelector(selector),   *   {}, // empty options object   *   selector   * );   * ```   *   * @param pageFunction - the function to evaluate in the frame context.   * @param options - options to configure the polling method and timeout.   * @param args - arguments to pass to the `pageFunction`.   * @returns the promise which resolve when the `pageFunction` returns a truthy value.   */  waitForFunction<    Params extends unknown[],    Func extends EvaluateFunc<Params> = EvaluateFunc<Params>,  >(    pageFunction: Func | string,    options?: FrameWaitForFunctionOptions,    ...args: Params  ): Promise<HandleFor<Awaited<ReturnType<Func>>>>;  /**   * @returns The full HTML contents of the frame, including the DOCTYPE.   */  content(): Promise<string>;  /**   * Set the content of the frame.   *   * @param html - HTML markup to assign to the page.   * @param options - Options to configure how long before timing out and at   * what point to consider the content setting successful.   */  setContent(html: string, options?: {    timeout?: number;    waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];  }): Promise<void>;  /**   * @returns The frame's `name` attribute as specified in the tag.   *   * @remarks   * If the name is empty, it returns the `id` attribute instead.   *   * @remarks   * This value is calculated once when the frame is created, and will not   * update if the attribute is changed later.   */  name(): string;  /**   * @returns The frame's URL.   */  url(): string;  /**   * @returns The parent frame, if any. Detached and main frames return `null`.   */  parentFrame(): Frame | null;  /**   * @returns An array of child frames.   */  childFrames(): Frame[];  /**   * @returns `true` if the frame has been detached. Otherwise, `false`.   */  isDetached(): boolean;  /**   * Adds a `<script>` tag into the page with the desired url or content.   *   * @param options - Options for the script.   * @returns a promise that resolves to the added tag when the script's   * `onload` event fires or when the script content was injected into the   * frame.   */  addScriptTag(    options: FrameAddScriptTagOptions,  ): Promise<ElementHandle<any>>;  /**   * Adds a `<link rel="stylesheet">` tag into the page with the desired url or   * a `<style type="text/css">` tag with the content.   *   * @param options - Options for the style link.   * @returns a promise that resolves to the added tag when the stylesheets's   * `onload` event fires or when the CSS content was injected into the   * frame.   */  addStyleTag(    options: FrameAddStyleTagOptions,  ): Promise<ElementHandle<any>>;  /**   * Clicks the first element found that matches `selector`.   *   * @remarks   * If `click()` triggers a navigation event and there's a separate   * `page.waitForNavigation()` promise to be resolved, you may end up with a   * race condition that yields unexpected results. The correct pattern for   * click and wait for navigation is the following:   *   * ```ts   * const [response] = await Promise.all([   *   page.waitForNavigation(waitOptions),   *   frame.click(selector, clickOptions),   * ]);   * ```   *   * @param selector - The selector to query for.   */  click(selector: string, options?: {    delay?: number;    button?: MouseButton;    clickCount?: number;  }): Promise<void>;  /**   * Focuses the first element that matches the `selector`.   *   * @param selector - The selector to query for.   * @throws Throws if there's no element matching `selector`.   */  focus(selector: string): Promise<void>;  /**   * Hovers the pointer over the center of the first element that matches the   * `selector`.   *   * @param selector - The selector to query for.   * @throws Throws if there's no element matching `selector`.   */  hover(selector: string): Promise<void>;  /**   * Selects a set of value on the first `<select>` element that matches the   * `selector`.   *   * @example   *   * ```ts   * frame.select('select#colors', 'blue'); // single selection   * frame.select('select#colors', 'red', 'green', 'blue'); // multiple selections   * ```   *   * @param selector - The selector to query for.   * @param values - The array of values to select. If the `<select>` has the   * `multiple` attribute, all values are considered, otherwise only the first   * one is taken into account.   * @returns the list of values that were successfully selected.   * @throws Throws if there's no `<select>` matching `selector`.   */  select(selector: string, ...values: string[]): Promise<string[]>;  /**   * Taps the first element that matches the `selector`.   *   * @param selector - The selector to query for.   * @throws Throws if there's no element matching `selector`.   */  tap(selector: string): Promise<void>;  /**   * Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character   * in the text.   *   * @remarks   * To press a special key, like `Control` or `ArrowDown`, use   * {@link Keyboard.press}.   *   * @example   *   * ```ts   * await frame.type('#mytextarea', 'Hello'); // Types instantly   * await frame.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user   * ```   *   * @param selector - the selector for the element to type into. If there are   * multiple the first will be used.   * @param text - text to type into the element   * @param options - takes one option, `delay`, which sets the time to wait   * between key presses in milliseconds. Defaults to `0`.   */  type(selector: string, text: string, options?: {    delay: number;  }): Promise<void>;  /**   * @deprecated Use `new Promise(r => setTimeout(r, milliseconds));`.   *   * Causes your script to wait for the given number of milliseconds.   *   * @remarks   * It's generally recommended to not wait for a number of seconds, but instead   * use {@link Frame.waitForSelector}, {@link Frame.waitForXPath} or   * {@link Frame.waitForFunction} to wait for exactly the conditions you want.   *   * @example   *   * Wait for 1 second:   *   * ```ts   * await frame.waitForTimeout(1000);   * ```   *   * @param milliseconds - the number of milliseconds to wait.   */  waitForTimeout(milliseconds: number): Promise<void>;  /**   * @returns the frame's title.   */  title(): Promise<string>;  /**   * @internal   */  _navigated(framePayload: Protocol.Page.Frame): void;  /**   * @internal   */  _navigatedWithinDocument(url: string): void;  /**   * @internal   */  _onLifecycleEvent(loaderId: string, name: string): void;  /**   * @internal   */  _onLoadingStopped(): void;  /**   * @internal   */  _onLoadingStarted(): void;  /**   * @internal   */  _detach(): void;}