Skip to main content
Module

x/puppeteer/mod.ts>Page

A port of puppeteer running on Deno
Latest
class Page
extends EventEmitter
Re-export
import { Page } from "https://deno.land/x/puppeteer@16.2.0/mod.ts";
Page provides methods to interact with a single tab or extension background page in Chromium.

::note

One Browser instance might have multiple Page instances.

::

Examples

This example creates a page, navigates it to a URL, and then saves a screenshot:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({path: 'screenshot.png'});
  await browser.close();
})();

The Page class extends from Puppeteer's EventEmitter class and will emit various events which are documented in the PageEmittedEvents enum.

This example logs a message for a single page load event:

page.once('load', () => console.log('Page loaded!'));

To unsubscribe from events use the Page.off method:

function logRequest(interceptedRequest) {
  console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.off('request', logRequest);

Constructors

new
Page(
client: CDPSession,
target: Target,
ignoreHTTPSErrors: boolean,
screenshotTaskQueue: TaskQueue,
)

Properties

readonly
accessibility: Accessibility
readonly
coverage: Coverage
readonly
keyboard: Keyboard
readonly
mouse: Mouse
readonly
touchscreen: Touchscreen
readonly
tracing: Tracing

Methods

_client(): CDPSession
$<Selector extends string>(selector: Selector): Promise<ElementHandle<NodeFor<Selector>> | null>

Runs document.querySelector within the page. If no element matches the selector, the return value resolves to null.

$$<Selector extends string>(selector: Selector): Promise<Array<ElementHandle<NodeFor<Selector>>>>

The method runs document.querySelectorAll within the page. If no elements match the selector, the return value resolves to [].

$$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>>>

This method runs Array.from(document.querySelectorAll(selector)) within the page and passes the result as the first argument to the pageFunction.

$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>>>

This method runs document.querySelector within the page and passes the result as the first argument to the pageFunction.

$x(expression: string): Promise<Array<ElementHandle<any>>>

The method evaluates the XPath expression relative to the page document as its context node. If there are no such elements, the method resolves to an empty array.

addScriptTag(options: { url?: string; path?: string; content?: string; type?: string; id?: string; }): Promise<ElementHandle<any>>

Adds a <script> tag into the page with the desired URL or content.

addStyleTag(options: { url?: string; path?: string; content?: string; }): 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.

authenticate(credentials: Credentials): Promise<void>

Provide credentials for HTTP authentication.

bringToFront(): Promise<void>

Brings page to front (activates tab).

browser(): Browser

Get the browser the page belongs to.

browserContext(): BrowserContext

Get the browser context that the page belongs to.

click(selector: string, options?: { delay?: number; button?: MouseButton; clickCount?: number; }): Promise<void>

This method fetches an element with selector, scrolls it into view if needed, and then uses Page.mouse to click in the center of the element. If there's no element matching selector, the method throws an error.

close(options?: { runBeforeUnload?: boolean; }): Promise<void>
content(): Promise<string>
cookies(...urls: string[]): Promise<Protocol.Network.Cookie[]>

If no URLs are specified, this method returns cookies for the current page URL. If URLs are specified, only cookies for those URLs are returned.

createPDFStream(options?: PDFOptions): Promise<ReadableStream>

Generates a PDF of the page with the print CSS media type.

deleteCookie(...cookies: Protocol.Network.DeleteCookiesRequest[]): Promise<void>
emulate(options: { viewport: Viewport; userAgent: string; }): Promise<void>

Emulates given device metrics and user agent.

emulateCPUThrottling(factor: number | null): Promise<void>

Enables CPU throttling to emulate slow CPUs.

emulateIdleState(overrides?: { isUserActive: boolean; isScreenUnlocked: boolean; }): Promise<void>

Emulates the idle state. If no arguments set, clears idle state emulation.

emulateMediaFeatures(features?: MediaFeature[]): Promise<void>
emulateMediaType(type?: string): Promise<void>
emulateNetworkConditions(networkConditions: NetworkConditions | null): Promise<void>
emulateTimezone(timezoneId?: string): Promise<void>
emulateVisionDeficiency(type?: Protocol.Emulation.SetEmulatedVisionDeficiencyRequest["type"]): Promise<void>

Simulates the given vision deficiency on the page.

evaluate<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, ...args: Params): Promise<Awaited<ReturnType<Func>>>

