feat: Expose native isAccessibilityElement (#1146)

anton-yereshchenko · cursoragent · web-flow · commit e6156212e6fb · 2026-06-08T20:23:02.000-07:00
* feat: expose native isAccessibilityElement

* refactor: rename nativeAccessible to nativeAccessibilityElement

Address review feedback to use the full word for clarity:
- protocol property wdNativeAccessible -&gt; wdNativeAccessibilityElement
- JSON key isNativeAccessible -&gt; isNativeAccessibilityElement
- XML attribute nativeAccessible -&gt; nativeAccessibilityElement
- setting includeNativeAccessibleInPageSource -&gt; includeNativeAccessibilityElementInPageSource

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;

* Unify JSON attribute key prefixing

* Remove empty-key guard from FBJsonPrefixedAttributeKey

---------

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/WebDriverAgentLib/Categories/XCUIApplication+FBHelpers.m b/WebDriverAgentLib/Categories/XCUIApplication+FBHelpers.m
@@ -44,13 +44,21 @@
 static NSString* const FBExclusionAttributeEnabled = @"enabled";
 static NSString* const FBExclusionAttributeVisible = @"visible";
 static NSString* const FBExclusionAttributeAccessible = @"accessible";
+static NSString* const FBExclusionAttributeNativeAccessibilityElement = @"nativeAccessibilityElement";
 static NSString* const FBExclusionAttributeFocused = @"focused";
 static NSString* const FBExclusionAttributePlaceholderValue = @"placeholderValue";
 static NSString* const FBExclusionAttributeNativeFrame = @"nativeFrame";
 static NSString* const FBExclusionAttributeTraits = @"traits";
 static NSString* const FBExclusionAttributeMinValue = @"minValue";
 static NSString* const FBExclusionAttributeMaxValue = @"maxValue";
 
+static NSString *FBJsonPrefixedAttributeKey(NSString *key)
+{
+  return [NSString stringWithFormat:@"is%@%@",
+          [[key substringToIndex:1] uppercaseString],
+          [key substringFromIndex:1]];
+}
+
 _Nullable id extractIssueProperty(id issue, NSString *propertyName) {
   SEL selector = NSSelectorFromString(propertyName);
   NSMethodSignature *methodSignature = [issue methodSignatureForSelector:selector];
@@ -223,7 +231,7 @@ + (NSDictionary *)dictionaryForElement:(id<FBXCElementSnapshot>)snapshot
           if ([nonPrefixedKeys containsObject:key]) {
               info[key] = value;
           } else {
-              info[[NSString stringWithFormat:@"is%@", [key capitalizedString]]] = value;
+              info[FBJsonPrefixedAttributeKey(key)] = value;
           }
       }
   }
@@ -268,6 +276,9 @@ + (NSDictionary *)dictionaryForElement:(id<FBXCElementSnapshot>)snapshot
   },
     FBExclusionAttributeAccessible: ^{
     return [@([wrappedSnapshot isWDAccessible]) stringValue];
+  },
+    FBExclusionAttributeNativeAccessibilityElement: ^{
+    return [@([wrappedSnapshot isWDNativeAccessibilityElement]) stringValue];
   },
     FBExclusionAttributeFocused: ^{
     return [@([wrappedSnapshot isWDFocused]) stringValue];
diff --git a/WebDriverAgentLib/Categories/XCUIElement+FBWebDriverAttributes.m b/WebDriverAgentLib/Categories/XCUIElement+FBWebDriverAttributes.m
@@ -202,6 +202,11 @@ - (BOOL)isWDFocused
   return self.hasFocus;
 }
 
