Repository navigation
feat(pagefactory): support custom @PageFactoryFinder locator annotations - #2499
hoanle0126 wants to merge 4 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.
| } | ||
| } | ||
| return defaultBy; | ||
| return annotatedElement != null ? PageFactoryFinderSupport.buildBy(annotatedElement) : null; |
There was a problem hiding this comment.
[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.
There was a problem hiding this comment.
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) { |
There was a problem hiding this comment.
[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.
There was a problem hiding this comment.
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) { | |||
There was a problem hiding this comment.
[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.
There was a problem hiding this comment.
Addressed in c5f3892: deleted SeleniumAnnotationsCompat, switched DefaultElementByBuilder.isLookupCached() to PageFactoryFinderSupport.isCompatibleAnnotationPresent(...), moved the adapter tests to SeleniumAnnotationAdapterTest, and renamed DefaultFieldDecorator.hasStandardLocatorAnnotation to hasLocatorAnnotation.
| } | ||
| ``` | ||
|
|
||
| # Custom locator annotations |
There was a problem hiding this comment.
[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.
There was a problem hiding this comment.
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("'", "\\'").
|
Addressed all review items in commit c5f3892 (including documenting why Selenium's protected |
Proposed changes
Fixes #1043
@PageFactoryFinderandAnnotationsunderio.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.AbstractFindByBuildercontracts (null field for class-level widget annotations and zero-arg builder constructors), and combined annotation rules indocs/Page-objects.md.Types of changes