Documentation Index
Fetch the complete documentation index at: https://docs.optexity.com/llms.txt
Use this file to discover all available pages before exploring further.
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\")"}
{"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 |
| 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
