appium-webdriveragent 16.13.3 → 16.13.4

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [16.13.4](https://github.com/appium/WebDriverAgent/compare/v16.13.3...v16.13.4) (2026-09-30)
+
+### Performance Improvements
+
+* use native predicates for accessibility id lookups ([#1286](https://github.com/appium/WebDriverAgent/issues/1286)) ([2ceb940](https://github.com/appium/WebDriverAgent/commit/2ceb940939c2033cb37b846962a966d42bb0ddab))
+
 ## [16.13.3](https://github.com/appium/WebDriverAgent/compare/v16.13.2...v16.13.3) (2026-09-30)
 
 ### Bug Fixes

package/WebDriverAgentLib/Categories/XCUIElement+FBFind.m

@@ -120,14 +120,27 @@
 - (NSArray<XCUIElement *> *)fb_descendantsMatchingIdentifier:(NSString *)accessibilityId
                                  shouldReturnAfterFirstMatch:(BOOL)shouldReturnAfterFirstMatch
 {
-  NSPredicate *predicate = [NSPredicate predicateWithBlock:^BOOL(id<FBXCElementSnapshot> snapshot,
-                                                                 NSDictionary<NSString *,id> * _Nullable bindings) {
-    @autoreleasepool {
-      return [[FBXCElementSnapshotWrapper wdNameWithSnapshot:snapshot] isEqualToString:accessibilityId];
+  // Standard snapshot attributes let XCTest evaluate a structured predicate
+  // without WDA's per-snapshot block callback, while preserving wdName semantics.
+  // Local benchmarks showed lower end-to-end lookup latency; see measurements
+  // and regression checks in https://github.com/appium/WebDriverAgent/pull/1286.
+  NSPredicate *predicate = [NSPredicate predicateWithFormat:
+    @"(identifier != nil AND identifier != '' AND identifier == %@) OR "
+     "((identifier == nil OR identifier == '') AND label != nil AND label != '' AND label == %@)",
+    accessibilityId, accessibilityId];
+  XCUIElementQuery *query = [[self.fb_query descendantsMatchingType:XCUIElementTypeAny]
+    matchingPredicate:predicate];
+  NSMutableArray<XCUIElement *> *result = [NSMutableArray arrayWithArray:
+    [self.class fb_extractMatchingElementsFromQuery:query
+                       shouldReturnAfterFirstMatch:shouldReturnAfterFirstMatch]];
+  id<FBXCElementSnapshot> cachedSnapshot = [self fb_cachedSnapshotWithQuery:query];
+  if ([predicate evaluateWithObject:cachedSnapshot]) {
+    if (shouldReturnAfterFirstMatch || result.count == 0) {
+      return @[self];
     }
-  }];
-  return [self fb_descendantsMatchingPredicate:predicate
-                   shouldReturnAfterFirstMatch:shouldReturnAfterFirstMatch];
+    [result insertObject:self atIndex:0];
+  }
+  return result.copy;
 }
 
 @end

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentTests/IntegrationApp/Classes/SceneDelegate.m

@@ -10,7 +10,40 @@
 
 @implementation SceneDelegate
 
+- (void)showIdentifierLookupFixture
+{
+  UIViewController *controller = [UIViewController new];
+  controller.view.backgroundColor = UIColor.whiteColor;
+  controller.view.accessibilityIdentifier = @"IdentifierLookupFixture";
+  NSArray *identifiers = @[@"something", @"different", @"", NSNull.null, @"something", @"", NSNull.null, @"quote'\"é", NSNull.null];
+  NSArray<NSString *> *labels = @[@"other label", @"something", @"something", @"something", @"something", @"", @"", @"quoted", @"日本語"];
+  NSMutableArray<UILabel *> *labelViews = [NSMutableArray array];
+  for (NSUInteger i = 0; i < identifiers.count; i++) {
+    UILabel *label = [[UILabel alloc] initWithFrame:CGRectMake(20, 90 + i * 40, 300, 35)];
+    label.text = [NSString stringWithFormat:@"Fixture %lu", (unsigned long)i];
+    label.accessibilityIdentifier = identifiers[i] == NSNull.null ? nil : identifiers[i];
+    label.accessibilityLabel = labels[i];
+    label.isAccessibilityElement = YES;
+    [labelViews addObject:label];
+    [controller.view addSubview:label];
+  }
+  UIButton *mutate = [UIButton buttonWithType:UIButtonTypeSystem];
+  mutate.frame = CGRectMake(20, 470, 220, 40);
+  [mutate setTitle:@"Change identifier" forState:UIControlStateNormal];
+  mutate.accessibilityIdentifier = @"mutateIdentifier";
+  [mutate addAction:[UIAction actionWithHandler:^(__kindof UIAction *action) {
+    labelViews[0].accessibilityIdentifier = @"changed";
+  }] forControlEvents:UIControlEventTouchUpInside];
+  [controller.view addSubview:mutate];
+  self.window.rootViewController = controller;
+  [self.window makeKeyAndVisible];
+}
+
 - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--identifier-lookup-test"]) {
+    [self showIdentifierLookupFixture];
+    return;
+  }
   // Use this method to optionally configure and attach the UIWindow `window` to the provided UIWindowScene `scene`.
   // If using a storyboard, the `window` property will automatically be set and attached to the scene.
   // This delegate does not imply the connecting scene or session are new (see `application:configurationForConnectingSceneSession:` instead).

package/WebDriverAgentTests/IntegrationTests/XCUIElementFBFindTests.m

@@ -9,6 +9,7 @@
 #import <XCTest/XCTest.h>
 
 #import "FBIntegrationTestCase.h"
+#import "FBConfiguration.h"
 #import "FBElementUtils.h"
 #import "FBExceptions.h"
 #import "FBTestMacros.h"
@@ -558,3 +559,115 @@
 }
 
 @end
+
+
+@interface XCUIElementFBFindTests_IdentifierSemantics : FBIntegrationTestCase
+@end
+
+@implementation XCUIElementFBFindTests_IdentifierSemantics
+
+- (void)setUp
+{
+  [super setUp];
+  self.testedApplication.launchArguments = @[@"--identifier-lookup-test"];
+  [self.testedApplication launch];
+  XCTAssertTrue([self.testedApplication.otherElements[@"IdentifierLookupFixture"] waitForExistenceWithTimeout:5]);
+}
+
+- (void)tearDown
+{
+  [self.testedApplication terminate];
+  [super tearDown];
+}
+
+- (void)testIdentifierTakesPrecedenceOverLabel
+{
+  NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingIdentifier:@"something"
+                                                              shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(matches.count, 4);
+  XCTAssertEqualObjects([matches valueForKey:@"label"], (@[@"other label", @"something", @"something", @"something"]));
+  XCTAssertEqual([self.testedApplication fb_descendantsMatchingIdentifier:@"different" shouldReturnAfterFirstMatch:NO].count, 1);
+  // A matching label must not override a different, nonempty identifier.
+  XCTAssertEqual([self.testedApplication fb_descendantsMatchingIdentifier:@"other label" shouldReturnAfterFirstMatch:NO].count, 0);
+}
+
+- (void)testEmptyIdentifierDoesNotMatchEmptyAccessibilityId
+{
+  // The fixture has an empty identifier with a nonempty label at index 2,
+  // and an empty identifier with an empty label at index 5.
+  XCUIElement *labelFallback = [self.testedApplication.staticTexts elementBoundByIndex:2];
+  XCUIElement *unnamed = [self.testedApplication.staticTexts elementBoundByIndex:5];
+  XCTAssertEqualObjects(labelFallback.identifier, @"");
+  XCTAssertEqualObjects(labelFallback.label, @"something");
+  XCTAssertEqualObjects(unnamed.identifier, @"");
+  XCTAssertEqualObjects(unnamed.label, @"");
+
+  // Regression guard for "identifier != nil AND identifier != ''": the old
+  // wdName lookup used the nonempty label, or nil when both fields were empty.
+  // Thus an empty query matched neither element. Checking only identifier != nil
+  // would instead let identifier == @"" match both, changing existing behavior.
+  BOOL previousFirstMatch = FBConfiguration.sharedInstance.useFirstMatch;
+  @try {
+    for (NSNumber *useFirstMatch in @[@NO, @YES]) {
+      FBConfiguration.sharedInstance.useFirstMatch = useFirstMatch.boolValue;
+      for (NSNumber *firstMatch in @[@NO, @YES]) {
+        XCTAssertEqual([self.testedApplication fb_descendantsMatchingIdentifier:@""
+                                                  shouldReturnAfterFirstMatch:firstMatch.boolValue].count, 0,
+                       @"An empty accessibility ID must not match empty identifiers, even when they are non-nil");
+      }
+    }
+  } @finally {
+    FBConfiguration.sharedInstance.useFirstMatch = previousFirstMatch;
+  }
+}
+
+- (void)testMissingQuotedAndUnicodeIdentifiers
+{
+  for (NSNumber *firstMatch in @[@NO, @YES]) {
+    XCTAssertEqual([self.testedApplication fb_descendantsMatchingIdentifier:@"missing-target" shouldReturnAfterFirstMatch:firstMatch.boolValue].count, 0);
+    XCTAssertEqual([self.testedApplication fb_descendantsMatchingIdentifier:@"quote'\"é" shouldReturnAfterFirstMatch:firstMatch.boolValue].count, 1);
+    XCTAssertEqual([self.testedApplication fb_descendantsMatchingIdentifier:@"日本語" shouldReturnAfterFirstMatch:firstMatch.boolValue].count, 1);
+  }
+}
+
+- (void)testFirstMatchAndParentScopeWithBothBindings
+{
+  BOOL previousBinding = FBConfiguration.sharedInstance.boundElementsByIndex;
+  @try {
+    for (NSNumber *indexed in @[@NO, @YES]) {
+      FBConfiguration.sharedInstance.boundElementsByIndex = indexed.boolValue;
+      // Use the element returned by WDA lookup, as the element-scoped endpoint does.
+      XCUIElement *parent = [self.testedApplication fb_descendantsMatchingIdentifier:@"IdentifierLookupFixture"
+                                                          shouldReturnAfterFirstMatch:YES].firstObject;
+      XCTAssertNotNil(parent);
+      // The HTTP endpoint resolves the parent when registering its element ID.
+      XCTAssertNotNil(parent.fb_uid);
+      NSArray<XCUIElement *> *matches = [parent fb_descendantsMatchingIdentifier:@"something" shouldReturnAfterFirstMatch:NO];
+      NSArray<XCUIElement *> *first = [parent fb_descendantsMatchingIdentifier:@"something" shouldReturnAfterFirstMatch:YES];
+      XCTAssertEqual(matches.count, 4);
+      XCTAssertEqual(first.count, 1);
+      XCTAssertEqualObjects(first.firstObject.fb_uid, matches.firstObject.fb_uid);
+      NSArray<XCUIElement *> *selfMatches = [parent fb_descendantsMatchingIdentifier:@"IdentifierLookupFixture" shouldReturnAfterFirstMatch:NO];
+      XCTAssertEqual(selfMatches.count, 1);
+      XCTAssertEqualObjects(selfMatches.firstObject.fb_uid, parent.fb_uid);
+    }
+  } @finally {
+    FBConfiguration.sharedInstance.boundElementsByIndex = previousBinding;
+  }
+}
+
+- (void)testIdentifierChangesAreObserved
+{
+  NSArray<XCUIElement *> *before = [self.testedApplication fb_descendantsMatchingIdentifier:@"something" shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(before.count, 4);
+  NSArray<NSString *> *beforeIds = [before valueForKey:@"fb_uid"];
+  [self.testedApplication.buttons[@"mutateIdentifier"] tap];
+  NSArray<XCUIElement *> *after = [self.testedApplication fb_descendantsMatchingIdentifier:@"something" shouldReturnAfterFirstMatch:NO];
+  NSArray<XCUIElement *> *changed = [self.testedApplication fb_descendantsMatchingIdentifier:@"changed" shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(after.count, 3);
+  XCTAssertEqual(changed.count, 1);
+  XCTAssertEqualObjects([after valueForKey:@"fb_uid"], [beforeIds subarrayWithRange:NSMakeRange(1, 3)]);
+  XCTAssertEqualObjects(changed.firstObject.fb_uid, beforeIds.firstObject);
+}
+
+@end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-webdriveragent",
-  "version": "16.13.3",
+  "version": "16.13.4",
   "description": "Package bundling WebDriverAgent",
   "keywords": [
     "Appium",