# Browser Actions

Source: https://docs.scrappey.com/docs/guides/browser-actions

> Automate interactions with web pages by specifying a sequence of typed actions in the `browserActions` array of your request payload.

## Command

Browser actions are passed as the `browserActions` array on any `request.get` or `request.post` call.

## Parameters

All actions share a common set of top-level properties.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `type` | string | Yes | The action type (see Action Types below). |
| `when` | string | No | Lifecycle phase to run this action. Defaults to `"afterload"`. |
| `ignoreErrors` | boolean | No | If `true`, errors in this action will not stop execution. |
| `timeout` | number | No | Timeout in milliseconds. Default `60000`. |

## Execution Lifecycle

Browser actions run at specific points during the request lifecycle. Use the `when` property to control when each action executes. If `when` is omitted it defaults to `"afterload"`.

### Lifecycle Phases (in order)

```
1. beforelaunch    — Before browser navigates to the URL
2. beforeload      — After browser is ready, before the page loads
3. afterload       — After the page has loaded (default)
```

### Phase Details

| Phase | When it runs | Use case |
| -------------- | ------------ | -------- |
| `beforelaunch` | Before any navigation. No page context yet. | Setting up browser state, pre-flight actions |
| `beforeload` | After cookies are added, before GET/POST navigation | Pre-navigation setup, adding localStorage |
| `afterload` | After page navigation completes | Main page interactions — filling forms, clicking buttons, extracting data |

Additional lifecycle phases used by authorized verification workflows are documented on the login-gated [Verification Flow Handling](/docs/solve-captcha) guide — sign in with your Scrappey account to view them.

Each action in the `browserActions` array is tagged with a `when` phase. The engine loops through the array multiple times — once per phase — and only runs actions whose `when` matches the current phase. Actions within the same phase execute in order.

When actions are nested inside `if.then`, `if.or`, or `while.then`, the `when` property of nested actions is ignored — they run immediately when the parent action executes. Only top-level actions in the `browserActions` array are filtered by `when`.

## Action Types

### `click` - Click an Element

Clicks on an element using CSS selector. See the dedicated [Click Action](/docs/click-action) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `cssSelector` | string | Yes | CSS selector of element to click. |
| `wait` | number | No | Wait time in seconds after clicking. |
| `waitForSelector` | string | No | Wait for this selector to appear after click. |
| `direct` | boolean | No | Use direct click instead of cursor simulation. |

**Example:**
```json
{
  "type": "click",
  "cssSelector": "#submit-button",
  "wait": 1,
  "waitForSelector": ".success-message"
}
```

### `type` - Type Text into Input

Types text into an input field with configurable delays between keystrokes. See the dedicated [Type Action](/docs/type-action) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `cssSelector` | string | Yes | CSS selector of input element. |
| `text` | string | Yes | Text to type. |
| `wait` | number | No | Wait time in seconds after typing. |
| `direct` | boolean | No | Use direct typing instead of cursor simulation. |

**Example:**
```json
{
  "type": "type",
  "cssSelector": "#username",
  "text": "myusername"
}
```

### `goto` - Navigate to URL

Navigates the browser to a new URL. See the dedicated [Go To](/docs/go-to) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `url` | string | Yes | URL to navigate to. |
| `wait` | number | No | Wait time in seconds after navigation. |

**Example:**
```json
{
  "type": "goto",
  "url": "https://example.com/page2"
}
```

### `wait` - Wait for Duration

Pauses execution for a specified time. See the dedicated [Wait](/docs/wait) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `wait` | number | Yes | Wait time in seconds. |

**Example:**
```json
{
  "type": "wait",
  "wait": 2
}
```

### `wait_for_selector` - Wait for Element

Waits for an element to appear in the DOM. See the dedicated [Wait For Selector](/docs/wait-for-selector) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `cssSelector` | string | Yes | CSS selector to wait for. |
| `timeout` | number | No | Timeout in ms. Default `60000`. |

**Example:**
```json
{
  "type": "wait_for_selector",
  "cssSelector": ".loaded-content",
  "timeout": 30000
}
```

### `wait_for_function` - Wait for JavaScript Condition

