Web automation requires careful timing. Pages load at different speeds, elements appear dynamically, and networks can be slow.
Timing Controls
| Level | Properties |
|---|
| Action Node | before_sleep_time, end_sleep_time, expect_new_tab, max_new_tab_wait_time |
| Interaction Action | max_tries, max_timeout_seconds_per_try |
Sleep Times
before_sleep_time
Wait before executing the action. Use when page needs to load or settle.
{
"type": "action_node",
"interaction_action": { ... },
"before_sleep_time": 3.0
}
end_sleep_time
Wait after action completes. Use when subsequent actions depend on this action’s effects.
{
"type": "action_node",
"interaction_action": { ... },
"end_sleep_time": 2.0
}
Default Values
| Action Type | before_sleep_time | end_sleep_time |
|---|
| Interaction | 0.0 | 1.0 |
| Extraction | 3.0 | 0.0 |
| Assertion | 0.0 | 0.0 |
| 2FA | 0.0 | 0.0 |
Sleep times must be between 0 and 10 seconds.
Retry Configuration
Control how Optexity retries finding elements.
| Property | Type | Default | Description |
|---|
max_tries | int | 10 | Maximum retry attempts |
max_timeout_seconds_per_try | float | 1.0 | Timeout per attempt |
{
"interaction_action": {
"max_tries": 15,
"max_timeout_seconds_per_try": 2.0,
"click_element": { ... }
}
}
How Retries Work
- Attempt to find element using
command or xpath
- If not found within timeout, retry
- After all tries exhausted, use AI with
prompt_instructions
- If AI can’t find it, action fails
Increase max_tries rather than timeout per try. This finds elements faster when they appear while still handling slow pages.
Handling New Tabs
expect_new_tab
Set when action opens a new browser tab:
{
"type": "action_node",
"interaction_action": {
"click_element": {
"command": "get_by_role(\"link\", name=\"Open Report\")"
}
},
"expect_new_tab": true
}
expect_new_tab=True:
max_new_tab_wait_time automatically set to 10.0- Automation waits for new tab
- Focus switches to new tab
Common Patterns
Slow-Loading Pages
{
"type": "action_node",
"interaction_action": {
"click_element": {
"command": "get_by_role(\"button\", name=\"Search\")"
}
},
"end_sleep_time": 5.0
}
Dynamic AJAX Content
{
"type": "action_node",
"interaction_action": {
"max_tries": 15,
"max_timeout_seconds_per_try": 1.0,
"click_element": {
"command": "get_by_text(\"Results loaded\")"
}
},
"before_sleep_time": 2.0
}
Optional Elements
{
"type": "action_node",
"interaction_action": {
"max_tries": 3,
"click_element": {
"command": "get_by_role(\"button\", name=\"Dismiss\")",
"skip_prompt": true,
"assert_locator_presence": true
}
}
}
Troubleshooting
| Symptom | Likely Cause | Solution |
|---|
| ”Element not found” | Page not loaded | Increase before_sleep_time |
| Clicking wrong element | Page still loading | Increase before_sleep_time |
| Missing extracted data | Content not rendered | Increase wait before extraction |
| Next action fails | Previous effect not ready | Increase end_sleep_time |
| Random failures | Race conditions | Increase retries and timeouts |
Best Practices
| Practice | Recommendation |
|---|
| Start conservative | Use longer waits initially, optimize later |
| Use defaults | Let action-type defaults handle most cases |
| Wait before extraction | Ensure page stability |
| Wait after navigation | Give pages time to load |
| Increase retries | Prefer more tries over longer timeouts |
