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

​
Locator Methods

MethodFieldWhen to Use
Playwright CommandcommandPreferred—robust, fast, no LLM tokens
XPathxpathComplex DOM traversal
AI Fallbackprompt_instructionsAlways provide—used when locators fail

​
Playwright Commands

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

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: 
{"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
  • Skips action if not found (instead of failing)
  • Useful for dismiss dialogs, optional popups