Evaluates a function in the page's context and returns the result.

If the function passed to page.evaluteHandle returns a Promise, the function will wait for the promise to resolve and return its value.

evaluateHandle<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, ...args: Params): Promise<HandleFor<Awaited<ReturnType<Func>>>>
evaluateOnNewDocument<Params extends unknown[], Func extends (...args: Params) => unknown = (...args: Params) => unknown>(pageFunction: Func | string, ...args: Params): Promise<void>

Adds a function which would be invoked in one of the following scenarios:

  • whenever the page is navigated

  • whenever the child frame is attached or navigated. In this case, the function is invoked in the context of the newly attached frame.

The function is invoked after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed Math.random.

exposeFunction(name: string, pptrFunction: Function | { default: Function; }): Promise<void>

The method adds a function called name on the page's window object. When called, the function executes puppeteerFunction in node.js and returns a Promise which resolves to the return value of puppeteerFunction.

If the puppeteerFunction returns a Promise, it will be awaited.

::note

Functions installed via page.exposeFunction survive navigations.

::note

focus(selector: string): Promise<void>

This method fetches an element with selector and focuses it. If there's no element matching selector, the method throws an error.

frames(): Frame[]
goBack(options?: WaitForOptions): Promise<HTTPResponse | null>

This method navigate to the previous page in history.

goForward(options?: WaitForOptions): Promise<HTTPResponse | null>

This method navigate to the next page in history.

goto(url: string, options?: WaitForOptions & { referer?: string; }): Promise<HTTPResponse | null>
hover(selector: string): Promise<void>

This method fetches an element with selector, scrolls it into view if needed, and then uses Page.mouse to hover over the center of the element. If there's no element matching selector, the method throws an error.

isClosed(): boolean

Indicates that the page has been closed.

mainFrame(): Frame
metrics(): Promise<Metrics>
off<K extends keyof PageEventObject>(eventName: K, handler: (event: PageEventObject[K]) => void): EventEmitter
on<K extends keyof PageEventObject>(eventName: K, handler: (event: PageEventObject[K]) => void): EventEmitter
Listen to page events.

::note

This method exists to define event typings and handle proper wireup of cooperative request interception. Actual event listening and dispatching is delegated to EventEmitter.

::

once<K extends keyof PageEventObject>(eventName: K, handler: (event: PageEventObject[K]) => void): EventEmitter
pdf(options?: PDFOptions): Promise<Uint8Array>
queryObjects<Prototype>(prototypeHandle: JSHandle<Prototype>): Promise<JSHandle<Prototype[]>>

This method iterates the JavaScript heap and finds all objects with the given prototype.

reload(options?: WaitForOptions): Promise<HTTPResponse | null>
screenshot(options?: ScreenshotOptions): Promise<Buffer | string>
select(selector: string, ...values: string[]): Promise<string[]>

Triggers a change and input event once all the provided options have been selected. If there's no <select> element matching selector, the method throws an error.

setBypassCSP(enabled: boolean): Promise<void>

Toggles bypassing page's Content-Security-Policy.

setCacheEnabled(enabled?: boolean): Promise<void>

Toggles ignoring cache for each request based on the enabled state. By default, caching is enabled.

setContent(html: string, options?: WaitForOptions): Promise<void>
setCookie(...cookies: Protocol.Network.CookieParam[]): Promise<void>
setDefaultNavigationTimeout(timeout: number): void

This setting will change the default maximum navigation time for the following methods and related shortcuts:

  • Page.goBack | page.goBack(options)

  • Page.goForward | page.goForward(options)

  • Page.goto | page.goto(url,options)

  • Page.reload | page.reload(options)

  • Page.setContent | page.setContent(html,options)

  • Page.waitForNavigation | page.waitForNavigation(options)

