***

title: Puppeteer Frame
description: Complete Frame method reference for the Puppeteer driver.
----------------------------------------------------------------------

All `Frame` methods available when using the **Puppeteer** driver.

Access via `frame` after launching a Puppeteer runtime.

<Accordion title="How these methods work over HTTP">
  Every method below is a remote call. The SDK translates it into a structured step sent to a single endpoint:

  ```
  POST /v1/workspaces/{workspaceId}/execute
  ```

  ```json
  {
    "runtime": "my-browser",
    "steps": [
      {
        "call": "frame.goto",
        "args": ["https://example.com"]
      }
    ]
  }
  ```

  The `call` field maps directly to the method name. `args` is a JSON array of the method's arguments. You can batch multiple steps in one request.
</Accordion>

## Navigation

### goto(url, options?)

Navigate the frame to a URL.

```ts
await frame.goto('...');
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `url`     | `string`               | Yes      | —           |
| `options` | `PuppeteerGotoOptions` | No       | —           |

**Returns** `PuppeteerHTTPResponse \| null`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.goto)

***

### waitForNavigation(options?)

Wait for navigation to complete.

```ts
await frame.waitForNavigation();
```

| Parameter | Type                                | Required | Description |
| --------- | ----------------------------------- | -------- | ----------- |
| `options` | `PuppeteerWaitForNavigationOptions` | No       | —           |

**Returns** `PuppeteerHTTPResponse \| null`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.waitfornavigation)

***

## Page Info

### url()

The frame's URL.

```ts
await frame.url();
```

**Returns** `string`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.url)

***

### title()

The frame's title.

```ts
await frame.title();
```

**Returns** `string`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.title)

***

### content()

The full HTML contents of the frame.

```ts
await frame.content();
```

**Returns** `string`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.content)

***

### setContent(html, options?)

Set the content of the frame.

```ts
await frame.setContent('...');
```

| Parameter | Type                                       | Required | Description |
| --------- | ------------------------------------------ | -------- | ----------- |
| `html`    | `string`                                   | Yes      | —           |
| `options` | `{ timeout?: number; waitUntil?: string }` | No       | —           |

[Upstream docs](https://pptr.dev/api/puppeteer.frame.setcontent)

***

## Actions

### click(selector, options?)

Click on an element.

```ts
await frame.click('...');
```

| Parameter  | Type                    | Required | Description |
| ---------- | ----------------------- | -------- | ----------- |
| `selector` | `string`                | Yes      | —           |
| `options`  | `PuppeteerClickOptions` | No       | —           |

[Upstream docs](https://pptr.dev/api/puppeteer.frame.click)

***

### type(selector, text, options?)

Type text into an element.

```ts
await frame.type('...', '...');
```

| Parameter  | Type                           | Required | Description |
| ---------- | ------------------------------ | -------- | ----------- |
| `selector` | `string`                       | Yes      | —           |
| `text`     | `string`                       | Yes      | —           |
| `options`  | `PuppeteerKeyboardTypeOptions` | No       | —           |

[Upstream docs](https://pptr.dev/api/puppeteer.frame.type)

***

### focus(selector)

Focus on an element.

```ts
await frame.focus('...');
```

| Parameter  | Type     | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `selector` | `string` | Yes      | —           |

[Upstream docs](https://pptr.dev/api/puppeteer.frame.focus)

***

### hover(selector)

Hover over an element.

```ts
await frame.hover('...');
```

| Parameter  | Type     | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `selector` | `string` | Yes      | —           |

[Upstream docs](https://pptr.dev/api/puppeteer.frame.hover)

***

### select(selector, ...values)

Select options in a \<select> element.

```ts
await frame.select('...', /* string[] */);
```

| Parameter  | Type       | Required | Description |
| ---------- | ---------- | -------- | ----------- |
| `selector` | `string`   | Yes      | —           |
| `values`   | `string[]` | Yes      | —           |

**Returns** `string[]`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.select)

***

### tap(selector)

Tap on an element.

```ts
await frame.tap('...');
```

| Parameter  | Type     | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `selector` | `string` | Yes      | —           |

[Upstream docs](https://pptr.dev/api/puppeteer.frame.tap)

***

## Queries

### page()

The page associated with this frame.

<Note>
  Returns the cached page reference passed at construction time.
</Note>

```ts
frame.page();
```

**Returns** `RemotePuppeteerPage \| null`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.page)

***

### locator(selector)

Creates a Locator for the given selector.

<Note>
  Locators are used for performing actions on elements with built-in waiting.
</Note>

```ts
frame.locator('...');
```

| Parameter  | Type     | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `selector` | `string` | Yes      | —           |

**Returns** `RemotePuppeteerLocator`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.locator)

***

### \$(selector)

Query for a single element.

```ts
await frame.$('...');
```

| Parameter  | Type     | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `selector` | `string` | Yes      | —           |

**Returns** `RemotePuppeteerElementHandle \| null`

[Upstream docs](https://pptr.dev/api/puppeteer.frame._)

***

### \$\$(selector)

Query for all matching elements.

```ts
await frame.$$('...');
```

| Parameter  | Type     | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `selector` | `string` | Yes      | —           |

**Returns** `RemotePuppeteerElementHandle[]`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.__)

***

### \$x(expression)

Evaluate XPath expression. (Uses \$\$() with xpath prefix internally)

```ts
await frame.$x('...');
```

| Parameter    | Type     | Required | Description |
| ------------ | -------- | -------- | ----------- |
| `expression` | `string` | Yes      | —           |

**Returns** `RemotePuppeteerElementHandle[]`

[Upstream docs](https://pptr.dev/api/puppeteer.frame._x)

***

## State Checks

### isDetached()

Whether this frame is detached.

<Note>
  @deprecated Use the `detached` getter.
</Note>

```ts
frame.isDetached();
```

**Returns** `boolean`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.isdetached)

***

### isMainFrame()

Is this the main frame?

```ts
await frame.isMainFrame();
```

**Returns** `boolean`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.ismainframe)

***

### isOOPFrame()

Is this an out-of-process frame? (Deprecated - always returns false)

```ts
await frame.isOOPFrame();
```

**Returns** `boolean`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.isoopframe)

***

## Waiting

### waitForSelector(selector, options?)

Wait for a selector to appear.

```ts
await frame.waitForSelector('...');
```

| Parameter  | Type                              | Required | Description |
| ---------- | --------------------------------- | -------- | ----------- |
| `selector` | `string`                          | Yes      | —           |
| `options`  | `PuppeteerWaitForSelectorOptions` | No       | —           |

**Returns** `RemotePuppeteerElementHandle \| null`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.waitforselector)

***

### waitForFunction(pageFunction, options?, ...args)

Wait for a function to return a truthy value.

```ts
await frame.waitForFunction('...');
```

| Parameter      | Type                                                            | Required | Description |
| -------------- | --------------------------------------------------------------- | -------- | ----------- |
| `pageFunction` | `Func \| string`                                                | Yes      | —           |
| `options`      | `{ timeout?: number; polling?: number \| 'raf' \| 'mutation' }` | No       | —           |
| `args`         | `Params`                                                        | No       | —           |

**Returns** `RemotePuppeteerJSHandle&lt;Awaited&lt;ReturnType&lt;Func&gt;&gt;&gt;`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.waitforfunction)

***

## Evaluation

### evaluate(pageFunction, ...args)

Evaluate JavaScript in the frame context.

```ts
await frame.evaluate('...');
```

| Parameter      | Type                                                           | Required | Description |
| -------------- | -------------------------------------------------------------- | -------- | ----------- |
| `pageFunction` | `string \| ((...args: unknown[]) =&gt; T \| Promise&lt;T&gt;)` | Yes      | —           |
| `args`         | `unknown[]`                                                    | No       | —           |

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.evaluate)

***

### \$eval(selector, pageFunction, ...args)

Evaluate JavaScript on a selected element.

```ts
await frame.$eval('...', '...');
```

| Parameter      | Type                                                                        | Required | Description |
| -------------- | --------------------------------------------------------------------------- | -------- | ----------- |
| `selector`     | `string`                                                                    | Yes      | —           |
| `pageFunction` | `string \| ((el: Element, ...args: unknown[]) =&gt; T \| Promise&lt;T&gt;)` | Yes      | —           |
| `args`         | `unknown[]`                                                                 | No       | —           |

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.frame._eval)

***

### \$\$eval(selector, pageFunction, ...args)

Evaluate JavaScript on all matching elements.

```ts
await frame.$$eval('...', '...');
```

| Parameter      | Type                                                                           | Required | Description |
| -------------- | ------------------------------------------------------------------------------ | -------- | ----------- |
| `selector`     | `string`                                                                       | Yes      | —           |
| `pageFunction` | `string \| ((els: Element[], ...args: unknown[]) =&gt; T \| Promise&lt;T&gt;)` | Yes      | —           |
| `args`         | `unknown[]`                                                                    | No       | —           |

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.__eval)

***

### evaluateHandle(pageFunction, ...args)

Evaluates a function in the frame's context and returns a handle to the result.

```ts
await frame.evaluateHandle('...');
```

| Parameter      | Type             | Required | Description |
| -------------- | ---------------- | -------- | ----------- |
| `pageFunction` | `Func \| string` | Yes      | —           |
| `args`         | `Params`         | No       | —           |

**Returns** `RemotePuppeteerJSHandle&lt;Awaited&lt;ReturnType&lt;Func&gt;&gt;&gt;`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.evaluatehandle)

***

## Other

### detached()

Is `true` if the frame has been detached. Otherwise, `false`.

```ts
frame.detached();
```

**Returns** `boolean`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.detached)

***

### frameElement()

The frame element associated with this frame, if any.

<Note>
  Returns the ElementHandle for the \<iframe> or \<frame> tag for this frame. Returns null for the main frame.
</Note>

```ts
await frame.frameElement();
```

**Returns** `RemotePuppeteerElementHandle \| null`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.frameelement)

***

### name()

The frame's name attribute as specified in the tag.

```ts
await frame.name();
```

**Returns** `string`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.name)

***

### parentFrame()

The parent frame, if any.

<Note>
  Returns null for the main frame.
</Note>

```ts
await frame.parentFrame();
```

**Returns** `RemotePuppeteerFrame \| null`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.parentframe)

***

### childFrames()

Child frames of this frame.

```ts
await frame.childFrames();
```

**Returns** `RemotePuppeteerFrame[]`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.childframes)

***

### addScriptTag(options)

Add a script tag to the frame.

```ts
await frame.addScriptTag(/* PuppeteerFrameAddScriptTagOptions */);
```

| Parameter | Type                                | Required | Description |
| --------- | ----------------------------------- | -------- | ----------- |
| `options` | `PuppeteerFrameAddScriptTagOptions` | Yes      | —           |

**Returns** `RemotePuppeteerElementHandle`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.addscripttag)

***

### addStyleTag(options)

Add a style tag to the frame.

```ts
await frame.addStyleTag(/* PuppeteerFrameAddStyleTagOptions */);
```

| Parameter | Type                               | Required | Description |
| --------- | ---------------------------------- | -------- | ----------- |
| `options` | `PuppeteerFrameAddStyleTagOptions` | Yes      | —           |

**Returns** `RemotePuppeteerElementHandle`

[Upstream docs](https://pptr.dev/api/puppeteer.frame.addstyletag)

***