Playwright · API reference · all subjects

frame

11 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Frame lifecycle and frame tree

Frame objects have a lifecycle controlled by three events dispatched on the page: frameAttached (fired when the frame gets attached to the page, only once), frameNavigated (fired when the frame commits navigation to a different URL), and frameDetached (fired when the frame gets detached from the page, only once). The page exposes its current frame tree via Page.mainFrame() and Frame.childFrames() methods.

Frame.childFrames() return type

Frame.childFrames() is a non-async method that returns Array<Frame>, containing all child frames of the current frame.

Frame.addScriptTag() method signature and return type

Frame.addScriptTag() is an async method that returns ElementHandle. It adds a <script> tag into the frame and returns the added tag when the script's onload fires or when the script content was injected into frame. Options: url (string, URL of a script to be added), path (path, path to the JavaScript file to be injected into frame, relative paths are resolved relative to current working directory), content (string, raw JavaScript content to be injected into frame), type (string, script type, use 'module' to load a JavaScript ES6 module).

Frame.addStyleTag() method signature and return type

Frame.addStyleTag() is an async method that returns ElementHandle. It returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame. It adds a <link rel="stylesheet"> tag with the desired url or a <style type="text/css"> tag with content. Options: url (string, URL of the <link> tag), path (path, path to the CSS file to be injected into frame, relative paths are resolved relative to current working directory), content (string, raw CSS content to be injected into frame).

Frame.frameElement() returns ElementHandle

Frame.frameElement() is an async method that returns ElementHandle. It returns the frame or iframe element handle corresponding to this frame. This is the inverse of ElementHandle.contentFrame(). Returned handle belongs to the parent frame. Throws error if frame has been detached before frameElement() returns.

Frame.frameLocator() method and usage

Frame.frameLocator() is a non-async method that returns FrameLocator. Parameters: selector (iframe selector). Used for working with iframes to locate elements within them without needing to locate each iframe first.

Frame.isDetached() method return type

Frame.isDetached() is a non-async method that returns boolean. Returns true if the frame has been detached, false otherwise.

Frame.name property returns string

Frame.name is a non-async, read-only property that returns string. Returns frame's name attribute as specified in the tag. If name is empty, returns the id attribute instead. Value is calculated once when frame is created and won't update if attribute changes later.

Frame.page property returns Page

Frame.page is a non-async, read-only property that returns Page. Returns the page containing this frame.

Frame.parentFrame property returns null or Frame

Frame.parentFrame is a non-async, read-only property that returns null or Frame. Returns parent frame if any. Detached frames and main frames return null.

Frame.pierceFrames() method and usage

Frame.pierceFrames() is a non-async method that returns FrameLocator. Used for searching elements across this frame and all iframes inside it without needing to locate each iframe first. Options: pierce (boolean, whether to pierce frames, default true, can pass false to opt out). Note: all matching elements must belong to a single frame, otherwise throws error.

Give your agent this brain