setDefaultTimeout(timeout: number): void
setDragInterception(enabled: boolean): Promise<void>
setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>
The extra HTTP headers will be sent with every request the page initiates.

::tip

All HTTP header names are lowercased. (HTTP headers are case-insensitive, so this shouldn’t impact your server code.)

::

:::note

page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.

::

setGeolocation(options: GeolocationOptions): Promise<void>

Sets the page's geolocation.

setJavaScriptEnabled(enabled: boolean): Promise<void>
setOfflineMode(enabled: boolean): Promise<void>
setRequestInterception(value: boolean): Promise<void>

Activating request interception enables HTTPRequest.abort, HTTPRequest.continue and HTTPRequest.respond methods. This provides the capability to modify network requests that are made by a page.

Once request interception is enabled, every request will stall unless it's continued, responded or aborted; or completed using the browser cache.

Enabling request interception disables page caching.

See the Request interception guide for more details.

setUserAgent(userAgent: string, userAgentMetadata?: Protocol.Emulation.UserAgentMetadata): Promise<void>
setViewport(viewport: Viewport): Promise<void>

page.setViewport will resize the page. A lot of websites don't expect phones to change size, so you should set the viewport before navigating to the page.

In the case of multiple pages in a single browser, each page can have its own viewport size.

tap(selector: string): Promise<void>

This method fetches an element with selector, scrolls it into view if needed, and then uses Page.touchscreen to tap in the center of the element. If there's no element matching selector, the method throws an error.

target(): Target
title(): Promise<string>
type(
selector: string,
text: string,
options?: { delay: number; },
): Promise<void>

Sends a keydown, keypress/input, and keyup event for each character in the text.

To press a special key, like Control or ArrowDown, use Keyboard.press.

url(): string
viewport(): Viewport | null
waitForFileChooser(options?: WaitTimeoutOptions): Promise<FileChooser>
This method is typically coupled with an action that triggers file choosing.

::caution

This must be called before the file chooser is launched. It will not return a currently active file chooser.

::

waitForFrame(urlOrPredicate: string | ((frame: Frame) => boolean | Promise<boolean>), options?: { timeout?: number; }): Promise<Frame>
waitForFunction<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(
pageFunction: Func | string,
options?: { timeout?: number; polling?: string | number; },
...args: Params,
): Promise<HandleFor<Awaited<ReturnType<Func>>>>

Waits for a function to finish evaluating in the page's context.

waitForNavigation(options?: WaitForOptions): Promise<HTTPResponse | null>

Waits for the page to navigate to a new URL or to reload. It is useful when you run code that will indirectly cause the page to navigate.

waitForNetworkIdle(options?: { idleTime?: number; timeout?: number; }): Promise<void>
waitForRequest(urlOrPredicate: string | ((req: HTTPRequest) => boolean | Promise<boolean>), options?: { timeout?: number; }): Promise<HTTPRequest>
waitForResponse(urlOrPredicate: string | ((res: HTTPResponse) => boolean | Promise<boolean>), options?: { timeout?: number; }): Promise<HTTPResponse>
waitForSelector<Selector extends string>(selector: Selector, options?: Exclude<WaitForSelectorOptions, "root">): Promise<ElementHandle<NodeFor<Selector>> | null>

Wait for the selector to appear in page. If at the moment of calling the method the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout milliseconds of waiting, the function will throw.

This method works across navigations:

const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  let currentURL;
  page
    .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();
})();
deprecated
waitForTimeout(milliseconds: number): Promise<void>
waitForXPath(xpath: string, options?: { visible?: boolean; hidden?: boolean; timeout?: number; }): Promise<ElementHandle<any> | null>

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.

This method works across navigation

const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  let currentURL;
  page
    .waitForXPath('//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();
})();
workers(): WebWorker[]

Static Methods

_create(
client: CDPSession,
target: Target,
ignoreHTTPSErrors: boolean,
defaultViewport: Viewport | null,
screenshotTaskQueue: TaskQueue,
): Promise<Page>