> ## 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

> Tips for building reliable and maintainable automations

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

```json theme={null}
{
  "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:**

```json theme={null}
{"command": "locator(\"#btn_12345_submit\")"}
```

**Good:**

```json theme={null}
{"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            |

```json theme={null}
{
  "type": "action_node",
  "extraction_action": { ... },
  "before_sleep_time": 5.0
}
```

***

## Error Handling

### Optional Elements

Use `assert_locator_presence` for elements that may not appear:

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

### Skip Optional Steps

```json theme={null}
{
  "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

```json theme={null}
{
  "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