Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface Page

Page provides methods to interact with a single tab in Chromium. One Browser instance might have multiple Page instances.

Hierarchy

Index

Properties

Methods

Properties

accessibility

accessibility: Accessibility

coverage

coverage: Coverage

keyboard

keyboard: Keyboard

Returns the virtual keyboard.

mouse

mouse: Mouse

Gets the virtual mouse.

touchscreen

touchscreen: Touchscreen

Returns the virtual touchscreen object.

tracing

tracing: Tracing

Returns the tracing object.

Methods

$

  • The method queries frame for the selector. If there's no such element within the frame, the method will resolve to null.

    Parameters

    • selector: string

    Returns Promise<null | ElementHandle<Element>>

$$

  • The method runs document.querySelectorAll within the frame. If no elements match the selector, the return value resolve to [].

    Parameters

    • selector: string

    Returns Promise<ElementHandle<Element>[]>

$$eval

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

    If pageFunction returns a Promise, then $$eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (elements: Element[]) => R | Promise<R>

      Function to be evaluated in browser context

        • (elements: Element[]): R | Promise<R>

        • Parameters

          • elements: Element[]

          Returns R | Promise<R>

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

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

    If pageFunction returns a Promise, then $$eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    • X1

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (elements: Element[], x1: UnwrapElementHandle<X1>) => R | Promise<R>

      Function to be evaluated in browser context

    • x1: X1

      First argument to pass to pageFunction

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

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

    If pageFunction returns a Promise, then $$eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    • X1

    • X2

    Parameters

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

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

    If pageFunction returns a Promise, then $$eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    • X1

    • X2

    • X3

    Parameters

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

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

    If pageFunction returns a Promise, then $$eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (elements: Element[], ...args: any[]) => R | Promise<R>

      Function to be evaluated in browser context

        • (elements: Element[], ...args: any[]): R | Promise<R>

        • Parameters

          • elements: Element[]
          • Rest ...args: any[]

          Returns R | Promise<R>

    • Rest ...args: SerializableOrJSHandle[]

      Arguments to pass to pageFunction

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

$eval

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

    If pageFunction returns a Promise, then $eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (element: Element) => R | Promise<R>

      Function to be evaluated in browser context

        • (element: Element): R | Promise<R>

        • Parameters

          • element: Element

          Returns R | Promise<R>

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

    If pageFunction returns a Promise, then $eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    • X1

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (element: Element, x1: UnwrapElementHandle<X1>) => R | Promise<R>

      Function to be evaluated in browser context

    • x1: X1

      First argument to pass to pageFunction

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

    If pageFunction returns a Promise, then $eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    • X1

    • X2

    Parameters

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

    If pageFunction returns a Promise, then $eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    • X1

    • X2

    • X3

    Parameters

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

    If pageFunction returns a Promise, then $eval would wait for the promise to resolve and return its value.

    Type parameters

    • R

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (element: Element, ...args: any[]) => R | Promise<R>

      Function to be evaluated in browser context

        • (element: Element, ...args: any[]): R | Promise<R>

        • Parameters

          • element: Element
          • Rest ...args: any[]

          Returns R | Promise<R>

    • Rest ...args: SerializableOrJSHandle[]

      Arguments to pass to pageFunction

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

$x

  • The method evaluates the XPath expression.

    Parameters

    • expression: string

      XPath expression to evaluate.

    Returns Promise<ElementHandle<Element>[]>

addListener

  • addListener(event: EventType, handler: Handler<any>): EventEmitter

addScriptTag

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

    Parameters

    Returns Promise<void>

addStyleTag

  • Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content.

    Parameters

    Returns Promise<void>

authenticate

  • authenticate(credentials: null | AuthOptions): Promise<void>

  • Provide credentials for http authentication. To disable authentication, pass null.

    Parameters

    Returns Promise<void>

bringToFront

  • bringToFront(): Promise<void>

  • Brings page to front (activates tab).

    Returns Promise<void>

browser

  • Get the browser the page belongs to.

    Returns Browser

browserContext

  • Get the browser context that the page belongs to.

    Returns BrowserContext

click

  • click(selector: string, options?: ClickOptions): 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.

    Parameters

    • selector: string

      A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.

    • Optional options: ClickOptions

      Specifies the click options.

    Returns Promise<void>

