feat: Add 'limitXpathContextScope' setting

WebDriverAgentLib/Commands/FBSessionCommands.m

@@ -351,6 +351,7 @@ + (NSArray *)routes
       FB_SETTING_MAX_TYPING_FREQUENCY: @([FBConfiguration maxTypingFrequency]),
       FB_SETTING_RESPECT_SYSTEM_ALERTS: @([FBConfiguration shouldRespectSystemAlerts]),
       FB_SETTING_USE_CLEAR_TEXT_SHORTCUT: @([FBConfiguration useClearTextShortcut]),
+      FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE: @([FBConfiguration limitXpathContextScope]),
 #if !TARGET_OS_TV
       FB_SETTING_SCREENSHOT_ORIENTATION: [FBConfiguration humanReadableScreenshotOrientation],
 #endif
@@ -445,6 +446,9 @@ + (NSArray *)routes
   if (nil != [settings objectForKey:FB_SETTING_USE_CLEAR_TEXT_SHORTCUT]) {
     [FBConfiguration setUseClearTextShortcut:[[settings objectForKey:FB_SETTING_USE_CLEAR_TEXT_SHORTCUT] boolValue]];
   }
+  if (nil != [settings objectForKey:FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE]) {
+    [FBConfiguration setLimitXpathContextScope:[[settings objectForKey:FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE] boolValue]];
+  }
 
 #if !TARGET_OS_TV
   if (nil != [settings objectForKey:FB_SETTING_SCREENSHOT_ORIENTATION]) {

WebDriverAgentLib/Utilities/FBConfiguration.h

@@ -103,6 +103,14 @@ extern NSString *const FBSnapshotMaxDepthKey;
 + (NSUInteger)mjpegServerFramerate;
 + (void)setMjpegServerFramerate:(NSUInteger)framerate;
 
+/**
+ Whether to limit the XPath scope to descendant items only while performing a lookup
+ in an element context. Enabled by default. Being disabled, allows to use XPath locators
+ like ".." in order to match parent items of the current context root.
+ */
++ (BOOL)limitXpathContextScope;
++ (void)setLimitXpathContextScope:(BOOL)enabled;
+
 /**
  The quality of display screenshots. The higher quality you set is the bigger screenshot size is.
  The highest quality value is 0 (lossless PNG) or 3 (lossless HEIC). The lowest quality is 2 (highly compressed JPEG).

WebDriverAgentLib/Utilities/FBConfiguration.m

@@ -56,6 +56,7 @@
 static BOOL FBShouldUseCompactResponses;
 static NSString *FBElementResponseAttributes;
 static BOOL FBUseClearTextShortcut;
+static BOOL FBLimitXpathContextScope = YES;
 #if !TARGET_OS_TV
 static UIInterfaceOrientation FBScreenshotOrientation;
 #endif
@@ -438,6 +439,16 @@ + (BOOL)useClearTextShortcut
   return FBUseClearTextShortcut;
 }
 
++ (BOOL)limitXpathContextScope
+{
+  return FBLimitXpathContextScope;
+}
+
++ (void)setLimitXpathContextScope:(BOOL)enabled
+{
+  FBLimitXpathContextScope = enabled;
+}
+
 #if !TARGET_OS_TV
 + (BOOL)setScreenshotOrientation:(NSString *)orientation error:(NSError **)error
 {
@@ -503,6 +514,7 @@ + (void)resetSessionSettings
   // 50 should be enough for the majority of the cases. The performance is acceptable for values up to 100.
   FBSetCustomParameterForElementSnapshot(FBSnapshotMaxDepthKey, @50);
   FBUseClearTextShortcut = YES;
+  FBLimitXpathContextScope = YES;
 #if !TARGET_OS_TV
   FBScreenshotOrientation = UIInterfaceOrientationUnknown;
 #endif

WebDriverAgentLib/Utilities/FBSettings.h

@@ -38,6 +38,7 @@ extern NSString* const FB_SETTING_ANIMATION_COOL_OFF_TIMEOUT;
 extern NSString* const FB_SETTING_MAX_TYPING_FREQUENCY;
 extern NSString* const FB_SETTING_RESPECT_SYSTEM_ALERTS;
 extern NSString* const FB_SETTING_USE_CLEAR_TEXT_SHORTCUT;
+extern NSString* const FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE;
 
 
 NS_ASSUME_NONNULL_END

WebDriverAgentLib/Utilities/FBSettings.m

@@ -34,3 +34,4 @@
 NSString* const FB_SETTING_MAX_TYPING_FREQUENCY = @"maxTypingFrequency";
 NSString* const FB_SETTING_RESPECT_SYSTEM_ALERTS = @"respectSystemAlerts";
 NSString* const FB_SETTING_USE_CLEAR_TEXT_SHORTCUT = @"useClearTextShortcut";
+NSString* const FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE = @"limitXpathContextScope";

WebDriverAgentLib/Utilities/FBXPath-Private.h

@@ -25,7 +25,7 @@ NS_ASSUME_NONNULL_BEGIN
  If `query` argument is assigned then `excludedAttributes` argument is effectively ignored.
  @return zero if the method has completed successfully
  */
-+ (int)xmlRepresentationWithRootElement:(id<FBElement>)root
++ (int)xmlRepresentationWithRootElement:(id<FBXCElementSnapshot>)root
                                  writer:(xmlTextWriterPtr)writer
                            elementStore:(nullable NSMutableDictionary *)elementStore
                                   query:(nullable NSString*)query
@@ -45,9 +45,12 @@ NS_ASSUME_NONNULL_BEGIN
 
  @param xpathQuery actual query. Should be valid XPath 1.0-compatible expression
  @param document libxml2-compatible document pointer
+ @param contextNode Optonal context node instance
  @return pointer to a libxml2-compatible structure with set of matched nodes or NULL in case of failure
  */
-+ (xmlXPathObjectPtr)evaluate:(NSString *)xpathQuery document:(xmlDocPtr)doc;
++ (xmlXPathObjectPtr)evaluate:(NSString *)xpathQuery
+                     document:(xmlDocPtr)doc
+                  contextNode:(nullable xmlNodePtr)contextNode;
 
 @end
 

WebDriverAgentLib/Utilities/FBXPath.m

@@ -11,6 +11,7 @@
 
 #import "FBConfiguration.h"
 #import "FBExceptions.h"
+#import "FBElementUtils.h"
 #import "FBLogger.h"
 #import "FBMacros.h"
 #import "FBXMLGenerationOptions.h"
@@ -145,7 +146,7 @@ + (nullable NSString *)xmlStringWithRootElement:(id<FBElement>)root
     }
 
     if (rc >= 0) {
-      rc = [self xmlRepresentationWithRootElement:root
+      rc = [self xmlRepresentationWithRootElement:[self snapshotWithRoot:root]
                                            writer:writer
                                      elementStore:nil
                                             query:nil
@@ -193,10 +194,29 @@ + (nullable NSString *)xmlStringWithRootElement:(id<FBElement>)root
   }
   NSMutableDictionary *elementStore = [NSMutableDictionary dictionary];
   int rc = xmlTextWriterStartDocument(writer, NULL, _UTF8Encoding, NULL);
+  id<FBXCElementSnapshot> lookupScopeSnapshot = nil;
+  id<FBXCElementSnapshot> contextRootSnapshot = nil;
   if (rc < 0) {
     [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterStartDocument. Error code: %d", rc];
   } else {
-    rc = [self xmlRepresentationWithRootElement:root
+    if (FBConfiguration.limitXpathContextScope) {
+      lookupScopeSnapshot = [self snapshotWithRoot:root];
+    } else {
+      if ([root isKindOfClass:XCUIElement.class]) {
+        lookupScopeSnapshot = [self snapshotWithRoot:[(XCUIElement *)root application]];
+        contextRootSnapshot = [root isKindOfClass:XCUIApplication.class]
+          ? nil
+          : [(XCUIElement *)root fb_takeSnapshot:YES];
+      } 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
@@ -214,7 +234,22 @@ + (nullable NSString *)xmlStringWithRootElement:(id<FBElement>)root
     return [self throwException:FBXPathQueryEvaluationException forQuery:xpathQuery];
   }
 
-  xmlXPathObjectPtr queryResult = [self evaluate:xpathQuery document:doc];
+  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];
+    }
+  }
+  xmlXPathObjectPtr queryResult = [self evaluate:xpathQuery
+                                        document:doc
+                                     contextNode:contextNode];
+  if (NULL != contextNodeQueryResult) {
+    xmlXPathFreeObject(contextNodeQueryResult);
+  }
   if (NULL == queryResult) {
     xmlFreeTextWriter(writer);
     xmlFreeDoc(doc);
@@ -256,6 +291,36 @@ + (NSArray *)collectMatchingSnapshots:(xmlNodeSetPtr)nodeSet
   return matchingSnapshots.copy;
 }
 
++ (nullable xmlXPathObjectPtr)matchNodeInDocument:(xmlDocPtr)doc
+                                     elementStore:(NSDictionary<NSString *, id<FBXCElementSnapshot>> *)elementStore
+                                      forSnapshot:(nullable id<FBXCElementSnapshot>)snapshot
+{
+  if (nil == snapshot) {
+    return NULL;
+  }
+
+  NSString *contextRootUid = [FBElementUtils uidWithAccessibilityElement:[(id)snapshot accessibilityElement]];
+  if (nil == contextRootUid) {
+    return NULL;
+  }
+
+  for (NSString *key in elementStore) {
+    id<FBXCElementSnapshot> value = [elementStore objectForKey:key];
+    NSString *snapshotUid = [FBElementUtils uidWithAccessibilityElement:[value accessibilityElement]];
+    if (nil == snapshotUid || ![snapshotUid isEqualToString:contextRootUid]) {
+      continue;
+    }
+    NSString *indexQuery = [NSString stringWithFormat:@"//*[@%@=\"%@\"]", kXMLIndexPathKey, key];
+    xmlXPathObjectPtr queryResult = [self evaluate:indexQuery
+                                          document:doc
+                                       contextNode:NULL];
+    if (NULL != queryResult) {
+      return queryResult;
+    }
+  }
+  return NULL;
+}
+
 + (NSSet<Class> *)elementAttributesWithXPathQuery:(NSString *)query
 {
   if ([query rangeOfString:@"[^\\w@]@\\*[^\\w]" options:NSRegularExpressionSearch].location != NSNotFound) {
@@ -271,7 +336,7 @@ + (NSArray *)collectMatchingSnapshots:(xmlNodeSetPtr)nodeSet
   return result.copy;
 }
 
-+ (int)xmlRepresentationWithRootElement:(id<FBElement>)root
++ (int)xmlRepresentationWithRootElement:(id<FBXCElementSnapshot>)root
                                  writer:(xmlTextWriterPtr)writer
                            elementStore:(nullable NSMutableDictionary *)elementStore
                                   query:(nullable NSString*)query
@@ -312,14 +377,16 @@ + (int)xmlRepresentationWithRootElement:(id<FBElement>)root
   return 0;
 }
 
-+ (xmlXPathObjectPtr)evaluate:(NSString *)xpathQuery document:(xmlDocPtr)doc
++ (xmlXPathObjectPtr)evaluate:(NSString *)xpathQuery
+                     document:(xmlDocPtr)doc
+                  contextNode:(nullable xmlNodePtr)contextNode
 {
   xmlXPathContextPtr xpathCtx = xmlXPathNewContext(doc);
   if (NULL == xpathCtx) {
     [FBLogger logFmt:@"Failed to invoke libxml2>xmlXPathNewContext for XPath query \"%@\"", xpathQuery];
     return NULL;
   }
-  xpathCtx->node = doc->children;
+  xpathCtx->node = NULL == contextNode ? doc->children : contextNode;
 
   xmlXPathObjectPtr xpathObj = xmlXPathEvalExpression((const xmlChar *)[xpathQuery UTF8String], xpathCtx);
   if (NULL == xpathObj) {
@@ -360,45 +427,29 @@ + (int)recordElementAttributes:(xmlTextWriterPtr)writer
   return 0;
 }
 
-+ (int)writeXmlWithRootElement:(id<FBElement>)root
++ (int)writeXmlWithRootElement:(id<FBXCElementSnapshot>)root
                      indexPath:(nullable NSString *)indexPath
                   elementStore:(nullable NSMutableDictionary *)elementStore
             includedAttributes:(nullable NSSet<Class> *)includedAttributes
                         writer:(xmlTextWriterPtr)writer
 {
   NSAssert((indexPath == nil && elementStore == nil) || (indexPath != nil && elementStore != nil), @"Either both or none of indexPath and elementStore arguments should be equal to nil", nil);
 
-  __block id<FBXCElementSnapshot> currentSnapshot;
-  NSArray<id<FBXCElementSnapshot>> *children;
-  if ([root isKindOfClass:XCUIElement.class]) {
-    XCUIElement *element = (XCUIElement *)root;
-    if (nil == includedAttributes || [includedAttributes containsObject:FBVisibleAttribute.class]) {
-      // If the app is not idle state while we retrieve the visiblity state
-      // then the snapshot retrieval operation might freeze and time out
-      [element.application fb_waitUntilStableWithTimeout:FBConfiguration.animationCoolOffTimeout];
-    }
-    @autoreleasepool {
-      currentSnapshot = [element fb_takeSnapshot:YES];
-    }
-    children = currentSnapshot.children;
-  } else {
-    currentSnapshot = (id<FBXCElementSnapshot>)root;
-    children = currentSnapshot.children;
-  }
+  NSArray<id<FBXCElementSnapshot>> *children = root.children;
 
   if (elementStore != nil && indexPath != nil && [indexPath isEqualToString:topNodeIndexPath]) {
-    [elementStore setObject:currentSnapshot forKey:topNodeIndexPath];
+    [elementStore setObject:root forKey:topNodeIndexPath];
   }
 
-  FBXCElementSnapshotWrapper *wrappedSnapshot = [FBXCElementSnapshotWrapper ensureWrapped:currentSnapshot];
+  FBXCElementSnapshotWrapper *wrappedSnapshot = [FBXCElementSnapshotWrapper ensureWrapped:root];
   int rc = xmlTextWriterStartElement(writer, (xmlChar *)[wrappedSnapshot.wdType UTF8String]);
   if (rc < 0) {
     [FBLogger logFmt:@"Failed to invoke libxml2>xmlTextWriterStartElement for the tag value '%@'. Error code: %d", wrappedSnapshot.wdType, rc];
     return rc;
   }
 
   rc = [self recordElementAttributes:writer
-                          forElement:currentSnapshot
+                          forElement:root
                            indexPath:indexPath
                   includedAttributes:includedAttributes];
   if (rc < 0) {
@@ -431,6 +482,20 @@ + (int)writeXmlWithRootElement:(id<FBElement>)root
   return 0;
 }
 
++ (id<FBXCElementSnapshot>)snapshotWithRoot:(id<FBElement>)root
+{
+  if (![root isKindOfClass:XCUIElement.class]) {
+    return (id<FBXCElementSnapshot>)root;
+  }
+
+  // If the app is not idle state while we retrieve the visiblity state
+  // then the snapshot retrieval operation might freeze and time out
+  [[(XCUIElement *)root application] fb_waitUntilStableWithTimeout:FBConfiguration.animationCoolOffTimeout];
+  @autoreleasepool {
+    return [(XCUIElement *)root fb_takeSnapshot:YES];
+  }
+}
+
 @end
 
 

WebDriverAgentTests/IntegrationTests/FBXPathIntegrationTests.m

@@ -96,6 +96,29 @@ - (void)testFindMatchesInElement
   }
 }
 
+- (void)testFindMatchesWithoutContextScopeLimit
+{
+  XCUIElement *button = self.testedApplication.buttons.firstMatch;
+  BOOL previousValue = FBConfiguration.limitXpathContextScope;
+  FBConfiguration.limitXpathContextScope = NO;
+  @try {
+    NSArray *parentSnapshots = [FBXPath matchesWithRootElement:button forQuery:@".."];
+    XCTAssertEqual(parentSnapshots.count, 1);
+    XCTAssertEqualObjects(
+                          [FBXCElementSnapshotWrapper ensureWrapped:[parentSnapshots objectAtIndex:0]].wdLabel,
+                          @"MainView"
+                          );
+    NSArray *currentSnapshots = [FBXPath matchesWithRootElement:button forQuery:@"."];
+    XCTAssertEqual(currentSnapshots.count, 1);
+    XCTAssertEqualObjects(
+                          [FBXCElementSnapshotWrapper ensureWrapped:[currentSnapshots objectAtIndex:0]].wdType,
+                          @"XCUIElementTypeButton"
+                          );
+  } @finally {
+    FBConfiguration.limitXpathContextScope = previousValue;
+  }
+}
+
 - (void)testFindMatchesInElementWithDotNotation
 {
   NSArray<id<FBXCElementSnapshot>> *matchingSnapshots = [FBXPath matchesWithRootElement:self.testedApplication forQuery:@".//XCUIElementTypeButton"];