Smart Locator Agent

Smart Locator Agent

Purpose: Generate stable and maintainable locators for UI automation.

Applicable frameworks:

• Playwright
• Selenium
• Appium

---

When to Use

Use this skill when:

• Generating locators for new UI elements
• Reviewing existing locators for stability
• Migrating locators between frameworks

---

Responsibilities

The agent must:

1. Inspect the DOM or mobile UI hierarchy (NEVER guess)
2. Identify stable attributes
3. Generate a reliable locator
4. Validate locator uniqueness
5. Provide fallback locator if primary is fragile

---

Locator Priority

Use the following priority order:

1. Accessibility attributes (aria-label, role)
2. data-testid / data-test / data-qa
3. id
4. name
5. Framework semantic locator
6. css selector
7. xpath (last option)

Note: For detailed rules, refer to .agent/rules/locator_strategy.md.

---

Playwright Locators

Preferred locator methods:

1. getByRole() — Best for semantic elements
2. getByLabel() — Best for form fields with labels
3. getByPlaceholder() — Best for inputs with placeholder text
4. getByText() — Best for text content
5. getByTestId() — Best when data-testid is available

Example:

page.getByRole("button", { name: "Submit" })
page.getByLabel("Email")
page.getByPlaceholder("Enter your password")

Note: For detailed rules, refer to .agent/rules/playwright_rules.md.

---

Selenium Locators

Preferred order:

1. id
2. data-testid
3. name
4. cssSelector
5. xpath

Example:

driver.findElement(By.id("login-button"));
driver.findElement(By.cssSelector("button[data-testid='submit-btn']"));

Note: For detailed rules, refer to .agent/rules/selenium_rules.md.

---

Appium Locators

Preferred order:

1. accessibility id
2. resource-id
3. id
4. iOS predicate string
5. class chain
6. xpath

Example:

driver.findElement(AppiumBy.accessibilityId("login_button"));
driver.findElement(AppiumBy.id("com.app:id/login_button"));
driver.findElement(AppiumBy.iOSNsPredicateString("label == 'Login'"));