close

  • Closes the current page.

    Parameters

    Returns Promise<void>

content

  • content(): Promise<string>

  • Gets the full HTML contents of the page, including the doctype.

    Returns Promise<string>

cookies

  • cookies(...urls: string[]): Promise<Cookie[]>

  • Gets the cookies. 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.

    Parameters

    • Rest ...urls: string[]

    Returns Promise<Cookie[]>

deleteCookie

  • Deletes the specified cookies.

    Parameters

    Returns Promise<void>

emit

  • emit(event: EventType, eventData?: any): boolean

  • Parameters

    • event: EventType
    • Optional eventData: any

    Returns boolean

emulate

  • Emulates given device metrics and user agent. This method is a shortcut for setUserAgent and setViewport.

    Parameters

    Returns Promise<void>

emulateIdleState

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

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

    example
    // set idle emulation
await page.emulateIdleState({isUserActive: true, isScreenUnlocked: false});

// do some checks here
...

// clear idle emulation
await page.emulateIdleState();

    Parameters

    • Optional overrides: { isScreenUnlocked: boolean; isUserActive: boolean }

      Mock idle state. If not set, clears idle overrides

      • isScreenUnlocked: boolean
      • isUserActive: boolean

    Returns Promise<void>

emulateMediaFeatures

  • emulateMediaFeatures(features: null | MediaFeature[]): Promise<void>

  • Given an array of media feature objects, emulates CSS media features on the page. Passing null resets all.

    Parameters

    Returns Promise<void>

emulateMediaType

  • emulateMediaType(mediaType: null | "screen" | "print"): Promise<void>

  • Emulates the media.

    Parameters

    • mediaType: null | "screen" | "print"

    Returns Promise<void>

emulateTimezone

  • emulateTimezone(tz: null | string): Promise<void>

  • Changes the timezone of the page. See ICU’s metaZones.txt for a list of supported timezone IDs. Passing null disables timezone emulation.

    Parameters

    • tz: null | string

    Returns Promise<void>

evaluate

  • Evaluates a function in the browser context. If the function, passed to the frame.evaluate, returns a Promise, then frame.evaluate would wait for the promise to resolve and return its value. If the function passed into frame.evaluate returns a non-Serializable value, then frame.evaluate resolves to undefined.

    Type parameters

    Parameters

    Returns Promise<EvaluateFnReturnType<T> extends PromiseLike<U> ? U : EvaluateFnReturnType<T>>

evaluateHandle

  • evaluateHandle<HandlerType>(pageFunction: string | ((arg1: any, ...args: any[]) => any), ...args: SerializableOrJSHandle[]): Promise<HandlerType>

  • The only difference between evaluate and evaluateHandle is that evaluateHandle returns in-page object (JSHandle). If the function, passed to the evaluateHandle, returns a Promise, then evaluateHandle would wait for the promise to resolve and return its value. The TypeScript definitions assume that evaluateHandle returns a JSHandle, but if you know it's going to return an ElementHandle, pass it as the generic argument:

    Type parameters

    Parameters

    • pageFunction: string | ((arg1: any, ...args: any[]) => any)

      a function that is run within the page

    • Rest ...args: SerializableOrJSHandle[]

      arguments to be passed to the pageFunction

    Returns Promise<HandlerType>

evaluateOnNewDocument

  • 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. The function is invoked after the document was created but before any of its scripts were run. This is useful to amend JavaScript environment, e.g. to seed Math.random.

    Parameters

    Returns Promise<void>

exposeFunction

  • exposeFunction(name: string, puppeteerFunction: (...args: any[]) => any): 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.

    Parameters

    • name: string

      The name of the function on the window object.

    • puppeteerFunction: (...args: any[]) => any
        • (...args: any[]): any

        • Parameters

          • Rest ...args: any[]

          Returns any

    Returns Promise<void>

focus

  • focus(selector: string): Promise<void>

  • This method fetches an element with selector and focuses it.

    Parameters

    • selector: string

    Returns Promise<void>

frames

  • An array of all frames attached to the page.

    Returns Frame[]

goBack

  • Navigate to the previous page in history.

    Parameters

    Returns Promise<null | Response>

