Locators - Optexity Documentation

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:

{"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:

{"command": "get_by_label(\"Email address\")"}
{"command": "get_by_label(\"Password\")"}

Text-Based

Find by visible text:

{"command": "get_by_text(\"Welcome back\")"}
{"command": "get_by_text(\"Welcome\", exact=True)"}

Test ID

For elements with data-testid:

{"command": "get_by_test_id(\"login-button\")"}

CSS Selector

Direct CSS access:

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

Chaining

Narrow down to specific elements:

{"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:

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

XPath Locators

Use when Playwright locators can’t express the query:

{
  "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

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

XPath locators are more fragile than Playwright commands. Prefer command when possible.

Prompt Instructions

Natural language description used when locators fail:

{
  "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:

{"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:

{"prompt_instructions": "Click the button"}
{"prompt_instructions": "Click it"}

Include visual details, position, and context in prompt instructions.

Locator Selection Strategy

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

Dynamic Elements

Use variables in locators:

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

Always provide prompt_instructions as backup:

{"prompt_instructions": "Click on the row containing order {order_id[0]}"}

assert_locator_presence

Verify element exists before acting (for optional steps):

{
  "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

​Locator Methods

​Playwright Commands

​Role-Based (Recommended)

​Label-Based

​Text-Based

​Test ID

​CSS Selector

​Chaining

​Iframes

​XPath Locators

​Common Patterns

​Prompt Instructions

​Writing Good Instructions

​Locator Selection Strategy

​Dynamic Elements

​assert_locator_presence

Locator Methods

Playwright Commands

Role-Based (Recommended)

Label-Based

Text-Based

Test ID

CSS Selector

Chaining

Iframes

XPath Locators

Common Patterns

Prompt Instructions

Writing Good Instructions

Locator Selection Strategy

Dynamic Elements

assert_locator_presence