Page

page.goto

Signature: page.goto(url, options?)

• url : <string> The target URL address. e.g. https://github.com
• options? : <object>
  • timeout? : <number> Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the Page.setDefaultNavigationTimeout() or Page.setDefaultTimeout() methods.
  • waitUnitil? : <"load" | "documentloaded" | "networkidle" | "commit"> When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
    • 'load' : consider navigation to be finished when the load event is fired.
    • 'domcontentloaded' : consider navigation to be finished when the DOMContentLoaded event is fired.
    • 'networkidle' : consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
• Returns <Promise<HTTPResponse | null>>

Example

await page.goto('https://github.com')

page.goForward

Signature: page.goForward(options?)

• options? <object>

  • timeout? <number> Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the Page.setDefaultNavigationTimeout() or Page.setDefaultTimeout() methods.
  • waitUntil? When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
    • 'load' consider navigation to be finished when the load event is fired.
    • 'domcontentloaded' : consider navigation to be finished when the DOMContentLoaded event is fired.
    • 'networkidle' : consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.

• Returns <Promise<HTTPResponse | null>>

This method navigate to the next page in history.

Example

await page.goForward();

page.goBack

Signature: page.goBack(options?)

• timeout? <number> Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the Page.setDefaultNavigationTimeout() or Page.setDefaultTimeout() methods.
• waitUntil? When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
  • 'load' consider navigation to be finished when the load event is fired.
  • 'domcontentloaded' : consider navigation to be finished when the DOMContentLoaded event is fired.
  • 'networkidle' : consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
• Returns Promise<HTTPResponse | null>

This method navigate to the previous page in history.

page.url

Signature: page.url()

• Returns <Promise<string>>

Shortcut for page.mainFrame().url().

page.content

Signature: page.content()

• Returns <Promise<string>>

The full HTML contents of the frame, including the DOCTYPE.

page.evaluate

Signature: page.evaluate(pageFunction, args?)

• pageFunction <Function | string> a function that is run within the page

• args? arguments to be passed to the pageFunction

• Returns <Promise<Awaited<ReturnType<typeof pageFunction>>>> the return value of pageFunction.

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.

page.evaluateHandle

Signature: page.evaluateHandle(pageFunction, args?)

• Returns Promise<HandleFor<Awaited<ReturnType<typeof pageFunction>>>>

page.screenshot(options?)

• options? <object>
  • path? <string> The file path to save the image to. The screenshot type will be inferred from file extension. If path is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk.
  • quality? <number> The quality of the image, between 0-100. Not applicable to png images.
  • fullPage? <boolean> When true, takes a screenshot of the full scrollable page. Defaults to false.
  • type? <'png' | 'jpeg'> Specify screenshot type, can be either jpeg or png. Defaults to 'png'.
  • clip? <object> An object which specifies clipping region of the page. Should have the following fields:
    • x <number> x-coordinate of top-left corner of clip area.
    • y <number> y-coordinate of top-left corner of clip area.
    • width <number> width of clipping area.
    • height <number> height of clipping area.
  • omitBackground? <boolean> Hides default white background and allows capturing screenshots with transparency. Defaults to false.
• Returns Promise<Buffer | string>;

page.click

Signature: page.click(selector, options?)

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

• options? <object>

  • delay? <number> Time to wait between mousedown and mouseup in milliseconds.
  • button? <'left' | 'right' | 'middle'> Defaults to 'left'.
  • clickCount? <number> Count of button clicks, defaults to 1.
  • position? <object> Offset for the clickable point relative to the top-left corder of the border box.
    • x <number> x-offset for the clickable point relative to the top-left corder of the border box.
    • y <number> y-offset for the clickable point relative to the top-left corder of the border box.

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

page.dblclick

Signature: page.dblclick(selector, options?)

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

• options? <object>

  • delay? <number> Time to wait between mousedown and mouseup in milliseconds.
  • button? <'left' | 'right' | 'middle'> Defaults to 'left'.
  • clickCount? <number> Count of button clicks, defaults to 1.
  • position? <object> Offset for the clickable point relative to the top-left corder of the border box.
    • x <number> x-offset for the clickable point relative to the top-left corder of the border box.
    • y <number> y-offset for the clickable point relative to the top-left corder of the border box.