Waits until a JavaScript expression returns truthy. See the dedicated [Wait For Function](/docs/wait-for-function) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `code` | string | Yes | JavaScript code that returns truthy when done. |
| `timeout` | number | No | Timeout in ms. Default `60000`. |

**Example:**
```json
{
  "type": "wait_for_function",
  "code": "window.dataLoaded === true",
  "timeout": 30000
}
```

### `wait_for_load_state` - Wait for Page State

Waits for a specific page load state. See the dedicated [Wait For Load State](/docs/wait-for-load-state) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `waitForLoadState` | string | Yes | `"domcontentloaded"`, `"networkidle"`, or `"load"`. |

**Example:**
```json
{
  "type": "wait_for_load_state",
  "waitForLoadState": "networkidle"
}
```

### `wait_for_cookie` - Wait for Cookie

Waits for a specific cookie to be set.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `cookieName` | string | Yes | Name of the cookie to wait for. |
| `cookieValue` | string | No | Expected value of the cookie. |
| `cookieDomain` | string | No | Domain the cookie should be set on. |
| `pollIntervalMs` | number | No | Poll interval. Default `200` ms. |
| `timeout` | number | No | Timeout in ms. Default `60000`. |

**Example:**
```json
{
  "type": "wait_for_cookie",
  "cookieName": "session_id",
  "timeout": 30000
}
```

### `execute_js` - Execute JavaScript

Executes JavaScript code on the page. Results are stored in the `javascriptReturn` array. See the dedicated [Execute Javascript](/docs/execute-javascript) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `code` | string | Yes | JavaScript code to execute. |
| `dontReturnValue` | boolean | No | If `true`, the return value is not captured. |

**Example:**
```json
{
  "type": "execute_js",
  "code": "document.querySelector('.price').innerText"
}
```

Access results in subsequent actions via `{javascriptReturn[0]}`.

### `scroll` - Scroll Page/Element

Scrolls to an element or the bottom of the page. See the dedicated [Scroll](/docs/scroll) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `cssSelector` | string | No | Element to scroll to. If omitted, scrolls to bottom. |
| `repeat` | number | No | Number of times to repeat the scroll. |
| `delayMs` | number | No | Delay between scrolls. Default `100` ms. |

**Example:**
```json
{
  "type": "scroll",
  "cssSelector": "#footer",
  "repeat": 3,
  "delayMs": 500
}
```

### `hover` - Hover Over Element

Hovers the mouse over an element.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `cssSelector` | string | Yes | CSS selector of element to hover. |
| `timeout` | number | No | Timeout in ms. |

**Example:**
```json
{
  "type": "hover",
  "cssSelector": ".dropdown-trigger"
}
```

### `keyboard` - Press Keyboard Key

Simulates keyboard key presses. See the dedicated [Keyboard](/docs/keyboard) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `value` | string | Yes | Key to press (see supported values below). |
| `cssSelector` | string | No | Element to focus first (required for `clear`). |
| `wait` | number | No | Wait time in seconds after pressing. |
| `waitForSelector` | string | No | Wait for selector after pressing. |

**Supported values:** `tab`, `enter`, `space`, `arrowdown`, `arrowup`, `arrowleft`, `arrowright`, `backspace`, `clear`

**Example:**
```json
{
  "type": "keyboard",
  "value": "enter"
}
```

### `dropdown` - Select Dropdown Option

Selects an option from a dropdown/select element. See the dedicated [Dropdown Action](/docs/dropdown-action) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `cssSelector` | string | Yes | CSS selector of select element. |
| `index` | number | No | Option index to select. |
| `value` | string | No | Option value to select. |
| `wait` | number | No | Wait time in seconds after selection. |
| `waitForSelector` | string | No | Wait for selector after selection. |

Either `index` or `value` is required.

**Example:**
```json
{
  "type": "dropdown",
  "cssSelector": "#country-select",
  "value": "US"
}
```

### `switch_iframe` - Switch to iFrame

Switches context to an iframe for subsequent actions.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `cssSelector` | string | Yes | CSS selector of the iframe. |

**Example:**
```json
{
  "type": "switch_iframe",
  "cssSelector": "#payment-iframe"
}
```

### `set_viewport` - Set Browser Viewport

