Page.url() returns current URL
The url() method returns the current URL of the page as a string.
Playwright · API reference · all subjects
core page methods - dom queries
70 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Page.content() returns page HTML content
The content() method is an async method that returns the full HTML content of the page.
Page.viewportSize() returns viewport dimensions
The viewportSize() method returns the viewport size as an object with width and height properties.
Page.frames() returns array of all frames
The frames() method returns an array of all Frame objects on the page. Each Frame has a url() method to get its URL.
Page.evaluate() executes JavaScript and returns result
The evaluate() method accepts a JavaScript function and executes it in the browser context. It returns the result of the function execution. Arguments can be passed as additional parameters after the function.
Page.context() to access browser context operations
The page object has a context() method that returns the browser context associated with the page, allowing access to context operations such as grantPermissions(), setGeolocation(), clearPermissions(), and storageState().
Page.title() returns page title
The title() method is an async method that returns the title of the current page.
Frame.querySelectorAll() method parameters and return type
Frame.querySelectorAll() is an async, discouraged method that returns Array<ElementHandle>. Parameters: selector. Finds all elements matching selector and returns ElementHandles pointing to them. Returns empty array if no elements match. Use Locator instead as ElementHandle is discouraged.
Frame.title() method return type
Frame.title() is an async method that returns string. Returns the page title.
Frame.setContent() method parameters and options
Frame.setContent() is an async method. Parameters: html (string HTML markup to assign). Options: timeout (float/number navigation timeout), signal (AbortSignal), waitUntil (string navigation wait condition). Internally calls document.write(), inheriting its characteristics.
Frame.waitForSelector returns ElementHandle or null when selector satisfies state option
Frame.waitForSelector is discouraged; web assertions that assert visibility or locator-based Locator.waitFor should be used instead. It returns an ElementHandle when the element specified by the selector satisfies the state option, or null if waiting for 'hidden' or 'detached'. Returns immediately if the selector already satisfies the condition. Throws if the selector doesn't satisfy the condition for the specified timeout in milliseconds.
Frame.waitForSelector parameters and options
Frame.waitForSelector accepts the following parameters and options: - selector (required): CSS selector, since v1.8 - state (optional): 'attached', 'detached', 'visible', or 'hidden', since v1.8 - strict (optional): requires selector to resolve to a single element, since v1.14 - timeout (optional): timeout in milliseconds, since v1.8 - signal (optional): AbortSignal to cancel waiting, since v1.8
Frame.content() returns HTML contents
Frame.content() is an async method that returns a string containing the full HTML contents of the frame, including the doctype.
Frame.evalOnSelectorAll() method signature and return type
Frame.evalOnSelectorAll() is an async, discouraged method that returns Serializable. It finds all elements matching selector and passes an array of matched elements as first argument to expression. Parameters: selector, expression (string or function), arg (optional EvaluationArgument). If expression returns a Promise, waits for resolution.
Frame.evaluate() method signature and return type
Frame.evaluate() is an async method that returns Serializable. It evaluates an expression in the frame context. Parameters: expression (string with JS code or JS function), arg (optional EvaluationArgument). Options: exposeFunctions (object to expose functions to JS context). If expression returns a Promise, waits for resolution. Returns undefined for non-serializable values except -0, NaN, Infinity, -Infinity which are supported.
Frame.evaluateHandle() method signature and return type
Frame.evaluateHandle() is an async method that returns JSHandle. It evaluates an expression and returns the result as a JSHandle. Parameters: expression (string or function), arg (optional EvaluationArgument). Options: exposeFunctions (object to expose functions). If expression returns a Promise, waits for resolution.
Screenshot option: maskColor
The maskColor option specifies the color of the overlay box for masked elements, in CSS color format. The default color is pink #FF00FF. Available since v1.35.
query-selector and find-selector parameters
query-selector: selector parameter type string, a selector to query for. find-selector: selector parameter type string, a selector to use when resolving DOM element.
screenshot-option-animations-default-disabled
The animations parameter is ScreenshotAnimations ('disabled', 'allow'). 'disabled' stops animations. 'allow' leaves untouched. Defaults 'disabled'.
screenshot-option-omit-background
The omitBackground parameter is type boolean. Hides default white background for transparent screenshots. Not for jpeg. Defaults false.
screenshot-option-quality
The quality parameter is type int (0-100). Not for png. jpeg default 80. webp 100 default (lossless), lower uses lossy.
Screenshot option: mask elements
The mask option specifies locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF (customized by maskColor) that completely covers its bounding box. The mask is also applied to invisible elements.
screenshot-option-mask
The mask parameter is Array<Locator>. Locators to mask in screenshot.
Screenshot option: fullPage
The fullPage option is a boolean that determines whether to take a screenshot of the full scrollable page instead of the currently visible viewport. Defaults to false.
Screenshot option: clip
The clip option is an object that specifies clipping of the resulting screenshot image. It contains: x (float) - x-coordinate of top-left corner of clip area, y (float) - y-coordinate of top-left corner of clip area, width (float) - width of clipping area, height (float) - height of clipping area.
Screenshot option: scale
The scale option accepts ScreenshotScale values 'css' or 'device'. When set to 'css', screenshot will have a single pixel per each css pixel on the page, keeping screenshots small on high-dpi devices. Using 'device' option will produce a single pixel per each device pixel, making screenshots of high-dpi devices twice as large or larger. Defaults to 'device' in most screenshot methods, and 'css' in some methods like screenshot-option-scale-default-css.
Screenshot option: caret
The caret option accepts ScreenshotCaret values 'hide' or 'initial'. When set to 'hide', screenshot will hide text caret. When set to 'initial', text caret behavior will not be changed. Defaults to 'hide'.
Screenshot option: style
The style option is a string containing text of a stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make elements invisible or change their properties to help create repeatable screenshots. This stylesheet pierces the Shadow DOM and applies to inner frames.
Screenshot option: stylePath
The stylePath option is a string or array of strings containing file names of stylesheets to apply while making the screenshot. This is where you can hide dynamic elements, make elements invisible or change their properties to help create repeatable screenshots. This stylesheet pierces the Shadow DOM and applies to inner frames.
screenshot-option-path
The path parameter is type path. File path to save image. Type inferred from extension. Relative resolved to current directory. No path means no save to disk.
screenshot-option-type
The type parameter is ScreenshotType ('png', 'jpeg', 'webp'). Screenshot type. Defaults png.
Page.querySelector - find element (discouraged)
Page.querySelector() is an async method (since v1.9, alias-python: query_selector, alias-js: $, discouraged in favor of Page.locator, returns null|ElementHandle) that finds an element matching a selector within the page. Returns null if no elements match. For waiting, use Locator.waitFor. Accepts: selector (CSS selector string). Options: strict (boolean, since v1.14).
Page.querySelectorAll - find all elements (discouraged)
Page.querySelectorAll() is an async method (since v1.9, alias-python: query_selector_all, alias-js: $$, discouraged in favor of Page.locator, returns Array<ElementHandle>) that finds all elements matching a selector within the page. Returns empty array if no elements match. Accepts: selector (CSS selector string).
Page.exposeFunction example - expose crypto function
Example of exposing a function to page: page.expose_function('sha256', sha256) exposes a sha256 function to window object. JavaScript can then call await window.sha256('PLAYWRIGHT') to execute the Python function from page context. This allows running Python code from browser JavaScript.
Page.ariaSnapshot method
Page.ariaSnapshot() (async, added in v1.59) captures the aria snapshot of the page as a string. Options: mode ('ai' or 'default', defaults to 'default'), timeout, signal, depth (limits snapshot depth), boxes (added v1.60, boolean, appends bounding box as [box=x,y,width,height], defaults to false).
Page.ariaSnapshotJSON method
Page.ariaSnapshotJSON() (async, added in v1.63, JavaScript only) captures the aria snapshot of the page as a free form JSON object. Returns the same tree as Page.ariaSnapshot, but serialized as JSON instead of YAML. Options: mode ('ai' or 'default', defaults to 'default'), timeout, signal, depth (limits snapshot depth), boxes (boolean, includes bounding box as box property with x, y, width, height, defaults to false).
Page.textContent method
Page.textContent() (async, added in v1.8, discouraged in favor of Locator.textContent) returns element.textContent as null or string. Options: strict, timeout, signal.
Page.title method
Page.title() (added in v1.8) returns the page's title as a string.
Page.waitForSelector method
Page.waitForSelector() (async, added in v1.8, discouraged in favor of web assertions or Locator.waitFor) returns when element specified by selector satisfies state option. Returns null|ElementHandle. Returns null if waiting for 'hidden' or 'detached'. If selector already satisfies condition, returns immediately. Throws if doesn't satisfy condition within timeout. Options: state ('attached', 'detached', 'visible', 'hidden'), strict, timeout, signal.
Page.waitForSelector example
```js const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch(); const page = await browser.newPage(); for (const currentURL of ['https://google.com', 'https://bbc.com']) { await page.goto(currentURL); const element = await page.waitForSelector('img'); console.log('Loaded image: ' + await element.getAttribute('src')); } await browser.close(); })(); ``` This example demonstrates waiting for elements across multiple page navigations.
Page.cancelPickLocator cancels pick locator mode
The async method Page.cancelPickLocator (since v1.59) cancels an ongoing Page.pickLocator call by deactivating pick locator mode. If no pick locator mode is active, this method is a no-op.
Page.content returns full HTML contents
The async method Page.content (since v1.8) returns the full HTML contents of the page including the doctype. Return type: string.
Page.coverage property for Chromium
The property Page.coverage (since v1.8, JS only) provides browser-specific Coverage implementation. Only available for Chromium. Type: Coverage.
Page.emulateMedia changes CSS media type and color scheme
The async method Page.emulateMedia (since v1.8) changes the CSS media type and/or prefers-colors-scheme media feature. Returns undefined. Options: media (null, 'screen', or 'print'), colorScheme (null, 'light', 'dark', or 'no-preference' deprecated), reducedMotion (null, 'reduce', or 'no-preference' since v1.12), forcedColors (null, 'active', or 'none' since v1.15), contrast (null, 'no-preference', or 'more' since v1.51).
Page.evalOnSelectorAll evaluates expression on all matching elements
The async method Page.evalOnSelectorAll (since v1.9, discouraged - use Locator.evaluateAll instead) finds all elements matching the selector and passes an array of matched elements as the first argument to the expression. Returns the result of the expression invocation (Serializable). If the expression returns a Promise, waits for it to resolve. Alias: $$eval in JS, eval_on_selector_all in Python. Parameters: selector, expression, optional arg.
Page.evaluate evaluates JavaScript expression or function
The async method Page.evaluate (since v1.8) returns the value of the expression invocation (Serializable). If the function passed to Page.evaluate returns a Promise, waits for the promise to resolve and returns its value. If the function returns a non-Serializable value, resolves to undefined. Supports transferring additional values not serializable by JSON: -0, NaN, Infinity, -Infinity. Can pass a function or string expression. Parameters: expression, optional arg. Options: exposeFunctions (since v1.62).
Page.evaluateHandle evaluates expression and returns JSHandle
The async method Page.evaluateHandle (since v1.8) returns the value of the expression invocation as a JSHandle. The only difference between Page.evaluate and Page.evaluateHandle is that Page.evaluateHandle returns JSHandle. If the function returns a Promise, waits for the promise to resolve and returns its value. Can pass a function or string expression. Parameters: expression, optional arg. Options: exposeFunctions (since v1.62).
Page.exposeBinding exposes function on window object
The async method Page.exposeBinding (since v1.8) adds a function called name on the window object of every frame in the page. When called, the function executes the callback and returns a Promise which resolves to the return value of the callback. If the callback returns a Promise, it is awaited. The first argument of the callback contains information: { browserContext, page, frame }. Functions installed via Page.exposeBinding survive navigations. Returns a Disposable. Parameters: name (string), callback (function).
Page.exposeFunction exposes JavaScript function on window
The async method Page.exposeFunction (since v1.8) adds a function called name on the window object of every frame in the page. When called, the function executes the callback and returns a Promise which resolves to the return value of the callback. If the callback returns a Promise, it is awaited. Functions installed via Page.exposeFunction survive navigations. Returns a Disposable. Parameters: name (string), callback (function).
Page.emulateMedia example changes media type and color scheme
Example showing Page.emulateMedia usage. Code demonstrates: await page.emulateMedia({ media: 'print' }); to change media type, and await page.emulateMedia({ colorScheme: 'dark' }); to change color scheme. Shows how matchMedia results change after emulation.
Page.evalOnSelector example gets element values
Example showing Page.evalOnSelector usage. Code: const searchValue = await page.$eval('#search', el => el.value); Gets the value of a search input. Also shows: const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); with an additional argument.
Page.evalOnSelectorAll example counts elements
Example showing Page.evalOnSelectorAll usage. Code: const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); Gets all divs and checks if count is >= min.
Page.evaluate example passes arguments and returns values
Example showing Page.evaluate usage. Code: const result = await page.evaluate(([x, y]) => Promise.resolve(x * y), [7, 8]); passes [7, 8] as an argument and returns 56. Also shows passing a string expression: await page.evaluate('1 + 2'); returns 3.
Page.evaluate example with ElementHandle argument
Example showing Page.evaluate with ElementHandle. Code: const bodyHandle = await page.evaluateHandle('document.body'); const html = await page.evaluate(([body, suffix]) => body.innerHTML + suffix, [bodyHandle, 'hello']); Gets body's innerHTML and appends 'hello'.
Page.evaluateHandle example returns JSHandle to window
Example showing Page.evaluateHandle usage. Code: const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window)); Returns a handle to the window object. Also shows: const aHandle = await page.evaluateHandle('document'); gets a handle to document.
Page.evaluateHandle example passes JSHandle and operates on it
Example showing Page.evaluateHandle with JSHandle argument. Code: const aHandle = await page.evaluateHandle(() => document.body); const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle); passes body handle and gets its innerHTML.
Page.exposeBinding example exposes page URL to page
Example showing Page.exposeBinding usage. Code: await page.exposeBinding('pageURL', ({ page }) => page.url()); adds a pageURL function to window that returns the page's URL. The binding callback receives an object with page, browserContext, and frame properties.
Page.exposeFunction example exposes sha256 function
Example showing Page.exposeFunction usage for crypto. Code defines a sha256 function in Node, then calls: await page.exposeFunction('sha256', sha256); to expose it to the page's window object. JavaScript on the page can then call window.sha256('text') and get back the hash.
Page.exposeFunction - expose function to window
Page.exposeFunction() is an async method that exposes a function to the page's window object. It takes two parameters: name (string) - the name of the function on the window object, and callback (function) - the callback function which will be called in Playwright's context. Since v1.8.
Page.frame - get frame by name or url
Page.frame() is a synchronous method (since v1.8, returns null|Frame) that returns a frame matching specified criteria. Either name or url must be specified. In JavaScript, accepts frameSelector which can be a string or object with optional name and url properties. In Python, accepts optional name and url parameters. In Java and C#, frameByUrl() method is used for URL-based lookup.