Use natural language locators in Appium AI

Before you begin

Ensure the following:

  • Your environment is configured to support natural language locators. If you are unsure, contact your lab administrator or Kobiton Support.

  • Your test runs in a supported context (view hierarchy available)

  • You are familiar with basic Appium commands such as findElement(…​)

  • You are using a private device deployment (natural language locators are not available for Public Cloud devices)

Use a natural language locator

To locate an element using natural language, pass a descriptive string into findElement(…​) using the "natural" locator strategy.

python
element = driver.find_element("natural", "The login button at the bottom")
element.click()
java
WebElement el = driver.findElement(ByNatural.natural("the Accessibility button with an apostrophe"));
el.click();

Write effective descriptions

Use clear, specific descriptions to help identify the correct element.

Good examples:

java
driver.findElement(ByNatural.natural("the Accessibility button with an apostrophe"));
driver.findElement(ByNatural.natural("Enter email in the username field"));
driver.findElement(ByNatural.natural("Select Calgary from the city dropdown"));

Less effective examples:

driver.findElement(ByNatural.natural("Click button")
driver.findElement("Select item")

When multiple similar elements are present, include additional context such as position, label, or surrounding UI to improve accuracy.

Expected behavior

Appium AI evaluates the description and returns the most relevant matching element based on available UI metadata.

Results are not guaranteed to be deterministic. If multiple elements match the description, you may need to refine the description to improve accuracy.

Natural language locators work alongside traditional selector strategies and are best used in combination with them, rather than as a complete replacement.

Troubleshooting

If an element is not found or the wrong element is returned:

  • Use more specific language in the description

  • Include additional context such as position, labels, or surrounding elements

  • Verify that the UI element is visible and accessible in the view hierarchy

  • Confirm that the application exposes sufficient UI metadata for element identification

If natural language locators are not working as expected, contact your lab administrator to verify the following:

  • OpenAI or Azure OpenAI API credentials are configured correctly

  • Natural language locators are properly configured in your environment

  • The deployment uses private devices (natural language locators are not available on Public Cloud devices)

If issues persist, contact Kobiton Support for assistance.

Next steps

For an overview of how natural language locators work and their limitations, see the Appium AI concept guide.