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

# Locators

> Finding elements on the page reliably

Optexity provides multiple ways to locate elements. Understanding when to use each method is key to building robust automations.

## Locator Methods

| Method                 | Field                 | When to Use                            |
| ---------------------- | --------------------- | -------------------------------------- |
| **Playwright Command** | `command`             | Preferred—robust, fast, no LLM tokens  |
| **XPath**              | `xpath`               | Complex DOM traversal                  |
| **AI Fallback**        | `prompt_instructions` | Always provide—used when locators fail |

***

## Playwright Commands

### Role-Based (Recommended)

Most resilient—doesn't depend on CSS classes or IDs:

```json theme={null}
{"command": "get_by_role(\"button\", name=\"Submit\")"}
{"command": "get_by_role(\"link\", name=\"Learn More\")"}
{"command": "get_by_role(\"textbox\", name=\"Email\")"}
{"command": "get_by_role(\"checkbox\", name=\"Remember me\")"}
{"command": "get_by_role(\"combobox\", name=\"Country\")"}
```

### Label-Based

Great for form fields:

```json theme={null}
{"command": "get_by_label(\"Email address\")"}
{"command": "get_by_label(\"Password\")"}
```

### Text-Based

Find by visible text:

```json theme={null}
{"command": "get_by_text(\"Welcome back\")"}
{"command": "get_by_text(\"Welcome\", exact=True)"}
```

### Test ID

For elements with `data-testid`:

```json theme={null}
{"command": "get_by_test_id(\"login-button\")"}
```

### CSS Selector

Direct CSS access:

```json theme={null}
{"command": "locator(\"#email-input\")"}
{"command": "locator(\".submit-button\")"}
{"command": "locator(\"[data-action='submit']\")"}
```

### Chaining

Narrow down to specific elements:

```json theme={null}
{"command": "get_by_role(\"navigation\").get_by_role(\"link\", name=\"Home\")"}
{"command": "locator(\"form#login\").get_by_role(\"button\", name=\"Submit\")"}
```

### Iframes

Access elements inside iframes:

```json theme={null}
{"command": "locator('#login-iframe').content_frame.get_by_role('button', name='Submit')"}
```

***

## XPath Locators

Use when Playwright locators can't express the query:

```json theme={null}
{
  "interaction_action": {
    "click_element": {
      "xpath": "//table[@id='results']//tr[contains(@class, 'active')]/td[3]/button",
      "prompt_instructions": "Click the action button in the active row"
    }
  }
}
```

### Common Patterns

```json theme={null}
{"xpath": "//button[text()='Submit']"}
{"xpath": "//div[contains(text(), 'Welcome')]"}
{"xpath": "//input[@type='email']"}
{"xpath": "//ul/li[3]/a"}
```

<Warning>
  XPath locators are more fragile than Playwright commands. Prefer `command` when possible.
</Warning>

***

## Prompt Instructions

Natural language description used when locators fail:

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

### Writing Good Instructions

**Good:**

```json theme={null}
{"prompt_instructions": "Click the blue 'Add to Cart' button below the product price"}
{"prompt_instructions": "Click Submit next to the Cancel button at the form bottom"}
{"prompt_instructions": "Click on order number {order_id[0]} in the orders table"}
```

**Poor:**

```json theme={null}
{"prompt_instructions": "Click the button"}
{"prompt_instructions": "Click it"}
```

<Tip>
  Include visual details, position, and context in prompt instructions.
</Tip>

***

## Locator Selection Strategy

```
1. Element has role + accessible name? → get_by_role()
2. Form element with label?            → get_by_label()
3. Has data-testid?                    → get_by_test_id()
4. Unique visible text?                → get_by_text()
5. Unique ID or class?                 → locator() with CSS
6. Complex DOM traversal?              → xpath
7. Dynamic or variable?                → prompt_instructions primarily
```

***

## Dynamic Elements

Use variables in locators:

```json theme={null}
{"command": "get_by_text(\"{order_id[0]}\")"}
{"command": "get_by_role(\"link\", name=\"{product[index]}\")"}
```

Always provide `prompt_instructions` as backup:

```json theme={null}
{"prompt_instructions": "Click on the row containing order {order_id[0]}"}
```

***

## assert\_locator\_presence

Verify element exists before acting (for optional steps):

```json theme={null}
{
  "click_element": {
    "command": "get_by_role(\"button\", name=\"Proceed\")",
    "prompt_instructions": "Click Proceed if visible",
    "assert_locator_presence": true
  }
}
```

When `true`:

* Checks if locator finds element
* Acts only if the element is present
* Fails the automation with a clear error reason if the element is not found