> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Recording

> Browser action recording, editing, parameterization and replay

Zeus Desktop provides comprehensive browser action recording, automatically capturing user operations in the browser as editable, replayable workflows.

## Overview

Workflow recording is built on the **Chrome DevTools Protocol (CDP)**, capturing DOM-level browser events with higher accuracy and stability compared to traditional coordinate-based recording approaches.

### Core Capabilities

| Capability               | Description                                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| **Precise Recording**    | CDP-based DOM event capture with dual locator strategy: CSS selectors + semantic features       |
| **Visual Editing**       | Drag-and-drop reordering, step-by-step editing, insert/delete action steps                      |
| **Parameterization**     | Mark fixed values as variables for dynamic injection                                            |
| **Parameterized Replay** | Enter parameter values during test replay to verify workflow correctness                        |
| **Video Sync**           | Action events are time-aligned with recorded video; click a step to jump to the video timestamp |

## Quick Start

### 1. Select a Browser Profile

Before recording, select a browser profile. Each profile has its own independent cookies, cache, and login state.

### 2. Start Recording

1. Click the **Start Recording** button on the recording page
2. Select a browser profile
3. Optionally enable video recording (captures screen visuals simultaneously)
4. The browser launches automatically and enters recording mode

### 3. Perform Actions

Operate the browser normally. The system automatically captures the following events:

* Page navigation (URL changes)
* Mouse clicks
* Text input and modification
* Keyboard keystrokes
* Page scrolling
* Form submission
* Drag and drop

### 4. Stop Recording

Click the **Stop Recording** button. The recorded action sequence is displayed in the editor for further editing and saving.

## Supported Action Types

### Browser Events

| Type       | Description                                   | Parameterizable                    |
| ---------- | --------------------------------------------- | ---------------------------------- |
| `navigate` | Navigate to a specified URL                   | ✅ URL can be parameterized         |
| `click`    | Click a page element                          | ❌                                  |
| `input`    | Type text into an input field                 | ✅ Input value can be parameterized |
| `change`   | Change a form control value (dropdowns, etc.) | ✅ Value can be parameterized       |
| `scroll`   | Scroll the page or an element                 | ❌                                  |
| `keypress` | Press a keyboard key (Enter, Tab, etc.)       | ❌                                  |
| `wait`     | Wait for a specified duration                 | ❌                                  |
| `submit`   | Submit a form                                 | ❌                                  |
| `drag`     | Drag an element to a target position          | ❌                                  |

### System-level Events (Extensions)

| Type              | Description                 |
| ----------------- | --------------------------- |
| `system_click`    | System-level mouse click    |
| `system_keypress` | System-level keyboard input |
| `app_switch`      | Application switch          |
| `applescript`     | AppleScript execution       |
| `shell_command`   | Shell command execution     |

## Element Locator Strategy

During recording, each action's target element uses a multi-strategy locator approach to ensure high accuracy during replay:

### Locator Priority

| Priority | Method     | Confidence | Description                                 |
| -------- | ---------- | ---------- | ------------------------------------------- |
| 1        | `testId`   | 1.00       | Exact match on `data-testid` attribute      |
| 2        | `exact`    | 0.95       | Full semantic match (role + name)           |
| 3        | `selector` | 0.85       | CSS selector match                          |
| 4        | `fuzzy`    | 0.70       | Fuzzy match (text content, ARIA attributes) |
| 5        | `position` | 0.60       | Visual position match                       |
| 6        | `nth`      | 0.50       | Index-based fallback                        |

### Semantic Features (ElementFeatures)

Rich semantic features are recorded for each action's target element:

```typescript theme={null}
interface ElementFeatures {
  role?: string          // ARIA role
  name?: string          // Accessible name
  testId?: string        // data-testid
  ariaLabel?: string     // aria-label
  text?: string          // Text content
  placeholder?: string   // placeholder attribute
  tagName?: string       // HTML tag name
  type?: string          // input type
}
```

These features enable the replay engine to locate the correct target element through semantic information even when the page DOM structure has changed.

## Editing Workflows

### Workflow Editor

After saving a recording, you can modify the action sequence in the workflow editor:

* **Drag-and-drop reordering**: Adjust the execution order of action steps
* **Edit actions**: Modify selectors, values, URLs, and other properties
* **Insert steps**: Add new action steps at any position
* **Delete steps**: Remove unnecessary actions
* **Video sync**: Click a step to automatically jump to the corresponding timestamp in the recorded video

### Editing Action Details

Click any action step to open the editing dialog:

* **Basic info**: Action type, description
* **Selectors**: CSS selector, XPath, element features
* **Value**: Input value, navigation URL
* **Parameterization settings**: Mark as variable, set variable name and default value

## Parameterization

Parameterization converts fixed values in a recording into dynamically injectable variables — a key capability for enabling **AI Agent-driven execution**.

### What is Parameterization

Using a login flow as an example:

