Repository navigation
feat(pagefactory): support custom @PageFactoryFinder locator annotations - #2499
hoanle0126 wants to merge 5 commits into
Conversation
5810b53 to
a0789c5
Compare
mykola-mokhnach
left a comment
There was a problem hiding this comment.
-
[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,@FindBysor@FindAll(Appium or Selenium) with another annotation carrying@PageFactoryFinderused to work, because onlyFindBy,FindBysandFindAllwere inspected. It now throwsIllegalArgumentExceptionfrominitElements(DefaultElementByBuilder.java:194). - A field annotated only with an existing Selenium
@PageFactoryFinderannotation used to fall back to the default locator (the field name). It is now resolved through the custom builder, so it returns different elements. DefaultFieldDecoratornow decoratesList<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. - A field or widget class that combines
-
[major] Revert the changes to
docs/openrewrite/migrate-to-v11.ymlanddocs/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.mddoesn't describe custom@PageFactoryFinderannotations. It should cover the builder contract, that the builder needs a no-arg constructor, thatbuildItgets anullfield for class-level annotations, and what happens when finders are combined.
mykola-mokhnach
left a comment
There was a problem hiding this comment.
in the current state this PR could only be merged as part of the next major release of java client
|
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. |
There was a problem hiding this comment.
- [minor]
Annotations(support/pagefactory/Annotations.java:24) is the Appium counterpart of Selenium'sAnnotations, 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.
|
Addressed all review items in commit c5f3892 (including documenting why Selenium's protected |
mykola-mokhnach
left a comment
There was a problem hiding this comment.
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); |
There was a problem hiding this comment.
[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 { |
There was a problem hiding this comment.
[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); |
There was a problem hiding this comment.
[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); |
There was a problem hiding this comment.
[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.
…rministic widget finder precedence
|
Thanks @mykola-mokhnach! Updated PR #2499 to address all four review points:
|
Proposed changes
Fixes #1043
@PageFactoryFinderunderio.appium.java_client.support, and attach finder metadata to the built-in Appium FindBy, FindBys, and FindAll annotations.PageFactoryFinderSupportwith Selenium annotation proxy shims isolated inSeleniumAnnotationAdapter, shared byDefaultFieldDecoratorandDefaultElementByBuilderacross elements, lists, widgets (field and class level), and By / AppiumBy fields.@FindBy>@FindBys>@FindAll> custom finders sorted by annotation class name) with null-return fallthrough, and widget subclass finder annotations override superclass finders.AbstractFindByBuildercontracts (null field for class-level widget annotations and zero-arg builder constructors), and combined annotation rules indocs/Page-objects.md.Types of changes