Best Practices

Best practices learned from real-world Optexity deployments.

Design Principles

Principle	Practice
Start simple	Build minimum viable automation first
Iterate	Add complexity incrementally
Test with real data	Validate on realistic inputs
Document complexity	Comment non-obvious logic

Locator Strategy

Priority Order

Priority	Method	Example
1. Best	Role-based	`get_by_role("button", name="Submit")`
2. Good	Label-based	`get_by_label("Email Address")`
3. Okay	Test ID	`get_by_test_id("submit-btn")`
4. Last resort	CSS/XPath	`locator("#submit-form-btn")`

Always Provide Fallback

{
  "click_element": {
    "command": "get_by_role(\"button\", name=\"Continue\")",
    "prompt_instructions": "Click the green Continue button at the bottom of the form"
  }
}

Avoid Dynamic IDs

Bad:

{"command": "locator(\"#btn_12345_submit\")"}

Good:

{"command": "get_by_role(\"button\", name=\"Submit\")"}

Naming Conventions

Good	Bad
`patient_date_of_birth`	`dob`
`authorization_number`	`num`
`search_query`	`q`

Timing Guidelines

Scenario	Recommendation
Before extraction	Wait 3+ seconds for page to load
After navigation	Wait 1-2 seconds for render
Dynamic content	Increase retry count
Form submission	Wait for confirmation

{
  "type": "action_node",
  "extraction_action": { ... },
  "before_sleep_time": 5.0
}

Error Handling

Optional Elements

Use assert_locator_presence for elements that may not appear:

{
  "click_element": {
    "command": "get_by_role(\"button\", name=\"Accept Cookies\")",
    "assert_locator_presence": true
  }
}

Skip Optional Steps

{
  "click_element": {
    "command": "get_by_role(\"button\", name=\"Skip Tutorial\")",
    "skip_prompt": true,
    "assert_locator_presence": true
  }
}

Security

Practice	Example
Never hardcode credentials	Use `secure_parameters`
Use 1Password integration	Store in vault, retrieve at runtime
Avoid logging sensitive data	Don’t include in prompt instructions

Performance

Tip	Benefit
Minimize waits	Start conservative, optimize later
Use static over agentic	Faster, cheaper, more reliable
Batch extractions	One LLM call for multiple fields
Increase retries over timeouts	Faster when element appears

Debugging

Common Issues

Symptom	Solution
”Element not found”	Increase `before_sleep_time`
Wrong element clicked	Wait for page to settle
Empty extraction	Increase wait before extraction
Random failures	Increase retry count

Debug with Screenshots

{
  "type": "action_node",
  "extraction_action": {
    "screenshot": {
      "filename": "debug_before_submit.png",
      "full_page": true
    }
  }
}

Pre-Deployment Checklist

All locators have prompt_instructions
Sensitive data in secure_parameters
Appropriate wait times for page loads
Optional elements use assert_locator_presence
Error cases considered
Tested on realistic data
Variable names are descriptive
Complex logic is commented

Quickstart

Building Automations

Action Types

Inference

Advanced

FAQs

Design Principles

Locator Strategy

Priority Order

Always Provide Fallback

Avoid Dynamic IDs

Naming Conventions

Timing Guidelines

Error Handling

Optional Elements

Skip Optional Steps

Security

Performance

Debugging

Common Issues

Debug with Screenshots

Pre-Deployment Checklist

​Design Principles

​Locator Strategy

​Priority Order

​Always Provide Fallback

​Avoid Dynamic IDs

​Naming Conventions

​Timing Guidelines

​Error Handling

​Optional Elements

​Skip Optional Steps

​Security

​Performance

​Debugging

​Common Issues

​Debug with Screenshots

​Pre-Deployment Checklist

Design Principles

Locator Strategy

Priority Order

Always Provide Fallback

Avoid Dynamic IDs

Naming Conventions

Timing Guidelines

Error Handling

Optional Elements

Skip Optional Steps

Security

Performance

Debugging

Common Issues

Debug with Screenshots

Pre-Deployment Checklist