Page - Playwright

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 input instance.

mouse

Mouse

Mouse input instance.

touchscreen

Touchscreen

Touchscreen input instance.

request

APIRequestContext

API request context.

clock

Clock

Clock instance for time control.

coverage

Coverage

Coverage instance (Chromium only).

goto

Navigates to a URL.

goto(url: string, options?: GotoOptions): Promise<Response | null>

string

required

URL to navigate to

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>

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>

NavigationOptions

Navigation options

Returns: Promise<Response | null> - Main resource response

goForward

Navigates to the next page in history.

goForward(options?: NavigationOptions): Promise<Response | null>

NavigationOptions

Navigation options

Returns: Promise<Response | null> - Main resource response

waitForNavigation

Waits for navigation to finish.

waitForNavigation(options?: WaitForNavigationOptions): Promise<Response | null>

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>

string

Load state to wait for (default: ‘load’)

TimeoutOptions

Timeout options

Returns: Promise<void>

waitForURL

Waits for page to navigate to matching URL.

waitForURL(url: string | RegExp, options?: WaitForURLOptions): Promise<void>

string | RegExp

required

URL pattern to wait for

WaitForURLOptions

Wait options

Returns: Promise<void>

Selector Methods

$

Finds an element matching the selector.

$(selector: string, options?: { strict?: boolean }): Promise<ElementHandle | null>

string

required

Selector to query

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[]>

string

required

Selector to query

Returns: Promise<ElementHandle[]> - Array of element handles

locator

Creates a locator.

locator(selector: string, options?: LocatorOptions): Locator

string

required

Selector to locate

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

string

required

ARIA role

ByRoleOptions

Role options

Returns: Locator - Locator instance

getByText

Creates a locator by text content.

getByText(text: string | RegExp, options?: { exact?: boolean }): Locator

string | RegExp

required

Text to match

object

exact (boolean): Exact match

Returns: Locator - Locator instance

getByLabel

Creates a locator by label text.

getByLabel(text: string | RegExp, options?: { exact?: boolean }): Locator

string | RegExp

required

Label text to match

object

exact (boolean): Exact match

Returns: Locator - Locator instance

getByPlaceholder

Creates a locator by placeholder text.

getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): Locator

string | RegExp

required

Placeholder text to match

object

exact (boolean): Exact match

Returns: Locator - Locator instance

getByAltText

Creates a locator by alt text.

getByAltText(text: string | RegExp, options?: { exact?: boolean }): Locator

string | RegExp

required

Alt text to match

object

exact (boolean): Exact match

Returns: Locator - Locator instance

getByTitle

Creates a locator by title attribute.

getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator

string | RegExp

required

Title to match

object

exact (boolean): Exact match

Returns: Locator - Locator instance

getByTestId

Creates a locator by test ID.

getByTestId(testId: string | RegExp): Locator

string | RegExp

required

Test ID to match

Returns: Locator - Locator instance

Action Methods

click

Clicks an element.

click(selector: string, options?: ClickOptions): Promise<void>

string

required

Selector to click

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>

string

required

Selector to fill

string

required

Value to fill

FillOptions

Fill options

Returns: Promise<void>

type

Types text into an element.

type(selector: string, text: string, options?: TypeOptions): Promise<void>

string

required

Selector to type into

string

required

Text to type

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>

string

required

Selector to focus

string

required

Key to press (e.g., ‘Enter’, ‘ArrowDown’)

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[]>

string

required

Selector to select from

string | string[] | SelectOption | SelectOption[]

required

Values to select

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>

string

required

Source element selector

string

required

Target element selector

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>

string

required

HTML content to set

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>

Function | string

required

Function to evaluate

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

string | object

required

Frame name or URL pattern

Returns: Frame | null - Matching frame or null

frameLocator

Creates a frame locator.

frameLocator(selector: string): FrameLocator

string

required

Frame selector

Returns: FrameLocator - Frame locator instance

Utility Methods

screenshot

Takes a screenshot.

screenshot(options?: ScreenshotOptions): Promise<Buffer>

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>

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>

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>

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

number

required

Timeout in milliseconds

setDefaultNavigationTimeout

Sets default navigation timeout.

setDefaultNavigationTimeout(timeout: number): void

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"]', 'test@example.com');
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('test@example.com');

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', 'john@example.com');
await page.check('#terms');
await page.selectOption('#country', 'US');
await page.click('button[type="submit"]');

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

BrowserContext - Parent context
Frame - Page frames
Locator - Element locators
ElementHandle - Element handles

​Inheritance

​Events

​Properties

​keyboard

​mouse

​touchscreen

​request

​clock

​coverage

​Navigation Methods

​goto

​reload

​goBack

​goForward

​waitForNavigation

​waitForLoadState

​waitForURL

​Selector Methods

​$

​$$

​locator

​getByRole

​getByText

​getByLabel

​getByPlaceholder

​getByAltText

​getByTitle

​getByTestId

​Action Methods

​click

​dblclick

​fill

​type

​press

​check

​uncheck

​selectOption

​hover

​tap

​dragAndDrop

​Content Methods

​content

​setContent

​title

​url

​textContent

​innerText

​innerHTML

​getAttribute

​State Methods

​isVisible

​isHidden

​isEnabled

​isDisabled

​isChecked

​isEditable

​Evaluation Methods

​evaluate

​evaluateHandle

​$eval

​$$eval

​Frame Methods

​mainFrame

​frames

​frame

​frameLocator

​Utility Methods

​screenshot

​pdf

​close

​isClosed

​context

​opener

​bringToFront

​setViewportSize

​viewportSize

​setDefaultTimeout

​setDefaultNavigationTimeout

​workers

​Usage Examples

Inheritance

Events

Properties

keyboard

mouse

touchscreen

request

clock

coverage

Navigation Methods

goto

reload

goBack

goForward

waitForNavigation

waitForLoadState

waitForURL

Selector Methods

$

$$

locator

getByRole

getByText

getByLabel

getByPlaceholder

getByAltText

getByTitle

getByTestId

Action Methods

click

dblclick

fill

type

press

check

uncheck

selectOption

hover

tap

dragAndDrop

Content Methods

content

setContent

title

url

textContent

innerText

innerHTML

getAttribute

State Methods

isVisible

isHidden

isEnabled

isDisabled

isChecked

isEditable

Evaluation Methods

evaluate

evaluateHandle

$eval

$$eval

Frame Methods

mainFrame

frames

frame

frameLocator

Utility Methods

screenshot

pdf

close

isClosed

context

opener

bringToFront

setViewportSize

viewportSize

setDefaultTimeout

setDefaultNavigationTimeout

workers

Usage Examples