Skip to content

feat(pagefactory): support custom @PageFactoryFinder locator annotations - #2499

Open
hoanle0126 wants to merge 4 commits into
appium:masterfrom
hoanle0126:feat/custom-findby-annotations
Open

hoanle0126 wants to merge 4 commits into
appium:masterfrom
hoanle0126:feat/custom-findby-annotations

Conversation

@hoanle0126

@hoanle0126 hoanle0126 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Proposed changes

Fixes #1043

  • Add @PageFactoryFinder and Annotations under io.appium.java_client.support, and attach finder metadata to the built-in Appium FindBy, FindBys, and FindAll annotations.
  • Consolidate finder resolution, validation, and builder instantiation in PageFactoryFinderSupport with Selenium annotation proxy shims isolated in SeleniumAnnotationAdapter, shared by DefaultFieldDecorator and DefaultElementByBuilder across elements, lists, widgets (field and class level), and By / AppiumBy fields.
  • Keep existing page objects non-breaking: legacy org.openqa.selenium.support.PageFactoryFinder annotations remain unhandled, field-level finder conflicts throw IllegalArgumentException while widget class hierarchies and multi-finder widget classes preserve first-finder precedence, and widget subclass finder annotations override superclass finders.
  • Document custom finder annotations, AbstractFindByBuilder contracts (null field for class-level widget annotations and zero-arg builder constructors), and combined annotation rules in docs/Page-objects.md.

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)
  • Documentation Update (if none of the other choices apply)

@hoanle0126
hoanle0126 force-pushed the feat/custom-findby-annotations branch from 5810b53 to a0789c5 Compare November 11, 2026 05:36

@mykola-mokhnach mykola-mokhnach left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • [major] The PR ticks "New feature (non-breaking change)", but it changes how existing page objects behave, so it looks like a breaking change:

    • A field or widget class that combines @FindBy, @FindBys or @FindAll (Appium or Selenium) with another annotation carrying @PageFactoryFinder used to work, because only FindBy, FindBys and FindAll were inspected. It now throws IllegalArgumentException from initElements (DefaultElementByBuilder.java:194).
    • A field annotated only with an existing Selenium @PageFactoryFinder annotation used to fall back to the default locator (the field name). It is now resolved through the custom builder, so it returns different elements.
    • DefaultFieldDecorator now decorates List<WebElement> fields it used to skip (DefaultFieldDecorator.java:110).

    Either mark the PR as a breaking change (feat!:, tick the box, describe the impact), or make the new resolution not affect page objects that work today.

  • [major] Revert the changes to docs/openrewrite/migrate-to-v11.yml and docs/v10-to-v11-migration-guide.md. A non-breaking feature must not change the v10→v11 migration guides, and these edits contradict the "non-breaking" tick. If the change really needs migration notes, that confirms it is breaking.

  • [minor] docs/Page-objects.md doesn't describe custom @PageFactoryFinder annotations. It should cover the builder contract, that the builder needs a no-arg constructor, that buildIt gets a null field for class-level annotations, and what happens when finders are combined.

@mykola-mokhnach mykola-mokhnach left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in the current state this PR could only be merged as part of the next major release of java client

@hoanle0126

Copy link
Copy Markdown
Contributor Author

Updated the PR to keep existing page objects non-breaking: legacy org.openqa.selenium.support.PageFactoryFinder annotations are no longer intercepted, DefaultFieldDecorator continues to require an Appium @PageFactoryFinder annotation on List fields, and the changes to migrate-to-v11.yml and v10-to-v11-migration-guide.md have been reverted. Also consolidated finder resolution into PageFactoryFinderSupport and documented custom @PageFactoryFinder usage and inheritance/combination rules in docs/Page-objects.md.

