Skip to content

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

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

hoanle0126 wants to merge 5 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 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 multi-finder widget classes resolve deterministically (@FindBy > @FindBys > @FindAll > custom finders sorted by annotation class name) with null-return fallthrough, 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.

Comment thread docs/Page-objects.md Resolved
@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.

@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.

Earlier feedback is addressed, and I have a few points inline.

return null;
}
Field field = element instanceof Field ? (Field) element : null;
return buildFromFinder(finders.get(0), field);

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] On a widget class with several finders, the old code used a fixed @FindBy > @FindBys > @FindAll order (and tried the next one if the builder returned null). Now the pick is whichever annotation getDeclaredAnnotations() returns first, and nothing falls through if that builder returns null. For example, a widget class declared @FindAll(...) @FindBy(...) used to resolve via @FindBy and now resolves via @FindAll, a silent change of locator. The docs' "first one declared" also relies on reflection order, which the JDK doesn't specify. Is that intended? If not, keep a deterministic order for widget classes (e.g. Appium FindBy/FindBys/FindAll first, then custom finders), or fail on conflicts for classes too and document it.

* {@link io.appium.java_client.support.PageFactoryFinder} and
* {@link io.appium.java_client.support.AbstractFindByBuilder}.
*/
public class Annotations extends AbstractAnnotations {

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] Is this new public class needed? Nothing in the library uses it (DefaultFieldDecorator and the locator factories go through DefaultElementByBuilder); only AnnotationsTest does. It has the same simple name as Selenium's Annotations but is not a drop-in copy: the Javadoc says the buildByFromFindBy/buildByFromShortFindBy/etc. hooks are omitted. Users who subclassed Selenium's version would not get a working replacement. It also adds protected hooks (getField, buildByFromDefault, assertValidAnnotations) that must stay stable. Please either wire it into the decorator path so it has a purpose, or drop it from this PR and keep PageFactoryFinderSupport as the only entry point.

public By buildBy() {
assertValidAnnotations();

By ans = PageFactoryFinderSupport.buildBy(field);

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] assertValidAnnotations() already resolves and validates the finders, then PageFactoryFinderSupport.buildBy(field) resolves and validates them again (validateConflicts defaults to true). Use buildBy(field, false) here, or drop the explicit validation, to avoid the second pass.

checkDisallowedAnnotationPairs(findBy, findAll);
checkDisallowedAnnotationPairs(findBys, findAll);
if (annotatedElement != null) {
PageFactoryFinderSupport.validateFinderAnnotations(annotatedElement);

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] assertValidAnnotations() validates any AnnotatedElement, so a caller that sets a widget class as the annotated element and calls it gets IllegalArgumentException. buildDefaultBy() deliberately skips validation for classes. For consistency, validate only when the element is a Field here as well.

@hoanle0126

Copy link
Copy Markdown
Contributor Author

Thanks @mykola-mokhnach! Updated PR #2499 to address all four review points:

  1. Removed unused Annotations.java class: Kept PageFactoryFinderSupport as the single internal entry point instead of introducing a non-drop-in Annotations class, and moved the corresponding assertions into PageFactoryFinderSupportTest.
  2. Deterministic widget class precedence with null fallthrough (PageFactoryFinderSupport & docs/Page-objects.md): Ordered active finder annotations deterministically (@FindBy > @FindBys > @FindAll > custom @PageFactoryFinder annotations sorted by annotation class name) and updated buildBy to continue to the next finder when a builder returns null.
  3. Consistent field-only conflict validation (DefaultElementByBuilder.assertValidAnnotations()): Guarded validateFinderAnnotations with annotatedElement instanceof Field so class-level widget elements behave consistently with buildDefaultBy().
  4. Expanded tests in CustomFindByAnnotationTest covering @FindAll + @FindBy deterministic precedence on widget classes, null-builder fallthrough between multi-finder widget annotations, and DefaultElementByBuilder on a multi-finder widget class, and verified ./gradlew test checkstyleMain checkstyleTest javadoc :selenium-bridge:check.

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