appium-webdriveragent 9.12.0 → 9.13.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [9.13.0](https://github.com/appium/WebDriverAgent/compare/v9.12.0...v9.13.0) (2025-06-05)
+
+### Features
+
+* expose nativeFrame attribute in XML page source ([#1029](https://github.com/appium/WebDriverAgent/issues/1029)) ([5b56a45](https://github.com/appium/WebDriverAgent/commit/5b56a453f836cbc4358ce24ae43032658467c35c))
+
 ## [9.12.0](https://github.com/appium/WebDriverAgent/compare/v9.11.0...v9.12.0) (2025-06-04)
 
 ### Features

package/WebDriverAgentLib/Commands/FBSessionCommands.m

@@ -354,6 +354,7 @@
       FB_SETTING_RESPECT_SYSTEM_ALERTS: @([FBConfiguration shouldRespectSystemAlerts]),
       FB_SETTING_USE_CLEAR_TEXT_SHORTCUT: @([FBConfiguration useClearTextShortcut]),
       FB_SETTING_INCLUDE_HITTABLE_IN_PAGE_SOURCE: @([FBConfiguration includeHittableInPageSource]),
+      FB_SETTING_INCLUDE_NATIVE_FRAME_IN_PAGE_SOURCE: @([FBConfiguration includeNativeFrameInPageSource]),
       FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE: @([FBConfiguration limitXpathContextScope]),
 #if !TARGET_OS_TV
       FB_SETTING_SCREENSHOT_ORIENTATION: [FBConfiguration humanReadableScreenshotOrientation],
@@ -457,7 +458,10 @@
     [FBConfiguration setUseClearTextShortcut:[[settings objectForKey:FB_SETTING_USE_CLEAR_TEXT_SHORTCUT] boolValue]];
   }
   if (nil != [settings objectForKey:FB_SETTING_INCLUDE_HITTABLE_IN_PAGE_SOURCE]) {
-    [FBConfiguration setincludeHittableInPageSource:[[settings objectForKey:FB_SETTING_INCLUDE_HITTABLE_IN_PAGE_SOURCE] boolValue]];
+    [FBConfiguration setIncludeHittableInPageSource:[[settings objectForKey:FB_SETTING_INCLUDE_HITTABLE_IN_PAGE_SOURCE] boolValue]];
+  }
+  if (nil != [settings objectForKey:FB_SETTING_INCLUDE_NATIVE_FRAME_IN_PAGE_SOURCE]) {
+    [FBConfiguration setIncludeNativeFrameInPageSource:[[settings objectForKey:FB_SETTING_INCLUDE_NATIVE_FRAME_IN_PAGE_SOURCE] boolValue]];
   }
   if (nil != [settings objectForKey:FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE]) {
     [FBConfiguration setLimitXpathContextScope:[[settings objectForKey:FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE] boolValue]];

package/WebDriverAgentLib/Info.plist

@@ -15,11 +15,11 @@
     <key>CFBundlePackageType</key>
     <string>FMWK</string>
     <key>CFBundleShortVersionString</key>
-    <string>9.12.0</string>
+    <string>9.13.0</string>
     <key>CFBundleSignature</key>
     <string>????</string>
     <key>CFBundleVersion</key>
-    <string>9.12.0</string>
+    <string>9.13.0</string>
     <key>NSPrincipalClass</key>
     <string/>
   </dict>

package/WebDriverAgentLib/Utilities/FBConfiguration.h

@@ -340,9 +340,25 @@ typedef NS_ENUM(NSInteger, FBConfigurationKeyboardPreference) {
  *
  * @param enabled Either YES or NO
  */
-+ (void)setincludeHittableInPageSource:(BOOL)enabled;
++ (void)setIncludeHittableInPageSource:(BOOL)enabled;
 + (BOOL)includeHittableInPageSource;
 
+/**
+ * Whether to include `nativeFrame` attribute in the XML page source.
+ *
+ * When enabled, the XML representation will contain the precise rendered
+ * frame of the UI element.
+ *
+ * This value is more accurate than the legacy `wdFrame`, which applies rounding
+ * and may introduce inconsistencies in size and position calculations.
+ *
+ * The value is disabled by default to avoid potential performance overhead.
+ *
+ * @param enabled Either YES or NO
+ */
++ (void)setIncludeNativeFrameInPageSource:(BOOL)enabled;
++ (BOOL)includeNativeFrameInPageSource;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/WebDriverAgentLib/Utilities/FBConfiguration.m

@@ -61,7 +61,8 @@ static BOOL FBLimitXpathContextScope = YES;
 #if !TARGET_OS_TV
 static UIInterfaceOrientation FBScreenshotOrientation;
 #endif
-static BOOL FBShouldincludeHittableInPageSource = NO;
+static BOOL FBShouldIncludeHittableInPageSource = NO;
+static BOOL FBShouldIncludeNativeFrameInPageSource = NO;
 
 @implementation FBConfiguration
 
@@ -643,14 +644,24 @@ static BOOL FBShouldincludeHittableInPageSource = NO;
   return NO;
 }
 
-+ (void)setincludeHittableInPageSource:(BOOL)enabled
++ (void)setIncludeHittableInPageSource:(BOOL)enabled
 {
-  FBShouldincludeHittableInPageSource = enabled;
+  FBShouldIncludeHittableInPageSource = enabled;
 }
 
 + (BOOL)includeHittableInPageSource
 {
-  return FBShouldincludeHittableInPageSource;
+  return FBShouldIncludeHittableInPageSource;
+}
+
++ (void)setIncludeNativeFrameInPageSource:(BOOL)enabled
+{
+  FBShouldIncludeNativeFrameInPageSource = enabled;
+}
+
++ (BOOL)includeNativeFrameInPageSource
+{
+  return FBShouldIncludeNativeFrameInPageSource;
 }
 
 @end

package/WebDriverAgentLib/Utilities/FBSettings.h

@@ -41,6 +41,7 @@ extern NSString* const FB_SETTING_USE_CLEAR_TEXT_SHORTCUT;
 extern NSString* const FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE;
 extern NSString* const FB_SETTING_AUTO_CLICK_ALERT_SELECTOR;
 extern NSString *const FB_SETTING_INCLUDE_HITTABLE_IN_PAGE_SOURCE;
+extern NSString *const FB_SETTING_INCLUDE_NATIVE_FRAME_IN_PAGE_SOURCE;
 
 
 NS_ASSUME_NONNULL_END

package/WebDriverAgentLib/Utilities/FBSettings.m

@@ -37,3 +37,4 @@ NSString* const FB_SETTING_USE_CLEAR_TEXT_SHORTCUT = @"useClearTextShortcut";
 NSString* const FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE = @"limitXPathContextScope";
 NSString* const FB_SETTING_AUTO_CLICK_ALERT_SELECTOR = @"autoClickAlertSelector";
 NSString* const FB_SETTING_INCLUDE_HITTABLE_IN_PAGE_SOURCE = @"includeHittableInPageSource";
+NSString* const FB_SETTING_INCLUDE_NATIVE_FRAME_IN_PAGE_SOURCE = @"includeNativeFrameInPageSource";

package/WebDriverAgentLib/Utilities/FBXPath.m

@@ -105,6 +105,10 @@
 
 @end
 
+@interface FBNativeFrameAttribute : FBElementAttribute
+
+@end
+
 @interface FBTraitsAttribute : FBElementAttribute
 
 @end
@@ -366,6 +370,10 @@ static NSString *const topNodeIndexPath = @"top";
       // thus we only include it when requested explicitly
       [includedAttributes removeObject:FBHittableAttribute.class];
     }
+    if (!FBConfiguration.includeNativeFrameInPageSource) {
+      // Include nativeFrame only when requested
+      [includedAttributes removeObject:FBNativeFrameAttribute.class];
+    }
     if (nil != excludedAttributes) {
       for (NSString *excludedAttributeName in excludedAttributes) {
         for (Class supportedAttribute in FBElementAttribute.supportedAttributes) {
@@ -588,6 +596,7 @@ static NSString *const FBAbstractMethodInvocationException = @"AbstractMethodInv
            FBHittableAttribute.class,
            FBPlaceholderValueAttribute.class,
            FBTraitsAttribute.class,
+           FBNativeFrameAttribute.class,
           ];
 }
 
@@ -823,7 +832,19 @@ static NSString *const FBAbstractMethodInvocationException = @"AbstractMethodInv
 {
   return element.wdPlaceholderValue;
 }
+@end
+
+@implementation FBNativeFrameAttribute
 
++ (NSString *)name
+{
+  return @"nativeFrame";
+}
+
++ (NSString *)valueForElement:(id<FBElement>)element
+{
+  return NSStringFromCGRect(element.wdNativeFrame);
+}
 @end
 
 @implementation FBTraitsAttribute

package/WebDriverAgentTests/UnitTests/FBXPathTests.m

@@ -75,7 +75,7 @@
   id<FBElement> element = (id<FBElement>)[FBXCElementSnapshotWrapper ensureWrapped:(id)snapshot];
   NSString *resultXml = [self xmlStringWithElement:(id<FBXCElementSnapshot>)element
                                         xpathQuery:nil
-                               excludingAttributes:@[@"type", @"visible", @"value", @"index", @"traits"]];
+                               excludingAttributes:@[@"type", @"visible", @"value", @"index", @"traits", @"nativeFrame"]];
   NSString *expectedXml = [NSString stringWithFormat:@"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<%@ name=\"%@\" label=\"%@\" enabled=\"%@\" accessible=\"%@\" x=\"%@\" y=\"%@\" width=\"%@\" height=\"%@\" placeholderValue=\"%@\" private_indexPath=\"top\"/>\n",
                            element.wdType, element.wdName, element.wdLabel, FBBoolToString(element.wdEnabled), FBBoolToString(element.wdAccessible), element.wdRect[@"x"], element.wdRect[@"y"], element.wdRect[@"width"], element.wdRect[@"height"], element.wdPlaceholderValue];
   XCTAssertEqualObjects(resultXml, expectedXml);
@@ -90,8 +90,8 @@
   NSString *resultXml = [self xmlStringWithElement:(id<FBXCElementSnapshot>)element
                                         xpathQuery:[NSString stringWithFormat:@"//%@[@*]", element.wdType]
                                excludingAttributes:@[@"visible"]];
-  NSString *expectedXml = [NSString stringWithFormat:@"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<%@ type=\"%@\" value=\"%@\" name=\"%@\" label=\"%@\" enabled=\"%@\" visible=\"%@\" accessible=\"%@\" x=\"%@\" y=\"%@\" width=\"%@\" height=\"%@\" index=\"%lu\" hittable=\"%@\" placeholderValue=\"%@\" traits=\"%@\" private_indexPath=\"top\"/>\n",
-                           element.wdType, element.wdType, @"йоло&lt;&gt;&amp;&quot;", element.wdName, @"a&#10;b", FBBoolToString(element.wdEnabled), FBBoolToString(element.wdVisible), FBBoolToString(element.wdAccessible), element.wdRect[@"x"], element.wdRect[@"y"], element.wdRect[@"width"], element.wdRect[@"height"], element.wdIndex, FBBoolToString(element.wdHittable), element.wdPlaceholderValue, element.wdTraits];
+  NSString *expectedXml = [NSString stringWithFormat:@"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<%@ type=\"%@\" value=\"%@\" name=\"%@\" label=\"%@\" enabled=\"%@\" visible=\"%@\" accessible=\"%@\" x=\"%@\" y=\"%@\" width=\"%@\" height=\"%@\" index=\"%lu\" hittable=\"%@\" placeholderValue=\"%@\" traits=\"%@\" nativeFrame=\"%@\" private_indexPath=\"top\"/>\n",
+                           element.wdType, element.wdType, @"йоло&lt;&gt;&amp;&quot;", element.wdName, @"a&#10;b", FBBoolToString(element.wdEnabled), FBBoolToString(element.wdVisible), FBBoolToString(element.wdAccessible), element.wdRect[@"x"], element.wdRect[@"y"], element.wdRect[@"width"], element.wdRect[@"height"], element.wdIndex, FBBoolToString(element.wdHittable), element.wdPlaceholderValue, element.wdTraits, NSStringFromCGRect(element.wdNativeFrame)];
   XCTAssertEqualObjects(expectedXml, resultXml);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-webdriveragent",
-  "version": "9.12.0",
+  "version": "9.13.0",
   "description": "Package bundling WebDriverAgent",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",