• Returns <Promise<void>>

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

page.focus

Signature: page.focus(selector)

• selector <string> A selector of an element to focus. If there are multiple elements satisfying the selector, the first will be focused.
• Returns <Promise<void>> This method fetches an element with selector and focuses it. If there's no element matching selector, the method throws an error.

page.get

Signature: page.get(selector)

• selector <string> A selector to use when resolving DOM element.

Returns <Locator>

The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved to the element immediately before performing an action, so a series of actions on the same locator can in fact be performed on different DOM elements. That would happen if the DOM structure between those actions has changed.

page.getByText

Signature: page.getByText(text)

• text <string> The label text.
• Returns <Locator>

page.getByClass

Signature: page.getByClass(className)

• className <string>
• Returns <Locator>

page.getByTestId

Signature: page.getByTestId(testId)

• testId <string>
• Returns <Locator>

page.queryElementByText

Signature: page.queryElementByText(text)

• text <string>
• Returns <ElementHandle>

page.queryElementByClass

Signature: page.queryElementByClass(className)

• className <string>
• Returns <ElementHandle>

page.queryElementByTestId

Signature: page.queryElementByTestId(testId)

• testId <string>
• Returns <ElementHandle>

page.waitForNavigation

Signature: page.waitForNavigation(options?)

• options? <object>
  • timeout? <number> Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the Page.setDefaultNavigationTimeout() or Page.setDefaultTimeout() methods.
  • waitUntil? When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
    • 'load' consider navigation to be finished when the load event is fired.
    • 'domcontentloaded' : consider navigation to be finished when the DOMContentLoaded event is fired.
    • 'networkidle' : consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
• Returns: <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.

Example

const [response] = await Promise.all([
  page.waitForNavigation(), // The promise resolves after navigation has finished
  page.click('a.my-link'), // Clicking the link will indirectly cause a navigation
]);

page.waitForLoadState

Signature: page.waitForLoadState(state?, options?)

• state? <"load"|"domcontentloaded"|"networkidle"> Optional load state to wait for, defaults to load. If the state has been already reached while loading current document, the method resolves immediately. Can be one of:

  • load wait for the load event to be fired.
  • domcontentloaded wait for the DOMContentLoaded event to be fired.
  • networkidle wait until there are no network connections for at least 500 ms.

• options? <object>

  • timeout? <number> Maximum operation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout.

• Returns <Promise<void>>

Returns when the required load state has been reached.

This resolves when the page reaches a required load state, load by default. The navigation must have been committed when this method is called. If current document has already reached the required state, resolves immediately.

page.waitForRequest

Signature: page.waitForRequest(urlOrPredicate, options?)

• urlOrPredicate <string | RegExp | function(Request):boolean | Promise<boolean>> Request URL string, regex or predicate receiving Request object.#
• options? <object>
  • timeout? <number> Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. The default value can be changed by using the page.setDefaultTimeout(timeout) method.
• Returns <Promise<Request>>

page.waitForRequestFailed

Signature: page.waitForRequestFailed(optionsOrPredicate)

• optionsOrPredicate <function | object>
  • predicate? <(request: Request) => boolean | Promise<boolean>> receives a request object and resolves to truthy value when the waiting should resolve.
  • timeout? <number> Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. The default value can be changed by using the page.setDefaultTimeout(timeout) method.

Returns <Promise<Request>>

Waits for the matching request failed and returns it.

page.waitForRequestFinished

Signature: page.waitForRequestFinished(optionsOrPredicate)

• optionsOrPredicate <function | object>
  • predicate? <(request: Request) => boolean | Promise<boolean>> receives a request object and resolves to truthy value when the waiting should resolve.
  • timeout? <number> Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. The default value can be changed by using the page.setDefaultTimeout(timeout) method.

Returns <Promise<Request>>

Waits for the matching request finished and returns it.

page.waitForResponse

Signature: page.waitForResponse(urlOrPredicate, options?)

• urlOrPredicate <string | RegExp | function(Response):boolean | Promise<boolean>> Request URL string, regex or predicate receiving Response object. When a baseURL via the context options was provided and the passed URL is a path, it gets merged via the new URL() constructor.
• options? <object>
  • timeout? <number> Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.
• Returns: <Promise<Response>>

Waits for the matching response and returns it.