goForward

  • Navigate to the next page in history.

    Parameters

    Returns Promise<null | Response>

goto

  • Navigates to a URL.

    Parameters

    • url: string

      URL to navigate page to. The url should include scheme, e.g. https://

    • Optional options: DirectNavigationOptions

      The navigation parameters.

    Returns Promise<null | Response>

hover

  • 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.

    Parameters

    • selector: string

      A selector to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.

    Returns Promise<void>

isClosed

  • isClosed(): boolean

  • Indicates that the page has been closed.

    Returns boolean

isJavaScriptEnabled

  • isJavaScriptEnabled(): boolean

  • Returns boolean

    true if the page has JavaScript enabled, false otherwise.

listenerCount

  • listenerCount(event: string): number

  • Parameters

    • event: string

    Returns number

mainFrame

  • Page is guaranteed to have a main frame which persists during navigation's.

    Returns Frame

metrics

  • Gets the page metrics.

    Returns Promise<Metrics>

off

  • off(event: EventType, handler: Handler<any>): EventEmitter

  • Parameters

    • event: EventType
    • handler: Handler<any>

    Returns EventEmitter

on

  • on<K>(eventName: K, handler: (e: PageEventObj[K], ...args: any[]) => void): Page

  • Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

    Type parameters

    • K: "error" | "load" | "domcontentloaded" | "close" | "console" | "dialog" | "frameattached" | "framedetached" | "framenavigated" | "metrics" | "pageerror" | "popup" | "request" | "requestfailed" | "requestfinished" | "response" | "workercreated" | "workerdestroyed"

    Parameters

    • eventName: K
    • handler: (e: PageEventObj[K], ...args: any[]) => void

      The callback function.

    Returns Page

once

  • once<K>(eventName: K, handler: (e: PageEventObj[K], ...args: any[]) => void): Page

  • Adds a one time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

    Type parameters

    • K: "error" | "load" | "domcontentloaded" | "close" | "console" | "dialog" | "frameattached" | "framedetached" | "framenavigated" | "metrics" | "pageerror" | "popup" | "request" | "requestfailed" | "requestfinished" | "response" | "workercreated" | "workerdestroyed"

    Parameters

    • eventName: K
    • handler: (e: PageEventObj[K], ...args: any[]) => void

      The callback function.

    Returns Page

pdf

  • Generates a PDF of the page with print css media. To generate a pdf with screen media, call page.emulateMedia('screen') before calling page.pdf():

    Parameters

    • Optional options: PDFOptions

      The PDF parameters.

    Returns Promise<Buffer>

queryObjects

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

    Parameters

    • prototypeHandle: JSHandle<any>

      A handle to the object prototype.

    Returns Promise<JSHandle<any>>

reload

  • Reloads the current page.

    Parameters

    Returns Promise<Response>

removeAllListeners

removeListener

  • removeListener(event: EventType, handler: Handler<any>): EventEmitter

screenshot

  • Captures a screenshot of the page.

    Parameters

    Returns Promise<string>

  • Parameters

    Returns Promise<Buffer>

  • Parameters

    Returns Promise<string | Buffer>

select

  • 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.

    Parameters

    • selector: string

      A selector to query page for.

    • Rest ...values: string[]

      Values of options to select. If the <select> has the multiple attribute, all values are considered, otherwise only the first one is taken into account.

    Returns Promise<string[]>

setBypassCSP

  • setBypassCSP(enabled: boolean): Promise<void>

  • Toggles bypassing page's Content-Security-Policy. NOTE CSP bypassing happens at the moment of CSP initialization rather then evaluation. Usually this means that page.setBypassCSP should be called before navigating to the domain.

    Parameters

    • enabled: boolean

      sets bypassing of page's Content-Security-Policy.

    Returns Promise<void>

setCacheEnabled

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

  • Determines whether cache is enabled on the page.

    Parameters

    • Optional enabled: boolean

    Returns Promise<void>

setContent

  • Sets the page content.

    Parameters

    • html: string

      HTML markup to assign to the page.

    • Optional options: NavigationOptions

      The navigation parameters.

    Returns Promise<void>

setCookie

  • setCookie(...cookies: SetCookie[]): Promise<void>

  • Sets the cookies on the page.

    Parameters

    • Rest ...cookies: SetCookie[]

      The cookies to set.

    Returns Promise<void>

