Skip to main content
Page provides methods to interact with a single tab in a browser. Each page has a main frame and can have child frames.

​
Inheritance

Extends: ChannelOwner Implements: EventEmitter

​
Events

  • load: Emitted when the load event is fired
  • domcontentloaded: Emitted when DOMContentLoaded event is fired
  • close: Emitted when page is closed
  • crash: Emitted when page crashes
  • console: Emitted when console message is logged
  • dialog: Emitted when a dialog appears
  • download: Emitted when download starts
  • filechooser: Emitted when file chooser opens
  • frameattached: Emitted when frame is attached
  • framedetached: Emitted when frame is detached
  • framenavigated: Emitted when frame navigates
  • pageerror: Emitted when uncaught exception occurs
  • popup: Emitted when popup is opened
  • request: Emitted when request is made
  • response: Emitted when response is received
  • requestfailed: Emitted when request fails
  • requestfinished: Emitted when request finishes
  • websocket: Emitted when WebSocket is created
  • worker: Emitted when worker is created

​
Properties

​
keyboard

​
keyboard
Keyboard
Keyboard input instance.

​
mouse

​
mouse
Mouse
Mouse input instance.

​
touchscreen

​
touchscreen
Touchscreen
Touchscreen input instance.

​
request

​
request
APIRequestContext
API request context.

​
clock

​
clock
Clock
Clock instance for time control.

​
coverage

​
coverage
Coverage
Coverage instance (Chromium only).

​
goto

Navigates to a URL. 
goto(url: string, options?: GotoOptions): Promise<Response | null>
​
url
string
required
URL to navigate to
​
options
GotoOptions
Navigation options
  • timeout (number): Maximum time in milliseconds
  • waitUntil (‘load’ | ‘domcontentloaded’ | ‘networkidle’ | ‘commit’): When to consider navigation succeeded
  • referer (string): Referer header value
Returns: Promise<Response | null> - Main resource response

​
reload

Reloads the page. 
reload(options?: ReloadOptions): Promise<Response | null>
​
options
ReloadOptions
Reload options (same as goto)
Returns: Promise<Response | null> - Main resource response

​
goBack

Navigates to the previous page in history. 
goBack(options?: NavigationOptions): Promise<Response | null>
​
options
NavigationOptions
Navigation options
Returns: Promise<Response | null> - Main resource response

​
goForward

Navigates to the next page in history. 
goForward(options?: NavigationOptions): Promise<Response | null>
​
options
NavigationOptions
Navigation options
Returns: Promise<Response | null> - Main resource response

​
waitForNavigation

Waits for navigation to finish. 
waitForNavigation(options?: WaitForNavigationOptions): Promise<Response | null>
​
options
WaitForNavigationOptions
Wait options
  • url (string | RegExp): URL pattern to wait for
  • waitUntil (string): When to consider navigation succeeded
  • timeout (number): Maximum wait time
Returns: Promise<Response | null> - Response

​
waitForLoadState

Waits for load state to be reached. 
waitForLoadState(state?: 'load' | 'domcontentloaded' | 'networkidle', options?: TimeoutOptions): Promise<void>
​
state
string
Load state to wait for (default: ‘load’)
​
options
TimeoutOptions
Timeout options
Returns: Promise<void>

​
waitForURL

Waits for page to navigate to matching URL. 
waitForURL(url: string | RegExp, options?: WaitForURLOptions): Promise<void>
​
url
string | RegExp
required
URL pattern to wait for
​
options
WaitForURLOptions
Wait options
Returns: Promise<void>

​
Selector Methods

​
$

Finds an element matching the selector. 
$(selector: string, options?: { strict?: boolean }): Promise<ElementHandle | null>
​
selector
string
required
Selector to query
​
options
object
  • strict (boolean): Throw if multiple elements match
Returns: Promise<ElementHandle | null> - Element handle or null

​
$$

Finds all elements matching the selector. 
$$(selector: string): Promise<ElementHandle[]>
​
selector
string
required
Selector to query
Returns: Promise<ElementHandle[]> - Array of element handles

​
locator

Creates a locator. 
locator(selector: string, options?: LocatorOptions): Locator
​
selector
string
required
Selector to locate
​
options
LocatorOptions
Locator options
  • hasText (string | RegExp): Matches elements containing text
  • hasNotText (string | RegExp): Matches elements not containing text
  • has (Locator): Matches elements containing another locator
  • hasNot (Locator): Matches elements not containing another locator
Returns: Locator - Locator instance

​
getByRole

Creates a locator by ARIA role. 
getByRole(role: string, options?: ByRoleOptions): Locator
​
role
string
required
ARIA role
​
options
ByRoleOptions
Role options
Returns: Locator - Locator instance

​
getByText

Creates a locator by text content. 
getByText(text: string | RegExp, options?: { exact?: boolean }): Locator
​
text
string | RegExp
required
Text to match
​
options
object
  • exact (boolean): Exact match
Returns: Locator - Locator instance

​
getByLabel

Creates a locator by label text. 
getByLabel(text: string | RegExp, options?: { exact?: boolean }): Locator
​
text
string | RegExp
required
Label text to match
​
options
object
  • exact (boolean): Exact match