Changes the browser viewport size.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `width` | number | No | Viewport width. Default `1280`. |
| `height` | number | No | Viewport height. Default `1024`. |
| `wait` | number | No | Wait time in seconds after setting. |

**Example:**
```json
{
  "type": "set_viewport",
  "width": 1920,
  "height": 1080
}
```

### `if` - Conditional Execution

Executes actions conditionally based on a JavaScript condition. See the dedicated [Conditional](/docs/conditional) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `condition` | string | Yes | JavaScript condition to evaluate. |
| `then` | array | No | Actions to run if condition is true. |
| `or` | array | No | Actions to run if condition is false. |

**Example:**
```json
{
  "type": "if",
  "condition": "document.querySelector('.captcha') !== null",
  "then": [
    { "type": "solve_captcha", "captcha": "custom" }
  ],
  "or": [
    { "type": "click", "cssSelector": "#continue" }
  ]
}
```

### `while` - Loop Execution

Loops actions while a condition is true. See the dedicated [While Loop](/docs/while-loop) guide.

| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `condition` | string | Yes | JavaScript condition to evaluate. |
| `then` | array | Yes | Actions to run each iteration. |
| `maxAttempts` | number | No | Maximum iterations (prevents infinite loops). |

**Example:**
```json
{
  "type": "while",
  "condition": "document.querySelector('.load-more') !== null",
  "then": [
    { "type": "click", "cssSelector": ".load-more" },
    { "type": "wait", "wait": 1 }
  ],
  "maxAttempts": 10
}
```

### `solve_captcha` - Verification Flow Handling

Handles interactive verification steps that can appear during an authorized browser workflow, so a permitted session can continue. The action takes a `captcha` type and an optional `captchaData` configuration object.

The supported verification types and the full `captchaData` parameter reference are documented on the login-gated [Verification Flow Handling](/docs/solve-captcha) guide — sign in with your Scrappey account to view them. Only use verification handling within authorized workflows where you have a lawful basis to proceed.

**Example:**
```json
{
  "type": "solve_captcha",
  "captcha": "custom"
}
```

### Authenticated login

Some workflows need to start from an already-authenticated session. Token-based login actions are documented on the login-gated [Authenticated Login Flow](/docs/authenticated-login-flow) guide; sign in with your Scrappey account to view the parameters and example. Only use them to automate accounts you own or are authorized to access.

### `remove_iframes` - Remove All iFrames

Removes all iframes from the page (experimental). No additional properties required.

**Example:**
```json
{
  "type": "remove_iframes"
}
```

### `click_and_hold` - Click and Hold

*Note: This action is not yet implemented.*

## Example

### Using JavaScript Return Values

Results from `execute_js` are stored in the `javascriptReturn` array and can be referenced in subsequent actions:

```json
{
  "browserActions": [
    {
      "type": "execute_js",
      "code": "document.querySelector('.token').dataset.value"
    },
    {
      "type": "type",
      "cssSelector": "#input",
      "text": "{javascriptReturn[0]}"
    }
  ]
}
```

### Full Login Flow

```json
{
  "cmd": "request.get",
  "url": "https://example.com",
  "browserActions": [
    {
      "type": "wait_for_selector",
      "cssSelector": "#login-form",
      "when": "afterload"
    },
    {
      "type": "type",
      "cssSelector": "#username",
      "text": "myuser"
    },
    {
      "type": "type",
      "cssSelector": "#password",
      "text": "mypassword"
    },
    {
      "type": "solve_captcha",
      "captcha": "custom"
    },
    {
      "type": "click",
      "cssSelector": "#submit",
      "waitForSelector": ".dashboard"
    },
    {
      "type": "execute_js",
      "code": "document.querySelector('.user-data').innerText"
    }
  ]
}
```

## Notes

### Sequencing actions after a verification step

Actions that must run only after an authorized verification step completes use a dedicated lifecycle phase. That phase, and a worked example of submitting a form once a verification token is ready, are documented on the login-gated [Verification Flow Handling](/docs/solve-captcha) guide — sign in with your Scrappey account to view them.

[All the browser actions](https://www.scrappey.com/scrapers/BrowserActions)