feat: allow configuring default LocatorGroupStrategy for page objects by hoanle0126 · Pull Request #2480 · appium/java-client

hoanle0126 · 2026-10-25T20:53:22Z

Proposed changes

Allows configuring a custom default LocatorGroupStrategy (such as LocatorGroupStrategy.ALL_POSSIBLE) in one place instead of repeating @HowToUseLocators on every field:

Adds AppiumFieldDecorator(SearchContext, LocatorGroupStrategy) and AppiumFieldDecorator(SearchContext, Duration, LocatorGroupStrategy) constructors (plus DefaultElementByBuilder / WidgetByBuilder overloads) with Objects.requireNonNull validation.
New behavior: Honors class-level @HowToUseLocators annotations placed on page object / Widget classes, superclasses (@Inherited), interfaces, and enclosing classes.
Precedence order: field-level @HowToUseLocators > widget class @HowToUseLocators > page/declaring class @HowToUseLocators (including superclasses, interfaces, and enclosing classes) > AppiumFieldDecorator constructor defaultLocatorGroupStrategy > LocatorGroupStrategy.CHAIN.
Updates docs/Page-objects.md and adds unit tests in DefaultLocatorGroupStrategyTest.

Types of changes

Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

mykola-mokhnach · 2026-10-27T20:09:19Z