@mykola-mokhnach mykola-mokhnach left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • [minor] Annotations (support/pagefactory/Annotations.java:24) is the Appium counterpart of Selenium's Annotations, but it has none of that class's protected hooks (buildByFromFindBy, buildByFromShortFindBy, buildByFromLongFindBy, assertValidFindBys, assertValidFindAll). A subclass that overrides them can't be ported. Is the smaller surface intentional? If so, please say so in the class Javadoc.

}
}
return defaultBy;
return annotatedElement != null ? PageFactoryFinderSupport.buildBy(annotatedElement) : null;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[minor] buildDefaultBy() now validates finder conflicts. assertValidAnnotations() used to be the only place that validated, and WidgetByBuilder runs it on the field, never on widget classes. WidgetByBuilder.getByFromDeclaredClass calls super.buildDefaultBy() on each widget class up the hierarchy. A widget class that declares two HTML finders (e.g. @FindBy + @FindAll) used to resolve silently to the first one. It now throws IllegalArgumentException when a field of that type is decorated. Is this tightening intended? If so, please call it out in the docs, since the PR is marked non-breaking. If not, validate only on the field path.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in c5f3892: kept widget class lookup non-breaking by adding PageFactoryFinderSupport.buildBy(element, validateConflicts) and validating conflicts only on the field path (annotatedElement instanceof Field) in DefaultElementByBuilder.buildDefaultBy(), updated docs/Page-objects.md to match, and verified first-finder precedence on multi-finder widget classes in CustomFindByAnnotationTest.

return annotation.annotationType().getName().equals(SELENIUM_SUPPORT_PACKAGE + type.getSimpleName());
}

private static <A extends Annotation> A adapt(Annotation source, Class<A> target) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[minor] This class now has four jobs: finder resolution and validation, builder instantiation, Selenium-annotation detection (SELENIUM_*, adaptBuiltinSeleniumFinder), and the dynamic-proxy adapter (adapt / readAttribute / convert). Consider moving the Selenium compat part into a package-private SeleniumAnnotationAdapter. It would own isSeleniumCounterpart, adapt and convert, plus the three Selenium name constants. PageFactoryFinderSupport would keep resolve / validate / build, and the "Selenium is optional" concern would sit in one place.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in c5f3892: extracted package-private SeleniumAnnotationAdapter in io.appium.java_client.support.pagefactory.internal for Selenium built-in annotation lookup and dynamic proxy adaptation, keeping PageFactoryFinderSupport focused on @PageFactoryFinder discovery, validation, and builder execution.

@@ -48,65 +42,10 @@ private SeleniumAnnotationsCompat() {
*/
@Nullable
static <A extends Annotation> A find(AnnotatedElement element, Class<A> type) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] After this refactor find and isPresent only forward to PageFactoryFinderSupport, and the class Javadoc still says it does the reflective reading. DefaultElementByBuilder.isLookupCached can call PageFactoryFinderSupport.isCompatibleAnnotationPresent directly, and this class can go. Also, DefaultFieldDecorator.hasStandardLocatorAnnotation now matches custom finders too, so the name is misleading.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in c5f3892: deleted SeleniumAnnotationsCompat, switched DefaultElementByBuilder.isLookupCached() to PageFactoryFinderSupport.isCompatibleAnnotationPresent(...), moved the adapter tests to SeleniumAnnotationAdapterTest, and renamed DefaultFieldDecorator.hasStandardLocatorAnnotation to hasLocatorAnnotation.

Comment thread docs/Page-objects.md Outdated
}
```

# Custom locator annotations

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] The new section is a top-level #, but its subsections use ### and skip ##. Also, the sample DataTestIdBuilder puts the id into a CSS selector without escaping, so an id containing ' breaks the selector. Please use ## for the subsections and either escape the id or mention the limitation.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in c5f3892: changed # Custom locator annotations and its subsections to ## / ### to match the surrounding hierarchy and escaped single quotes in DataTestIdBuilder via id.replace("'", "\\'").

@hoanle0126

Copy link
Copy Markdown
Contributor Author

Addressed all review items in commit c5f3892 (including documenting why Selenium's protected AbstractAnnotations hooks are omitted in Annotations class Javadoc) and verified with ./gradlew test checkstyleMain checkstyleTest javadoc :selenium-bridge:check. Ready for re-review @mykola-mokhnach.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Custom FindBy annotations

2 participants