UNPKG

puppeteer-core

Version:

A high-level API to control headless Chrome over the DevTools Protocol

160 lines 5.61 kB
/** * Copyright 2017 Google Inc. All rights reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ import { Protocol } from 'devtools-protocol'; import { CDPSession } from './Connection.js'; import { IsolatedWorld } from './IsolatedWorld.js'; import { EvaluateFunc, HandleFor } from './types.js'; /** * @public */ export declare const EVALUATION_SCRIPT_URL = "pptr://__puppeteer_evaluation_script__"; /** * Represents a context for JavaScript execution. * * @example * A {@link Page} can have several execution contexts: * * - Each {@link Frame} of a {@link Page | page} has a "default" execution * context that is always created after frame is attached to DOM. This context * is returned by the {@link Frame.executionContext} method. * - Each {@link https://developer.chrome.com/extensions | Chrome extensions} * creates additional execution contexts to isolate their code. * * @remarks * By definition, each context is isolated from one another, however they are * all able to manipulate non-JavaScript resources (such as DOM). * * @remarks * Besides pages, execution contexts can be found in * {@link WebWorker | workers}. * * @internal */ export declare class ExecutionContext { #private; /** * @internal */ _client: CDPSession; /** * @internal */ _world?: IsolatedWorld; /** * @internal */ _contextId: number; /** * @internal */ _contextName: string; /** * @internal */ constructor(client: CDPSession, contextPayload: Protocol.Runtime.ExecutionContextDescription, world?: IsolatedWorld); /** * Evaluates the given function. * * @example * * ```ts * const executionContext = await page.mainFrame().executionContext(); * const result = await executionContext.evaluate(() => Promise.resolve(8 * 7))* ; * console.log(result); // prints "56" * ``` * * @example * A string can also be passed in instead of a function: * * ```ts * console.log(await executionContext.evaluate('1 + 2')); // prints "3" * ``` * * @example * Handles can also be passed as `args`. They resolve to their referenced object: * * ```ts * const oneHandle = await executionContext.evaluateHandle(() => 1); * const twoHandle = await executionContext.evaluateHandle(() => 2); * const result = await executionContext.evaluate( * (a, b) => a + b, * oneHandle, * twoHandle * ); * await oneHandle.dispose(); * await twoHandle.dispose(); * console.log(result); // prints '3'. * ``` * * @param pageFunction - The function to evaluate. * @param args - Additional arguments to pass into the function. * @returns The result of evaluating the function. If the result is an object, * a vanilla object containing the serializable properties of the result is * returned. */ evaluate<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, ...args: Params): Promise<Awaited<ReturnType<Func>>>; /** * Evaluates the given function. * * Unlike {@link ExecutionContext.evaluate | evaluate}, this method returns a * handle to the result of the function. * * This method may be better suited if the object cannot be serialized (e.g. * `Map`) and requires further manipulation. * * @example * * ```ts * const context = await page.mainFrame().executionContext(); * const handle: JSHandle<typeof globalThis> = await context.evaluateHandle( * () => Promise.resolve(self) * ); * ``` * * @example * A string can also be passed in instead of a function. * * ```ts * const handle: JSHandle<number> = await context.evaluateHandle('1 + 2'); * ``` * * @example * Handles can also be passed as `args`. They resolve to their referenced object: * * ```ts * const bodyHandle: ElementHandle<HTMLBodyElement> = * await context.evaluateHandle(() => { * return document.body; * }); * const stringHandle: JSHandle<string> = await context.evaluateHandle( * body => body.innerHTML, * body * ); * console.log(await stringHandle.jsonValue()); // prints body's innerHTML * // Always dispose your garbage! :) * await bodyHandle.dispose(); * await stringHandle.dispose(); * ``` * * @param pageFunction - The function to evaluate. * @param args - Additional arguments to pass into the function. * @returns A {@link JSHandle | handle} to the result of evaluating the * function. If the result is a `Node`, then this will return an * {@link ElementHandle | element handle}. */ evaluateHandle<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, ...args: Params): Promise<HandleFor<Awaited<ReturnType<Func>>>>; } //# sourceMappingURL=ExecutionContext.d.ts.map