+        if (annotatedElement instanceof Field) {
+            Class<?> declaringClass = ((Field) annotatedElement).getDeclaringClass();
+            while (declaringClass != null && !declaringClass.equals(Object.class)) {
+                HowToUseLocators onClass = declaringClass.getAnnotation(HowToUseLocators.class);


Class-level @HowToUseLocators was allowed on types but ignored until now. Honoring it here changes behavior for existing pages that already carry the annotation (e.g. CHAIN -> ALL_POSSIBLE), unrelated to the new constructor. Is this intended? If so, it deserves an explicit mention in the PR description/changelog.

mykola-mokhnach · 2026-10-27T20:09:19Z

+            return Optional.of(direct);
+        }
+        if (annotatedElement instanceof Field) {
+            Class<?> declaringClass = ((Field) annotatedElement).getDeclaringClass();


The lookup starts at field.getDeclaringClass(), so it never sees the annotation on the page class actually being initialized. If a subclass is annotated but the fields are declared in an unannotated base page, the annotation is ignored. Enclosing classes and interfaces are not checked either. The new test only covers the annotation on the parent.

mykola-mokhnach · 2026-10-27T20:09:19Z

-                    getBys(AndroidFindBy.class, AndroidFindBys.class, AndroidFindAll.class));
+            return buildMobileBy(
+                    howToUseLocatorsOptional
+                            .map(HowToUseLocators::androidAutomation)


HowToUseLocators.androidAutomation()/iOSXCUITAutomation() default to CHAIN, so a present annotation can't distinguish "unset" from an explicit CHAIN. E.g. decorator default ALL_POSSIBLE plus a field annotated @HowToUseLocators(androidAutomation = CHAIN): on iOS the annotation's default CHAIN still wins, so the configured default is not applied. Same for a class-level annotation that sets only one platform.

mykola-mokhnach · 2026-10-27T20:09:19Z

        this.platform = readStringCapability(context, CapabilityType.PLATFORM_NAME);
        this.automation = readStringCapability(context, AUTOMATION_NAME_OPTION);
        this.duration = duration;
+        this.defaultLocatorGroupStrategy = defaultLocatorGroupStrategy != null


The null -> CHAIN fallback is repeated in five places (here, DefaultElementByBuilder, WidgetInterceptor, WidgetListInterceptor, and the 2-arg paths). A null passed by mistake is silently coerced. Consider Objects.requireNonNull or a single shared fallback.

mykola-mokhnach · 2026-10-27T20:09:19Z

+     * @param duration the timeout of waiting for an element presence
+     * @param defaultLocatorGroupStrategy the default strategy used when {@link HowToUseLocators} is not present
+     */
+    public WidgetInterceptor(


The strategy is threaded by hand through WidgetInterceptor, WidgetListInterceptor and AppiumFieldDecorator, each with a new public constructor overload, which enlarges the public API for internal plumbing. Anyone still using the old constructors (subclasses, third parties) silently falls back to CHAIN for nested widget fields.

mykola-mokhnach · 2026-10-27T20:09:19Z

+import static io.appium.java_client.support.PageFactory.initElements;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+public class DefaultLocatorGroupStrategyTest {


Coverage gaps: no test for the List<Widget> path (WidgetListInterceptor), a nested widget with its own class-level annotation, a null strategy, the (SearchContext, LocatorGroupStrategy) overload, or a field-level annotation that sets only one platform.

mykola-mokhnach · 2026-10-27T20:09:19Z

+public class DefaultLocatorGroupStrategyTest {
+
+    private static String unwrapByString(WebElement proxy) {
+        return proxy.toString();


Asserting on proxy.toString() ("Located by By.chained(...)") ties the tests to incidental message formats. They'd break if the proxy's toString or Selenium's By.chained/By.all toString changes, even with correct locator behavior, which is likely given the project tracks latest Selenium.

mykola-mokhnach · 2026-10-27T20:09:19Z

+    pageObject
+);
+```
+You can also annotate the page object class itself with `@HowToUseLocators(androidAutomation = ALL_POSSIBLE, iOSXCUITAutomation = ALL_POSSIBLE)`.


Please clarify that class-level @HowToUseLocators is new behavior, that superclass annotations also apply, and which one wins when both a class annotation and the constructor default are set.

…s-level @HowToUseLocators

hoanle0126 · 2026-10-27T22:47:40Z

Thanks for the detailed review @mykola-mokhnach! I have updated the PR to address all feedback:

Null Validation: Replaced the repeated null -> CHAIN fallback with Objects.requireNonNull in AppiumFieldDecorator and DefaultElementByBuilder.
No Public API Bloat on WidgetInterceptor / WidgetListInterceptor: Made the internal strategy constructors package-private and scoped the active decorator strategy so any subclass or caller invoking the existing 5-arg public constructors still inherits the configured default strategy for nested widget fields.
Class-Level @HowToUseLocators Lookup & Documentation: Marked @HowToUseLocators as @Inherited, tracked the active page/widget class in PageFactory.initElements, and extended DefaultElementByBuilder to check widget classes, the runtime page class, superclasses, interfaces, and enclosing classes. Also documented the new class-level behavior, precedence order, and single-platform annotation attribute default (CHAIN) in docs/Page-objects.md, Javadocs, and the PR description.
Behavioral Tests (DefaultLocatorGroupStrategyTest): Replaced proxy.toString() assertions with By instance assertions (ByChained vs ByAll) recorded during element lookups, and added test coverage for List<Widget>, widgets with class-level @HowToUseLocators, null strategy rejection, both AppiumFieldDecorator constructor overloads, single-platform @HowToUseLocators, annotated subclasses of unannotated base pages, interfaces, and enclosing classes.

mykola-mokhnach · 2026-10-28T07:06:35Z

 );
 ```

+- To change the default `LocatorGroupStrategy` (for example to `LocatorGroupStrategy.ALL_POSSIBLE`) for all fields that do not declare their own `@HowToUseLocators`:


Please also mention the minimum java client version where this feature has been added

Added the minimum Appium Java Client version (11.1.0) to docs/Page-objects.md, thanks!

feat: allow configuring default LocatorGroupStrategy for page objects

28f2395

hoanle0126 requested review from SrinivasanTarget, mykola-mokhnach, saikrishna321 and valfirst as code owners October 25, 2026 20:53

mykola-mokhnach reviewed Oct 27, 2026

View reviewed changes

fix: address review feedback on default LocatorGroupStrategy and clas…

65be04c

…s-level @HowToUseLocators

mykola-mokhnach reviewed Oct 28, 2026

View reviewed changes

docs: mention minimum java-client version (11.1.0) in Page-objects.md

c406296

mykola-mokhnach approved these changes Oct 28, 2026

View reviewed changes

Navigation Menu

Repository navigation

feat: allow configuring default LocatorGroupStrategy for page objects - #2480

feat: allow configuring default LocatorGroupStrategy for page objects#2480
hoanle0126 wants to merge 3 commits into
appium:masterfrom
hoanle0126:feat/default-locator-group-strategy-2122

hoanle0126 commented Oct 25, 2026 •

edited

Loading

Uh oh!

mykola-mokhnach Oct 27, 2026

Uh oh!

mykola-mokhnach Oct 27, 2026

Uh oh!

mykola-mokhnach Oct 27, 2026

Uh oh!

mykola-mokhnach Oct 27, 2026

Uh oh!

mykola-mokhnach Oct 27, 2026

Uh oh!

mykola-mokhnach Oct 27, 2026

Uh oh!

mykola-mokhnach Oct 27, 2026

Uh oh!

mykola-mokhnach Oct 27, 2026

Uh oh!

hoanle0126 commented Oct 27, 2026

Uh oh!

mykola-mokhnach Oct 28, 2026

Uh oh!

hoanle0126 Oct 28, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

hoanle0126 commented Oct 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Types of changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hoanle0126 commented Oct 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hoanle0126 commented Oct 25, 2026 •

edited

Loading