Returns: Locator - Locator instance

​
getByPlaceholder

Creates a locator by placeholder text. 
getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): Locator
​
text
string | RegExp
required
Placeholder text to match
​
options
object
  • exact (boolean): Exact match
Returns: Locator - Locator instance

​
getByAltText

Creates a locator by alt text. 
getByAltText(text: string | RegExp, options?: { exact?: boolean }): Locator
​
text
string | RegExp
required
Alt text to match
​
options
object
  • exact (boolean): Exact match
Returns: Locator - Locator instance

​
getByTitle

Creates a locator by title attribute. 
getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator
​
text
string | RegExp
required
Title to match
​
options
object
  • exact (boolean): Exact match
Returns: Locator - Locator instance

​
getByTestId

Creates a locator by test ID. 
getByTestId(testId: string | RegExp): Locator
​
testId
string | RegExp
required
Test ID to match
Returns: Locator - Locator instance

​
Action Methods

​
click

Clicks an element. 
click(selector: string, options?: ClickOptions): Promise<void>
​
selector
string
required
Selector to click
​
options
ClickOptions
Click options
  • button (‘left’ | ‘right’ | ‘middle’): Mouse button
  • clickCount (number): Number of clicks
  • delay (number): Delay between mousedown and mouseup
  • position (object): Click position
  • modifiers (string[]): Modifier keys
  • force (boolean): Force click even if element is not actionable
  • noWaitAfter (boolean): Don’t wait for navigation
  • timeout (number): Maximum time in milliseconds
Returns: Promise<void>

​
dblclick

Double clicks an element. 
dblclick(selector: string, options?: DblClickOptions): Promise<void>

​
fill

Fills an input field. 
fill(selector: string, value: string, options?: FillOptions): Promise<void>
​
selector
string
required
Selector to fill
​
value
string
required
Value to fill
​
options
FillOptions
Fill options
Returns: Promise<void>

​
type

Types text into an element. 
type(selector: string, text: string, options?: TypeOptions): Promise<void>
​
selector
string
required
Selector to type into
​
text
string
required
Text to type
​
options
TypeOptions
Type options
  • delay (number): Delay between key presses in milliseconds
  • timeout (number): Maximum time
Returns: Promise<void>

​
press

Presses a key. 
press(selector: string, key: string, options?: PressOptions): Promise<void>
​
selector
string
required
Selector to focus
​
key
string
required
Key to press (e.g., ‘Enter’, ‘ArrowDown’)
​
options
PressOptions
Press options
Returns: Promise<void>

​
check

Checks a checkbox. 
check(selector: string, options?: CheckOptions): Promise<void>

​
uncheck

Unchecks a checkbox. 
uncheck(selector: string, options?: CheckOptions): Promise<void>

​
selectOption

Selects options in a <select> element. 
selectOption(selector: string, values: string | string[] | SelectOption | SelectOption[], options?: SelectOptionOptions): Promise<string[]>
​
selector
string
required
Selector to select from
​
values
string | string[] | SelectOption | SelectOption[]
required
Values to select
​
options
SelectOptionOptions
Select options
Returns: Promise<string[]> - Array of selected values

​
hover

Hovers over an element. 
hover(selector: string, options?: HoverOptions): Promise<void>

​
tap

Taps an element (mobile). 
tap(selector: string, options?: TapOptions): Promise<void>

​
dragAndDrop

Drags and drops an element. 
dragAndDrop(source: string, target: string, options?: DragAndDropOptions): Promise<void>
​
source
string
required
Source element selector
​
target
string
required
Target element selector
​
options
DragAndDropOptions
Drag options
Returns: Promise<void>

​
Content Methods

​
content

Returns page HTML content. 
content(): Promise<string>
Returns: Promise<string> - Full HTML content

​
setContent

Sets page HTML content. 
setContent(html: string, options?: SetContentOptions): Promise<void>
​
html
string
required
HTML content to set
​
options
SetContentOptions
Set content options
Returns: Promise<void>

​
title

Returns page title. 
title(): Promise<string>
Returns: Promise<string> - Page title

​
url

Returns page URL. 
url(): string
Returns: string - Current URL

​
textContent

Returns element’s text content. 
textContent(selector: string, options?: TimeoutOptions): Promise<string | null>

​
innerText

Returns element’s inner text. 
innerText(selector: string, options?: TimeoutOptions): Promise<string>

​
innerHTML

Returns element’s inner HTML. 
innerHTML(selector: string, options?: TimeoutOptions): Promise<string>

​
getAttribute

Returns element’s attribute value. 
getAttribute(selector: string, name: string, options?: TimeoutOptions): Promise<string | null>

​
State Methods

​
isVisible