| Step               | During Recording          | After Parameterization |
| ------------------ | ------------------------- | ---------------------- |
| Enter username     | `admin`                   | `{username}`           |
| Enter password     | `123456`                  | `{password}`           |
| Navigate to system | `https://sys.example.com` | `{systemUrl}`          |

After parameterization, these values are no longer fixed — they are supplied externally at replay/invocation time.

### Single Action Parameterization

1. Click an action step in the workflow editor to open the editing dialog
2. Toggle on the **Parameterize** switch
3. Set the **Variable Name** (e.g., `username`)
4. Optionally enter a **Parameter Description** (e.g., "Login username")
5. Optionally set a **Default Value** (e.g., `admin`)
6. Save

Once parameterization is enabled, the action's value field displays as a variable reference (e.g., `{username}`), and the actual value is injected at runtime.

### Batch Parameterization

For workflows with multiple input actions, you can use the **Batch Parameterize** feature:

1. If there are non-parameterized `input`/`change`/`navigate` actions, a **Batch Parameterize** prompt appears at the top of the workflow editor
2. Click it, and the system automatically generates variable names based on element attributes (`name`, `id`, `placeholder`, etc.)
3. Current values are automatically set as default values
4. You can further adjust settings in the editing dialog

### Variable Resolution

The replay engine uses `{variableName}` syntax for variable substitution:

```
Input value: "Hello, {username}! Your code is {verifyCode}"
Variables passed: { username: "John", verifyCode: "123456" }
Actual execution: "Hello, John! Your code is 123456"
```

Variable resolution supports:

* Full replacement: `{username}` → `John`
* Inline replacement: `https://{host}/api` → `https://example.com/api`
* Unmatched variables are kept as-is: `{unknown}` → `{unknown}`

## Replay Testing

### Basic Replay

For workflows without parameterized actions, simply select a browser profile and start replay.

### Parameterized Replay

When a workflow contains parameterized actions, clicking replay opens a **Parameter Input Dialog**:

1. All parameterized fields are automatically displayed
2. Parameter name, description, and default value are shown
3. Required parameters (no default value) are marked in red
4. Enter test values and click **Start Replay**

### Replay Engine

Replay is CDP-based and has the following characteristics:

| Feature                | Description                                                                                               |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| **Element Wait**       | Automatically waits for the target element to appear (up to 10 seconds)                                   |
| **Retry Mechanism**    | Automatically retries failed actions (up to 3 times, 1-second interval)                                   |
| **Timeout Protection** | Skips a single action after 30-second timeout                                                             |
| **Progress Feedback**  | Shows real-time execution progress and step status                                                        |
| **Visual Status**      | Highlights the current execution step in the editor (blue = in progress / green = success / red = failed) |

## Video Recording

### Recording Options

| Option                   | Description                                             |
| ------------------------ | ------------------------------------------------------- |
| **Screen/Window Source** | Choose to record the entire screen or a specific window |
| **Resolution**           | 720p / 1080p / 4K                                       |
| **Frame Rate**           | 30fps / 60fps                                           |
| **Microphone Audio**     | Record voice narration                                  |
| **System Audio**         | Record system sound (macOS requires BlackHole)          |

### Video-Action Synchronization

Video and action events are aligned by timestamps:

* Each action records a `videoTimestamp` (seconds relative to recording start)
* Clicking an action step in the editor automatically jumps the video to the corresponding time
* During replay, the video preview syncs with action execution

### Storage Estimates

| Resolution | Frame Rate | Duration   | File Size    |
| ---------- | ---------- | ---------- | ------------ |
| 720p       | 30fps      | 10 minutes | \~80-120 MB  |
| 1080p      | 30fps      | 10 minutes | \~150-250 MB |
| 1080p      | 30fps      | 1 minute   | \~15-25 MB   |

## Local Storage

Workflow data is stored in the local file system:

```
{userData}/workflows/
├── {workflow-id}.json          # Workflow definition (action sequence + metadata)
├── {workflow-id}/
│   ├── recordings/             # Recorded video files
│   │   └── recording.webm
│   ├── screenshots/            # Keyframe screenshots
│   │   ├── action-001.png
│   │   └── action-002.png
│   └── metadata.json           # Sync metadata
```

### Workflow JSON Structure

```json theme={null}
{
  "id": "wf-abc123",
  "name": "Log in to system and query data",
  "actions": [
    {
      "id": "act-001",
      "type": "navigate",
      "url": "https://system.example.com",
      "timestamp": 1700000000000
    },
    {
      "id": "act-002",
      "type": "input",
      "selector": "#username",
      "value": "{username}",
      "isParameterized": true,
      "variableName": "username",
      "paramDescription": "Login username",
      "defaultValue": "admin",
      "elementFeatures": {
        "role": "textbox",
        "name": "Username",
        "placeholder": "Enter username"
      }
    }
  ],
  "profileId": "profile-001",
  "toolName": "login_and_query",
  "toolDescription": "Log in to the system and query specified data",
  "isPublished": true
}
```

## Next Steps

After recording and parameterizing a workflow, you can [publish it as an RPA tool](/en/desktop/rpa-workflow) so that AI Agents can invoke it remotely.