Skip to main content
Best practices learned from real-world Optexity deployments.

​
Design Principles

PrinciplePractice
Start simpleBuild minimum viable automation first
IterateAdd complexity incrementally
Test with real dataValidate on realistic inputs
Document complexityComment non-obvious logic

​
Locator Strategy

​
Priority Order

PriorityMethodExample
1. BestRole-basedget_by_role("button", name="Submit")
2. GoodLabel-basedget_by_label("Email Address")
3. OkayTest IDget_by_test_id("submit-btn")
4. Last resortCSS/XPathlocator("#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

GoodBad
patient_date_of_birthdob
authorization_numbernum
search_queryq

​
Timing Guidelines

ScenarioRecommendation
Before extractionWait 3+ seconds for page to load
After navigationWait 1-2 seconds for render
Dynamic contentIncrease retry count
Form submissionWait 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

PracticeExample
Never hardcode credentialsUse secure_parameters
Use 1Password integrationStore in vault, retrieve at runtime
Avoid logging sensitive dataDon’t include in prompt instructions

​
Performance

TipBenefit
Minimize waitsStart conservative, optimize later
Use static over agenticFaster, cheaper, more reliable
Batch extractionsOne LLM call for multiple fields
Increase retries over timeoutsFaster when element appears

​
Debugging

​
Common Issues

SymptomSolution
”Element not found”Increase before_sleep_time
Wrong element clickedWait for page to settle
Empty extractionIncrease wait before extraction
Random failuresIncrease 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