+- (BOOL)isWDNativeAccessibilityElement
+{
+  return self.fb_isAccessibilityElement;
+}
+
 - (BOOL)isWDAccessible
 {
   XCUIElementType elementType = self.elementType;
diff --git a/WebDriverAgentLib/Routing/FBElement.h b/WebDriverAgentLib/Routing/FBElement.h
@@ -55,6 +55,9 @@ NS_ASSUME_NONNULL_BEGIN
 /*! Whether element is accessible */
 @property (nonatomic, readonly, getter = isWDAccessible) BOOL wdAccessible;
 
+/*! The raw, native `isAccessibilityElement` value reported by the accessibility framework, without WebDriverAgent's custom computation applied by `wdAccessible` */
+@property (nonatomic, readonly, getter = isWDNativeAccessibilityElement) BOOL wdNativeAccessibilityElement;
+
 /*! Whether element is an accessibility container (contains children of any depth that are accessible) */
 @property (nonatomic, readonly, getter = isWDAccessibilityContainer) BOOL wdAccessibilityContainer;
 
diff --git a/WebDriverAgentLib/Utilities/FBConfiguration.h b/WebDriverAgentLib/Utilities/FBConfiguration.h
@@ -366,6 +366,24 @@ typedef NS_ENUM(NSInteger, FBConfigurationKeyboardPreference) {
 + (void)setIncludeNativeFrameInPageSource:(BOOL)enabled;
 + (BOOL)includeNativeFrameInPageSource;
 
+/**
+ * Whether to include the `nativeAccessibilityElement` attribute in the XML page source.
+ *
+ * When enabled, the XML representation will contain the raw, native
+ * `isAccessibilityElement` value as reported by the accessibility framework,
+ * without the custom computation that WebDriverAgent applies to the
+ * `accessible` attribute (cell/text field special cases and parent absorption).
+ *
+ * This is useful for consumers that need to reason about the unmodified
+ * accessibility flag alongside the computed `accessible` value.
+ *
+ * The value is disabled by default to keep the default page source stable.
+ *
+ * @param enabled Either YES or NO
+ */
++ (void)setIncludeNativeAccessibilityElementInPageSource:(BOOL)enabled;
++ (BOOL)includeNativeAccessibilityElementInPageSource;
+
 /**
  * Whether to include `minValue`/`maxValue` attributes in the page source.
  * These attributes are retrieved from native element snapshots and represent
diff --git a/WebDriverAgentLib/Utilities/FBConfiguration.m b/WebDriverAgentLib/Utilities/FBConfiguration.m
@@ -61,6 +61,7 @@
 #endif
 static BOOL FBShouldIncludeHittableInPageSource = NO;
 static BOOL FBShouldIncludeNativeFrameInPageSource = NO;
+static BOOL FBShouldIncludeNativeAccessibilityElementInPageSource = NO;
 static BOOL FBShouldIncludeMinMaxValueInPageSource = NO;
 static BOOL FBShouldIncludeCustomActionsInPageSource = NO;
 static BOOL FBShouldEnforceCustomSnapshots = NO;
@@ -665,6 +666,16 @@ + (BOOL)includeNativeFrameInPageSource
   return FBShouldIncludeNativeFrameInPageSource;
 }
 
++ (void)setIncludeNativeAccessibilityElementInPageSource:(BOOL)enabled
+{
+  FBShouldIncludeNativeAccessibilityElementInPageSource = enabled;
+}
+
++ (BOOL)includeNativeAccessibilityElementInPageSource
+{
+  return FBShouldIncludeNativeAccessibilityElementInPageSource;
+}
+
 + (void)setIncludeMinMaxValueInPageSource:(BOOL)enabled
 {
   FBShouldIncludeMinMaxValueInPageSource = enabled;
diff --git a/WebDriverAgentLib/Utilities/FBSettings.h b/WebDriverAgentLib/Utilities/FBSettings.h
@@ -41,6 +41,7 @@ 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;
+extern NSString *const FB_SETTING_INCLUDE_NATIVE_ACCESSIBILITY_ELEMENT_IN_PAGE_SOURCE;
 extern NSString *const FB_SETTING_INCLUDE_MIN_MAX_VALUE_IN_PAGE_SOURCE;
 extern NSString *const FB_SETTING_INCLUDE_CUSTOM_ACTIONS_IN_PAGE_SOURCE;
 extern NSString *const FB_SETTING_ENFORCE_CUSTOM_SNAPSHOTS;
diff --git a/WebDriverAgentLib/Utilities/FBSettings.m b/WebDriverAgentLib/Utilities/FBSettings.m
@@ -37,6 +37,7 @@
 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";
+NSString* const FB_SETTING_INCLUDE_NATIVE_ACCESSIBILITY_ELEMENT_IN_PAGE_SOURCE = @"includeNativeAccessibilityElementInPageSource";
 NSString* const FB_SETTING_INCLUDE_MIN_MAX_VALUE_IN_PAGE_SOURCE = @"includeMinMaxValueInPageSource";
 NSString* const FB_SETTING_INCLUDE_CUSTOM_ACTIONS_IN_PAGE_SOURCE = @"includeCustomActionsInPageSource";
 NSString* const FB_SETTING_ENFORCE_CUSTOM_SNAPSHOTS = @"enforceCustomSnapshots";
diff --git a/WebDriverAgentLib/Utilities/FBSettingsHandler.m b/WebDriverAgentLib/Utilities/FBSettingsHandler.m
@@ -162,6 +162,10 @@ @implementation FBSettingsHandler
       [FBConfiguration setIncludeNativeFrameInPageSource:[value boolValue]];
       return nil;
     };
+    map[FB_SETTING_INCLUDE_NATIVE_ACCESSIBILITY_ELEMENT_IN_PAGE_SOURCE] = ^FBCommandStatus *(FBSession *session, id value) {
+      [FBConfiguration setIncludeNativeAccessibilityElementInPageSource:[value boolValue]];
+      return nil;
+    };
     map[FB_SETTING_INCLUDE_MIN_MAX_VALUE_IN_PAGE_SOURCE] = ^FBCommandStatus *(FBSession *session, id value) {
       [FBConfiguration setIncludeMinMaxValueInPageSource:[value boolValue]];
       return nil;
@@ -280,6 +284,9 @@ @implementation FBSettingsHandler
     map[FB_SETTING_INCLUDE_NATIVE_FRAME_IN_PAGE_SOURCE] = ^id(FBSession *session) {
       return @([FBConfiguration includeNativeFrameInPageSource]);
     };
+    map[FB_SETTING_INCLUDE_NATIVE_ACCESSIBILITY_ELEMENT_IN_PAGE_SOURCE] = ^id(FBSession *session) {
+      return @([FBConfiguration includeNativeAccessibilityElementInPageSource]);
+    };
     map[FB_SETTING_INCLUDE_MIN_MAX_VALUE_IN_PAGE_SOURCE] = ^id(FBSession *session) {
       return @([FBConfiguration includeMinMaxValueInPageSource]);
     };
diff --git a/WebDriverAgentLib/Utilities/FBXPath.m b/WebDriverAgentLib/Utilities/FBXPath.m
@@ -120,6 +120,10 @@ @interface FBNativeFrameAttribute : FBElementAttribute
 
 @end
 
+@interface FBNativeAccessibilityElementAttribute : FBElementAttribute
+
+@end
+
 @interface FBTraitsAttribute : FBElementAttribute
 
 @end
@@ -409,6 +413,10 @@ + (int)xmlRepresentationWithRootElement:(id<FBXCElementSnapshot>)root
       // Include nativeFrame only when requested
       [includedAttributes removeObject:FBNativeFrameAttribute.class];
     }
+    if (!FBConfiguration.includeNativeAccessibilityElementInPageSource) {
+      // Include the raw native accessibility flag only when requested
+      [includedAttributes removeObject:FBNativeAccessibilityElementAttribute.class];
+    }
     if (!FBConfiguration.includeMinMaxValueInPageSource) {
       // minValue/maxValue are retrieved from private APIs and may be slow on deep trees
       [includedAttributes removeObject:FBMinValueAttribute.class];
@@ -686,6 +694,7 @@ + (int)recordWithWriter:(xmlTextWriterPtr)writer forValue:(nullable NSString *)v
            FBEnabledAttribute.class,
            FBVisibleAttribute.class,
            FBAccessibleAttribute.class,
+           FBNativeAccessibilityElementAttribute.class,
 #if TARGET_OS_TV
            FBFocusedAttribute.class,
 #endif
@@ -954,6 +963,19 @@ + (NSString *)valueForElement:(id<FBElement>)element
 }
 @end
 
+@implementation FBNativeAccessibilityElementAttribute
+
++ (NSString *)name
+{
+  return @"nativeAccessibilityElement";
+}
+
++ (NSString *)valueForElement:(id<FBElement>)element
+{
+  return FBBoolToString(element.wdNativeAccessibilityElement);
+}
+@end
+
 @implementation FBTraitsAttribute
 
 + (NSString *)name
diff --git a/WebDriverAgentTests/IntegrationTests/FBElementAttributeTests.m b/WebDriverAgentTests/IntegrationTests/FBElementAttributeTests.m
@@ -41,6 +41,15 @@ - (void)testElementAccessibilityAttributes
   XCTAssertFalse(buttonElement.isWDAccessibilityContainer);
 }
 
+- (void)testNativeAccessibilityElementAttribute
+{
+  // wdNativeAccessibilityElement must expose the raw, native isAccessibilityElement flag
+  // without WebDriverAgent's custom computation applied by wdAccessible
+  XCUIElement *buttonElement = self.testedApplication.buttons[@"Button"];
+  XCTAssertTrue(buttonElement.exists);
+  XCTAssertEqual(buttonElement.wdNativeAccessibilityElement, buttonElement.fb_isAccessibilityElement);
+}
+
 - (void)testContainerAccessibilityAttributes
 {
   // "not_accessible" isn't accessibility element, but contains accessibility elements, so it is accessibility container
diff --git a/WebDriverAgentTests/UnitTests/Doubles/XCUIElementDouble.h b/WebDriverAgentTests/UnitTests/Doubles/XCUIElementDouble.h
@@ -31,6 +31,7 @@
 @property (nonatomic, readwrite) NSUInteger wdIndex;
 @property (nonatomic, readwrite, getter=isWDVisible) BOOL wdVisible;
 @property (nonatomic, readwrite, getter=isWDAccessible) BOOL wdAccessible;
+@property (nonatomic, readwrite, getter=isWDNativeAccessibilityElement) BOOL wdNativeAccessibilityElement;
 @property (nonatomic, readwrite, getter = isWDFocused) BOOL wdFocused;
 @property (nonatomic, readwrite, getter = isWDHittable) BOOL wdHittable;
 @property (nonatomic, copy, readwrite, nullable) NSString *wdPlaceholderValue;
diff --git a/WebDriverAgentTests/UnitTests/Doubles/XCUIElementDouble.m b/WebDriverAgentTests/UnitTests/Doubles/XCUIElementDouble.m
@@ -28,6 +28,7 @@ - (id)init
     self.wdCustomActions = nil;
     self.wdVisible = YES;
     self.wdAccessible = YES;
+    self.wdNativeAccessibilityElement = YES;
     self.wdEnabled = YES;
     self.wdSelected = YES;
     self.wdFocused = YES;
diff --git a/WebDriverAgentTests/UnitTests/FBXPathTests.m b/WebDriverAgentTests/UnitTests/FBXPathTests.m
@@ -92,8 +92,8 @@ - (void)testXPathPresentationBasedOnQueryMatchingAllAttributes
   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=\"%@\" traits=\"%@\" nativeFrame=\"%@\" customActions=\"%@\" 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.wdTraits, NSStringFromCGRect(element.wdNativeFrame), element.wdCustomActions];
+  NSString *expectedXml = [NSString stringWithFormat:@"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<%@ type=\"%@\" value=\"%@\" name=\"%@\" label=\"%@\" enabled=\"%@\" visible=\"%@\" accessible=\"%@\" nativeAccessibilityElement=\"%@\" x=\"%@\" y=\"%@\" width=\"%@\" height=\"%@\" index=\"%lu\" hittable=\"%@\" traits=\"%@\" nativeFrame=\"%@\" customActions=\"%@\" 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), FBBoolToString(element.wdNativeAccessibilityElement), element.wdRect[@"x"], element.wdRect[@"y"], element.wdRect[@"width"], element.wdRect[@"height"], element.wdIndex, FBBoolToString(element.wdHittable), element.wdTraits, NSStringFromCGRect(element.wdNativeFrame), element.wdCustomActions];
   XCTAssertEqualObjects(expectedXml, resultXml);
 }
 
diff --git a/WebDriverAgentTests/UnitTests_tvOS/Doubles/XCUIElementDouble.h b/WebDriverAgentTests/UnitTests_tvOS/Doubles/XCUIElementDouble.h
@@ -29,6 +29,7 @@
 @property (nonatomic, readwrite) NSUInteger wdIndex;
 @property (nonatomic, readwrite, getter=isWDVisible) BOOL wdVisible;
 @property (nonatomic, readwrite, getter=isWDAccessible) BOOL wdAccessible;
+@property (nonatomic, readwrite, getter=isWDNativeAccessibilityElement) BOOL wdNativeAccessibilityElement;
 @property (nonatomic, readwrite, getter=isWDFocused) BOOL wdFocused;
 @property (nonatomic, readwrite, getter = isWDHittable) BOOL wdHittable;
 @property (copy, nonnull) NSArray *children;
diff --git a/WebDriverAgentTests/UnitTests_tvOS/Doubles/XCUIElementDouble.m b/WebDriverAgentTests/UnitTests_tvOS/Doubles/XCUIElementDouble.m
@@ -24,6 +24,7 @@ - (id)init
     self.wdValue = @"magicValue";
     self.wdVisible = YES;
     self.wdAccessible = YES;
+    self.wdNativeAccessibilityElement = YES;
     self.wdEnabled = YES;
     self.wdSelected = YES;
     self.wdHittable = YES;

Original file line number	Diff line number	Diff line change
`@@ -202,6 +202,11 @@ - (BOOL)isWDFocused`
`202`	`202`	`return self.hasFocus;`
`203`	`203`	`}`
`204`	`204`
	`205`	`+- (BOOL)isWDNativeAccessibilityElement`
	`206`	`+{`
	`207`	`+ return self.fb_isAccessibilityElement;`
	`208`	`+}`
	`209`	`+`
`205`	`210`	`- (BOOL)isWDAccessible`
`206`	`211`	`{`
`207`	`212`	`XCUIElementType elementType = self.elementType;`