Checks if element is visible. 
isVisible(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isHidden

Checks if element is hidden. 
isHidden(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isEnabled

Checks if element is enabled. 
isEnabled(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isDisabled

Checks if element is disabled. 
isDisabled(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isChecked

Checks if checkbox is checked. 
isChecked(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isEditable

Checks if element is editable. 
isEditable(selector: string, options?: TimeoutOptions): Promise<boolean>

​
Evaluation Methods

​
evaluate

Evaluates JavaScript in page context. 
evaluate<R, Arg>(pageFunction: Function | string, arg?: Arg): Promise<R>
​
pageFunction
Function | string
required
Function to evaluate
​
arg
any
Argument to pass to function
Returns: Promise<R> - Evaluation result

​
evaluateHandle

Evaluates and returns a JSHandle. 
evaluateHandle<R, Arg>(pageFunction: Function | string, arg?: Arg): Promise<JSHandle<R>>

​
$eval

Evaluates function on an element. 
$eval<R, Arg>(selector: string, pageFunction: Function, arg?: Arg): Promise<R>

​
$$eval

Evaluates function on multiple elements. 
$$eval<R, Arg>(selector: string, pageFunction: Function, arg?: Arg): Promise<R>

​
Frame Methods

​
mainFrame

Returns the main frame. 
mainFrame(): Frame
Returns: Frame - Main frame

​
frames

Returns all frames. 
frames(): Frame[]
Returns: Frame[] - Array of frames

​
frame

Finds a frame by name or URL. 
frame(frameSelector: string | { name?: string, url?: string | RegExp }): Frame | null
​
frameSelector
string | object
required
Frame name or URL pattern
Returns: Frame | null - Matching frame or null

​
frameLocator

Creates a frame locator. 
frameLocator(selector: string): FrameLocator
​
selector
string
required
Frame selector
Returns: FrameLocator - Frame locator instance

​
Utility Methods

​
screenshot

Takes a screenshot. 
screenshot(options?: ScreenshotOptions): Promise<Buffer>
​
options
ScreenshotOptions
Screenshot options
  • path (string): File path to save to
  • type (‘png’ | ‘jpeg’): Image type
  • quality (number): JPEG quality (0-100)
  • fullPage (boolean): Capture full page
  • clip (object): Clip area
  • omitBackground (boolean): Transparent background
  • timeout (number): Maximum time
  • mask (Locator[]): Elements to mask
Returns: Promise<Buffer> - Screenshot buffer

​
pdf

Generates a PDF. 
pdf(options?: PDFOptions): Promise<Buffer>
​
options
PDFOptions
PDF options
  • path (string): File path to save to
  • format (string): Paper format (e.g., ‘A4’)
  • width (string | number): Paper width
  • height (string | number): Paper height
  • margin (object): Page margins
  • printBackground (boolean): Print background graphics
  • landscape (boolean): Landscape orientation
Returns: Promise<Buffer> - PDF buffer

​
close

Closes the page. 
close(options?: { runBeforeUnload?: boolean, reason?: string }): Promise<void>
​
options
object
  • runBeforeUnload (boolean): Run beforeunload handlers
  • reason (string): Close reason
Returns: Promise<void>

​
isClosed

Checks if page is closed. 
isClosed(): boolean
Returns: boolean - True if closed

​
context

Returns the browser context. 
context(): BrowserContext
Returns: BrowserContext - Parent context

​
opener

Returns the opener page. 
opener(): Promise<Page | null>
Returns: Promise<Page | null> - Opener page or null

​
bringToFront

Brings page to front. 
bringToFront(): Promise<void>
Returns: Promise<void>

​
setViewportSize

Sets viewport size. 
setViewportSize(viewportSize: { width: number, height: number }): Promise<void>
​
viewportSize
object
required
Viewport dimensions
  • width (number): Width in pixels
  • height (number): Height in pixels
Returns: Promise<void>

​
viewportSize

Returns viewport size. 
viewportSize(): { width: number, height: number } | null
Returns: object | null - Viewport size or null

​
setDefaultTimeout

Sets default timeout. 
setDefaultTimeout(timeout: number): void
​
timeout
number
required
Timeout in milliseconds

​
setDefaultNavigationTimeout

Sets default navigation timeout. 
setDefaultNavigationTimeout(timeout: number): void
​
timeout
number
required
Timeout in milliseconds

​
workers

Returns all workers. 
workers(): Worker[]
Returns: Worker[] - Array of workers

​
Usage Examples

​
Basic Page Automation

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();

await page.goto('https://example.com');
await page.click('button#submit');
await page.fill('input[name="email"]', '[email protected]');
await page.screenshot({ path: 'screenshot.png' });

await browser.close();

​
Using Locators

const page = await browser.newPage();
await page.goto('https://example.com');

const button = page.getByRole('button', { name: 'Submit' });
await button.click();

const input = page.getByPlaceholder('Enter your email');
await input.fill('[email protected]');

const heading = page.getByText('Welcome');
await expect(heading).toBeVisible();

​
Form Interactions

const page = await browser.newPage();
await page.goto('https://example.com/form');

await page.fill('#name', 'John Doe');
await page.fill('#email', '[email protected]');
await page.check('#terms');
await page.selectOption('#country', 'US');
await page.click('button[type="submit"]');

await page.waitForURL('**/success');

Build docs developers (and LLMs) love

Get started for freeTalk to us