setDefaultNavigationTimeout

  • setDefaultNavigationTimeout(timeout: number): void

  • This setting will change the default maximum navigation time of 30 seconds for the following methods:

    • page.goto
    • page.goBack
    • page.goForward
    • page.reload
    • page.waitForNavigation

    Parameters

    • timeout: number

    Returns void

setDefaultTimeout

  • setDefaultTimeout(timeout: number): void

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

    • page.goBack
    • page.goForward
    • page.goto
    • page.reload
    • page.setContent
    • page.waitFor
    • page.waitForFunction
    • page.waitForNavigation
    • page.waitForRequest
    • page.waitForResponse
    • page.waitForSelector
    • page.waitForXPath

    NOTE page.setDefaultNavigationTimeout takes priority over page.setDefaultTimeout

    Parameters

    • timeout: number

    Returns void

setExtraHTTPHeaders

  • setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>

  • The extra HTTP headers will be sent with every request the page initiates.

    Parameters

    • headers: Record<string, string>

      An object containing additional http headers to be sent with every request. All header values must be strings.

    Returns Promise<void>

setGeolocation

  • setGeolocation(options: GeoOptions): Promise<void>

  • Sets the page's geolocation.

    Parameters

    Returns Promise<void>

setJavaScriptEnabled

  • setJavaScriptEnabled(enabled: boolean): Promise<void>

  • Determines whether JavaScript is enabled on the page.

    Parameters

    • enabled: boolean

    Returns Promise<void>

setOfflineMode

  • setOfflineMode(enabled: boolean): Promise<void>

  • Determines whether the offline mode is enabled.

    Parameters

    • enabled: boolean

      When true, enables the offline mode for the page.

    Returns Promise<void>

setRequestInterception

  • setRequestInterception(enabled: boolean): Promise<void>

  • Determines whether the request interception is enabled.

    Parameters

    • enabled: boolean

      When true the methods request.abort, request.continue and request.respond must be used.

    Returns Promise<void>

setUserAgent

  • setUserAgent(userAgent: string): Promise<void>

  • Specifies the User-Agent used in this page.

    Parameters

    • userAgent: string

      The user-agent to be used in the page.

    Returns Promise<void>

setViewport

  • setViewport(viewport: Viewport): Promise<void>

  • Sets the viewport of the page.

    Parameters

    • viewport: Viewport

      The viewport parameters.

    Returns Promise<void>

tap

  • 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.

    Parameters

    • selector: string

      A selector to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped.

    Returns Promise<void>

target

  • Returns Target

    The target this page was created from

title

  • title(): Promise<string>

  • Returns the page's title.

    Returns Promise<string>

type

  • type(selector: string, text: string, options?: { delay: number }): Promise<void>

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

    Parameters

    • selector: string

      A selector of an element to type into. If there are multiple elements satisfying the selector, the first will be used.

    • text: string
    • Optional options: { delay: number }
      • delay: number

    Returns Promise<void>

url

  • url(): string

  • The page's URL. This is a shortcut for page.mainFrame().url()

    Returns string

viewport

  • Gets the page viewport.

    Returns Viewport

waitFor

waitForFileChooser

  • In non-headless Chromium, this method results in the native file picker dialog not showing up for the user. This method is typically coupled with an action that triggers file choosing. This must be called before the file chooser is launched. It will not return a currently active file chooser.

    Parameters

    Returns Promise<FileChooser>

waitForFunction

waitForNavigation

waitForRequest

  • Parameters

    Returns Promise<Request>

waitForResponse

  • Parameters

    Returns Promise<Response>

waitForSelector

waitForTimeout

  • waitForTimeout(milliseconds: number): Promise<void>

  • 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 Frame.waitForSelector, Frame.waitForXPath or Frame.waitForFunction to wait for exactly the conditions you want.

    example

    Wait for 1 second:

    await frame.waitForTimeout(1000);

    Parameters

    • milliseconds: number

      the number of milliseconds to wait.

    Returns Promise<void>

waitForXPath

workers

  • This method returns all of the dedicated WebWorkers associated with the page.

    Returns Worker[]

Generated using TypeDoc