Skip to main content

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.

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
  • Acts only if the element is present
  • Fails the automation with a clear error reason if the element is not found