appium-webdriveragent 16.13.3 → 16.13.5

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [16.13.5](https://github.com/appium/WebDriverAgent/compare/v16.13.4...v16.13.5) (2026-09-30)
+
+### Performance Improvements
+
+* stream page-source XML with exception-safe resource cleanup ([#1276](https://github.com/appium/WebDriverAgent/issues/1276)) ([4e8639b](https://github.com/appium/WebDriverAgent/commit/4e8639bf73f962591e3e7b3be211f289a19ebf84))
+
+## [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.5</string>
     <key>CFBundleSignature</key>
     <string>????</string>
     <key>CFBundleVersion</key>
-    <string>16.13.3</string>
+    <string>16.13.5</string>
     <key>NSPrincipalClass</key>
     <string/>
   </dict>

package/WebDriverAgentLib/Utilities/FBXPath.m

@@ -175,154 +175,175 @@ static NSString *const topNodeIndexPath = @"top";
 + (nullable NSString *)xmlStringWithRootElement:(id<FBElement>)root
                                         options:(nullable FBXMLGenerationOptions *)options
 {
-  xmlDocPtr doc;
-  xmlTextWriterPtr writer = xmlNewTextWriterDoc(&doc, 0);
-  int rc = xmlTextWriterStartDocument(writer, NULL, _UTF8Encoding, NULL);
-  if (rc < 0) {
-    [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterStartDocument. Error code: %d", rc];
-  } else {
-    BOOL hasScope = nil != options.scope && [options.scope length] > 0;
-    if (hasScope) {
-      rc = xmlTextWriterStartElement(writer,
-                                     (xmlChar *)[[self safeXmlStringWithString:options.scope] UTF8String]);
-      if (rc < 0) {
-        [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterStartElement for the tag value '%@'. Error code: %d", options.scope, rc];
-      }
+  xmlBufferPtr buffer = NULL;
+  xmlTextWriterPtr writer = NULL;
+  @try {
+    buffer = xmlBufferCreate();
+    if (NULL == buffer) {
+      [FBLogger log:@"Failed to invoke libxml2>xmlBufferCreate"];
+      return nil;
     }
-
-    if (rc >= 0) {
-      [self waitUntilStableWithElement:root];
-      // If 'includeHittableInPageSource' setting is enabled, then use native snapshots
-      // to calculate a more accurate value for the 'hittable' attribute.
-      rc = [self xmlRepresentationWithRootElement:[self snapshotWithRoot:root
-                                                        useNative:FBConfiguration.sharedInstance.includeHittableInPageSource]
-                                           writer:writer
-                                     elementStore:nil
-                                            query:nil
-                              excludingAttributes:options.excludedAttributes];
+    writer = xmlNewTextWriterMemory(buffer, 0);
+    if (NULL == writer) {
+      [FBLogger log:@"Failed to invoke libxml2>xmlNewTextWriterMemory"];
+      return nil;
     }
+    xmlTextWriterSetIndent(writer, 1);
+    xmlTextWriterSetIndentString(writer, BAD_CAST "  ");
+    int rc = xmlTextWriterStartDocument(writer, NULL, _UTF8Encoding, NULL);
+    if (rc < 0) {
+      [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterStartDocument. Error code: %d", rc];
+    } else {
+      BOOL hasScope = nil != options.scope && [options.scope length] > 0;
+      if (hasScope) {
+        rc = xmlTextWriterStartElement(writer,
+                                       (xmlChar *)[[self safeXmlStringWithString:options.scope] UTF8String]);
+        if (rc < 0) {
+          [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterStartElement for the tag value '%@'. Error code: %d", options.scope, rc];
+        }
+      }
 
-    if (rc >= 0 && hasScope) {
-      rc = xmlTextWriterEndElement(writer);
-      if (rc < 0) {
-        [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterEndElement. Error code: %d", rc];
+      if (rc >= 0) {
+        [self waitUntilStableWithElement:root];
+        // If 'includeHittableInPageSource' setting is enabled, then use native snapshots
+        // to calculate a more accurate value for the 'hittable' attribute.
+        rc = [self xmlRepresentationWithRootElement:[self snapshotWithRoot:root
+                                                          useNative:FBConfiguration.sharedInstance.includeHittableInPageSource]
+                                             writer:writer
+                                       elementStore:nil
+                                              query:nil
+                                excludingAttributes:options.excludedAttributes];
       }
-    }
 
-    if (rc >= 0) {
-      rc = xmlTextWriterEndDocument(writer);
-      if (rc < 0) {
-        [FBLogger logFmt:@"Failed to invoke libxml2>xmlXPathNewContext. Error code: %d", rc];
+      if (rc >= 0 && hasScope) {
+        rc = xmlTextWriterEndElement(writer);
+        if (rc < 0) {
+          [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterEndElement. Error code: %d", rc];
+        }
+      }
+
+      if (rc >= 0) {
+        rc = xmlTextWriterEndDocument(writer);
+        if (rc < 0) {
+          [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterEndDocument. Error code: %d", rc];
+        }
       }
     }
+    if (rc < 0) {
+      return nil;
+    }
+    return [[NSString alloc] initWithBytes:xmlBufferContent(buffer)
+                                  length:(NSUInteger)xmlBufferLength(buffer)
+                                encoding:NSUTF8StringEncoding];
+  } @finally {
+    if (NULL != writer) {
+      xmlFreeTextWriter(writer);
+    }
+    if (NULL != buffer) {
+      xmlBufferFree(buffer);
+    }
   }
-  if (rc < 0) {
-    xmlFreeTextWriter(writer);
-    xmlFreeDoc(doc);
-    return nil;
-  }
-  int buffersize;
-  xmlChar *xmlbuff;
-  xmlDocDumpFormatMemory(doc, &xmlbuff, &buffersize, 1);
-  xmlFreeTextWriter(writer);
-  xmlFreeDoc(doc);
-  NSString *result = [NSString stringWithCString:(const char *)xmlbuff encoding:NSUTF8StringEncoding];
-  xmlFree(xmlbuff);
-  return result;
 }
 
 + (NSArray<id<FBXCElementSnapshot>> *)matchesWithRootElement:(id<FBElement>)root
                                                     forQuery:(NSString *)xpathQuery
 {
-  xmlDocPtr doc;
-
-  xmlTextWriterPtr writer = xmlNewTextWriterDoc(&doc, 0);
-  if (NULL == writer) {
-    [FBLogger logFmt:@"Failed to invoke libxml2>xmlNewTextWriterDoc for XPath query \"%@\"", xpathQuery];
-    return [self throwException:FBXPathQueryEvaluationException forQuery:xpathQuery];
-  }
-  NSMutableDictionary *elementStore = [NSMutableDictionary dictionary];
-  int rc = xmlTextWriterStartDocument(writer, NULL, _UTF8Encoding, NULL);
-  id<FBXCElementSnapshot> lookupScopeSnapshot = nil;
-  id<FBXCElementSnapshot> contextRootSnapshot = nil;
-  BOOL useNativeSnapshot = nil == xpathQuery
-    ? NO
-    : [[self.class elementAttributesWithXPathQuery:xpathQuery] containsObject:FBHittableAttribute.class];
-  if (rc < 0) {
-    [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterStartDocument. Error code: %d", rc];
-  } else {
-    [self waitUntilStableWithElement:root];
-    if (FBConfiguration.sharedInstance.limitXpathContextScope) {
-      lookupScopeSnapshot = [self snapshotWithRoot:root useNative:useNativeSnapshot];
+  xmlDocPtr doc = NULL;
+  xmlTextWriterPtr writer = NULL;
+  xmlXPathObjectPtr contextNodeQueryResult = NULL;
+  xmlXPathObjectPtr queryResult = NULL;
+  @try {
+    writer = xmlNewTextWriterDoc(&doc, 0);
+    if (NULL == writer) {
+      [FBLogger logFmt:@"Failed to invoke libxml2>xmlNewTextWriterDoc for XPath query \"%@\"", xpathQuery];
+      return [self throwException:FBXPathQueryEvaluationException forQuery:xpathQuery];
+    }
+    NSMutableDictionary *elementStore = [NSMutableDictionary dictionary];
+    int rc = xmlTextWriterStartDocument(writer, NULL, _UTF8Encoding, NULL);
+    id<FBXCElementSnapshot> lookupScopeSnapshot = nil;
+    id<FBXCElementSnapshot> contextRootSnapshot = nil;
+    BOOL useNativeSnapshot = nil == xpathQuery
+      ? NO
+      : [[self.class elementAttributesWithXPathQuery:xpathQuery] containsObject:FBHittableAttribute.class];
+    if (rc < 0) {
+      [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterStartDocument. Error code: %d", rc];
     } else {
-      if ([root isKindOfClass:XCUIElement.class]) {
-        lookupScopeSnapshot = [self snapshotWithRoot:[(XCUIElement *)root application]
-                                           useNative:useNativeSnapshot];
-        // root.lastSnapshot may be stale leftover from an unrelated earlier command.
-        contextRootSnapshot = [root isKindOfClass:XCUIApplication.class]
-          ? nil
-          : ([(XCUIElement *)root fb_cachedSnapshot] ?: [self snapshotWithRoot:(XCUIElement *)root
-                                                                     useNative:useNativeSnapshot]);
+      [self waitUntilStableWithElement:root];
+      if (FBConfiguration.sharedInstance.limitXpathContextScope) {
+        lookupScopeSnapshot = [self snapshotWithRoot:root useNative:useNativeSnapshot];
       } else {
-        lookupScopeSnapshot = (id<FBXCElementSnapshot>)root;
-        contextRootSnapshot = nil == lookupScopeSnapshot.parent ? nil : (id<FBXCElementSnapshot>)root;
-        while (nil != lookupScopeSnapshot.parent) {
-          lookupScopeSnapshot = lookupScopeSnapshot.parent;
+        if ([root isKindOfClass:XCUIElement.class]) {
+          lookupScopeSnapshot = [self snapshotWithRoot:[(XCUIElement *)root application]
+                                             useNative:useNativeSnapshot];
+          // root.lastSnapshot may be stale leftover from an unrelated earlier command.
+          contextRootSnapshot = [root isKindOfClass:XCUIApplication.class]
+            ? nil
+            : ([(XCUIElement *)root fb_cachedSnapshot] ?: [self snapshotWithRoot:(XCUIElement *)root
+                                                                       useNative:useNativeSnapshot]);
+        } else {
+          lookupScopeSnapshot = (id<FBXCElementSnapshot>)root;
+          contextRootSnapshot = nil == lookupScopeSnapshot.parent ? nil : (id<FBXCElementSnapshot>)root;
+          while (nil != lookupScopeSnapshot.parent) {
+            lookupScopeSnapshot = lookupScopeSnapshot.parent;
+          }
         }
       }
-    }
 
-    rc = [self xmlRepresentationWithRootElement:lookupScopeSnapshot
-                                         writer:writer
-                                   elementStore:elementStore
-                                          query:xpathQuery
-                            excludingAttributes:nil];
-    if (rc >= 0) {
-      rc = xmlTextWriterEndDocument(writer);
-      if (rc < 0) {
-        [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterEndDocument. Error code: %d", rc];
+      rc = [self xmlRepresentationWithRootElement:lookupScopeSnapshot
+                                           writer:writer
+                                     elementStore:elementStore
+                                            query:xpathQuery
+                              excludingAttributes:nil];
+      if (rc >= 0) {
+        rc = xmlTextWriterEndDocument(writer);
+        if (rc < 0) {
+          [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterEndDocument. Error code: %d", rc];
+        }
       }
     }
-  }
-  if (rc < 0) {
-    xmlFreeTextWriter(writer);
-    xmlFreeDoc(doc);
-    return [self throwException:FBXPathQueryEvaluationException forQuery:xpathQuery];
-  }
+    if (rc < 0) {
+      return [self throwException:FBXPathQueryEvaluationException forQuery:xpathQuery];
+    }
 
-  xmlXPathObjectPtr contextNodeQueryResult = [self matchNodeInDocument:doc
-                                                          elementStore:elementStore.copy
-                                                           forSnapshot:contextRootSnapshot];
-  xmlNodePtr contextNode = NULL;
-  if (NULL != contextNodeQueryResult) {
-    xmlNodeSetPtr nodeSet = contextNodeQueryResult->nodesetval;
-    if (!xmlXPathNodeSetIsEmpty(nodeSet)) {
-      contextNode = nodeSet->nodeTab[0];
+    contextNodeQueryResult = [self matchNodeInDocument:doc
+                                                            elementStore:elementStore.copy
+                                                             forSnapshot:contextRootSnapshot];
+    xmlNodePtr contextNode = NULL;
+    if (NULL != contextNodeQueryResult) {
+      xmlNodeSetPtr nodeSet = contextNodeQueryResult->nodesetval;
+      if (!xmlXPathNodeSetIsEmpty(nodeSet)) {
+        contextNode = nodeSet->nodeTab[0];
+      }
+    }
+    NSString *evaluationError = nil;
+    queryResult = [self evaluate:xpathQuery
+                                          document:doc
+                                       contextNode:contextNode
+                                      errorMessage:&evaluationError];
+    if (NULL == queryResult) {
+      return [self throwException:FBInvalidXPathException forQuery:xpathQuery detail:evaluationError];
     }
-  }
-  NSString *evaluationError = nil;
-  xmlXPathObjectPtr queryResult = [self evaluate:xpathQuery
-                                        document:doc
-                                     contextNode:contextNode
-                                    errorMessage:&evaluationError];
-  if (NULL != contextNodeQueryResult) {
-    xmlXPathFreeObject(contextNodeQueryResult);
-  }
-  if (NULL == queryResult) {
-    xmlFreeTextWriter(writer);
-    xmlFreeDoc(doc);
-    return [self throwException:FBInvalidXPathException forQuery:xpathQuery detail:evaluationError];
-  }
 
-  NSArray *matchingSnapshots = [self collectMatchingSnapshots:queryResult->nodesetval
-                                                 elementStore:elementStore];
-  xmlXPathFreeObject(queryResult);
-  xmlFreeTextWriter(writer);
-  xmlFreeDoc(doc);
-  if (nil == matchingSnapshots) {
-    return [self throwException:FBXPathQueryEvaluationException forQuery:xpathQuery];
+    NSArray *matchingSnapshots = [self collectMatchingSnapshots:queryResult->nodesetval
+                                                   elementStore:elementStore];
+    if (nil == matchingSnapshots) {
+      return [self throwException:FBXPathQueryEvaluationException forQuery:xpathQuery];
+    }
+    return matchingSnapshots;
+  } @finally {
+    if (NULL != queryResult) {
+      xmlXPathFreeObject(queryResult);
+    }
+    if (NULL != contextNodeQueryResult) {
+      xmlXPathFreeObject(contextNodeQueryResult);
+    }
+    if (NULL != writer) {
+      xmlFreeTextWriter(writer);
+    }
+    if (NULL != doc) {
+      xmlFreeDoc(doc);
+    }
   }
-  return matchingSnapshots;
 }
 
 + (NSArray *)collectMatchingSnapshots:(xmlNodeSetPtr)nodeSet

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/WebDriverAgentTests/UnitTests/FBXPathTests.m

@@ -16,6 +16,33 @@
 #import "FBXCElementSnapshotWrapper+Helpers.h"
 #import "XCTestPrivateSymbols.h"
 
+// libxml's node callbacks are thread-local; restore any existing callbacks after each probe.
+static __thread NSUInteger FBReviewCreatedDocs;
+static __thread NSUInteger FBReviewFreedDocs;
+static __thread xmlRegisterNodeFunc FBReviewPreviousRegister;
+static __thread xmlDeregisterNodeFunc FBReviewPreviousDeregister;
+
+static void FBReviewRegisterNode(xmlNodePtr node)
+{
+  if (node->type == XML_DOCUMENT_NODE) { FBReviewCreatedDocs++; }
+  if (NULL != FBReviewPreviousRegister) { FBReviewPreviousRegister(node); }
+}
+
+static void FBReviewDeregisterNode(xmlNodePtr node)
+{
+  if (node->type == XML_DOCUMENT_NODE) { FBReviewFreedDocs++; }
+  if (NULL != FBReviewPreviousDeregister) { FBReviewPreviousDeregister(node); }
+}
+
+@interface FBThrowingLabelSnapshot : XCElementSnapshotDouble
+@end
+@implementation FBThrowingLabelSnapshot
+- (NSString *)label
+{
+  @throw [NSException exceptionWithName:@"SnapshotAttributeFailure" reason:@"test" userInfo:nil];
+}
+@end
+
 @interface FBTraversalSnapshot : XCElementSnapshotDouble
 @property (nonatomic, copy) NSArray *childSnapshots;
 @property (nonatomic, weak) FBTraversalSnapshot *parentSnapshot;
@@ -57,6 +84,44 @@
   }
 }
 
+- (void)testDirectXmlWriterPreservesEscapingAndFormatting
+{
+  XCElementSnapshotDouble *snapshot = [XCElementSnapshotDouble new];
+  snapshot.label = @"line one\nline two\t& < > \" йоло";
+  snapshot.value = @"value";
+  NSString *expected = [[self xmlStringWithElement:(id)snapshot xpathQuery:nil excludingAttributes:nil]
+    stringByReplacingOccurrencesOfString:@" private_indexPath=\"top\"" withString:@""];
+  NSString *actual = [FBXPath xmlStringWithRootElement:(id)snapshot options:nil];
+  XCTAssertEqualObjects(actual, expected);
+}
+
+- (void)testXmlDocumentsAreFreedWhenSnapshotAttributesThrow
+{
+  for (NSNumber *isLookup in @[@NO, @YES]) {
+    FBReviewCreatedDocs = 0;
+    FBReviewFreedDocs = 0;
+    FBReviewPreviousRegister = xmlRegisterNodeDefault(FBReviewRegisterNode);
+    FBReviewPreviousDeregister = xmlDeregisterNodeDefault(FBReviewDeregisterNode);
+    @try {
+      id<FBElement> snapshot = (id)[FBThrowingLabelSnapshot new];
+      if (isLookup.boolValue) {
+        XCTAssertThrowsSpecificNamed([FBXPath matchesWithRootElement:snapshot forQuery:@"//*[@label]"],
+                                     NSException, @"SnapshotAttributeFailure");
+      } else {
+        XCTAssertThrowsSpecificNamed([FBXPath xmlStringWithRootElement:snapshot options:nil],
+                                     NSException, @"SnapshotAttributeFailure");
+      }
+      if (isLookup.boolValue) {
+        XCTAssertGreaterThan(FBReviewCreatedDocs, 0u);
+      }
+      XCTAssertEqual(FBReviewCreatedDocs, FBReviewFreedDocs);
+    } @finally {
+      xmlRegisterNodeDefault(FBReviewPreviousRegister);
+      xmlDeregisterNodeDefault(FBReviewPreviousDeregister);
+    }
+  }
+}
+
 - (NSString *)xmlStringWithElement:(id<FBXCElementSnapshot>)snapshot
                         xpathQuery:(nullable NSString *)query
                excludingAttributes:(nullable NSArray<NSString *> *)excludedAttributes

package/package.json

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