@devicelab/maestro-runner-darwin-x64 1.1.25

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIDevice+FBHelpers.m

@@ -0,0 +1,388 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "XCUIDevice+FBHelpers.h"
+
+#import <arpa/inet.h>
+#import <ifaddrs.h>
+#include <notify.h>
+#import <objc/runtime.h>
+
+#import "FBErrorBuilder.h"
+#import "FBImageUtils.h"
+#import "FBMacros.h"
+#import "FBMathUtils.h"
+#import "FBScreenshot.h"
+#import "FBXCDeviceEvent.h"
+#import "FBXCodeCompatibility.h"
+#import "FBXCTestDaemonsProxy.h"
+#import "XCUIDevice.h"
+
+static const NSTimeInterval FBHomeButtonCoolOffTime = 1.;
+static const NSTimeInterval FBScreenLockTimeout = 5.;
+
+@implementation XCUIDevice (FBHelpers)
+
+static bool fb_isLocked;
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wobjc-load-method"
+
++ (void)load
+{
+  [self fb_registerAppforDetectLockState];
+}
+
+#pragma clang diagnostic pop
+
++ (void)fb_registerAppforDetectLockState
+{
+  int notify_token;
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wstrict-prototypes"
+  notify_register_dispatch("com.apple.springboard.lockstate", &notify_token, dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0), ^(int token) {
+    uint64_t state = UINT64_MAX;
+    notify_get_state(token, &state);
+    fb_isLocked = state != 0;
+  });
+#pragma clang diagnostic pop
+}
+
+- (BOOL)fb_goToHomescreenWithError:(NSError **)error
+{
+  return [XCUIApplication fb_switchToSystemApplicationWithError:error];
+}
+
+- (BOOL)fb_lockScreen:(NSError **)error
+{
+  if (fb_isLocked) {
+    return YES;
+  }
+  [self pressLockButton];
+  return [[[[FBRunLoopSpinner new]
+            timeout:FBScreenLockTimeout]
+           timeoutErrorMessage:@"Timed out while waiting until the screen gets locked"]
+          spinUntilTrue:^BOOL{
+            return fb_isLocked;
+          } error:error];
+}
+
+- (BOOL)fb_isScreenLocked
+{
+  return fb_isLocked;
+}
+
+- (BOOL)fb_unlockScreen:(NSError **)error
+{
+  if (!fb_isLocked) {
+    return YES;
+  }
+  [self pressButton:XCUIDeviceButtonHome];
+  [[NSRunLoop currentRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:FBHomeButtonCoolOffTime]];
+#if !TARGET_OS_TV
+  [self pressButton:XCUIDeviceButtonHome];
+#else
+  [self pressButton:XCUIDeviceButtonHome];
+#endif
+  [[NSRunLoop currentRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:FBHomeButtonCoolOffTime]];
+  return [[[[FBRunLoopSpinner new]
+            timeout:FBScreenLockTimeout]
+           timeoutErrorMessage:@"Timed out while waiting until the screen gets unlocked"]
+          spinUntilTrue:^BOOL{
+            return !fb_isLocked;
+          } error:error];
+}
+
+- (NSData *)fb_screenshotWithError:(NSError*__autoreleasing*)error
+{
+  return [FBScreenshot takeInOriginalResolutionWithQuality:FBConfiguration.screenshotQuality
+                                                     error:error];
+}
+
+- (BOOL)fb_fingerTouchShouldMatch:(BOOL)shouldMatch
+{
+  const char *name;
+  if (shouldMatch) {
+    name = "com.apple.BiometricKit_Sim.fingerTouch.match";
+  } else {
+    name = "com.apple.BiometricKit_Sim.fingerTouch.nomatch";
+  }
+  return notify_post(name) == NOTIFY_STATUS_OK;
+}
+
+- (NSString *)fb_wifiIPAddress
+{
+  struct ifaddrs *interfaces = NULL;
+  struct ifaddrs *temp_addr = NULL;
+  int success = getifaddrs(&interfaces);
+  if (success != 0) {
+    freeifaddrs(interfaces);
+    return nil;
+  }
+
+  NSString *address = nil;
+  temp_addr = interfaces;
+  while(temp_addr != NULL) {
+    if(temp_addr->ifa_addr->sa_family != AF_INET) {
+      temp_addr = temp_addr->ifa_next;
+      continue;
+    }
+    NSString *interfaceName = [NSString stringWithUTF8String:temp_addr->ifa_name];
+    if(![interfaceName isEqualToString:@"en0"]) {
+      temp_addr = temp_addr->ifa_next;
+      continue;
+    }
+    address = [NSString stringWithUTF8String:inet_ntoa(((struct sockaddr_in *)temp_addr->ifa_addr)->sin_addr)];
+    break;
+  }
+  freeifaddrs(interfaces);
+  return address;
+}
+
+- (BOOL)fb_openUrl:(NSString *)url error:(NSError **)error
+{
+  NSURL *parsedUrl = [NSURL URLWithString:url];
+  if (nil == parsedUrl) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"'%@' is not a valid URL", url]
+            buildError:error];
+  }
+
+  NSError *err;
+  if ([FBXCTestDaemonsProxy openDefaultApplicationForURL:parsedUrl error:&err]) {
+    return YES;
+  }
+  if (![err.description containsString:@"does not support"]) {
+    if (error) {
+      *error = err;
+    }
+    return NO;
+  }
+
+  id siriService = [self valueForKey:@"siriService"];
+  if (nil != siriService) {
+    return [self fb_activateSiriVoiceRecognitionWithText:[NSString stringWithFormat:@"Open {%@}", url] error:error];
+  }
+
+  NSString *description = [NSString stringWithFormat:@"Cannot open '%@' with the default application assigned for it. Consider upgrading to Xcode 14.3+/iOS 16.4+", url];
+  return [[[FBErrorBuilder builder]
+           withDescriptionFormat:@"%@", description]
+          buildError:error];;
+}
+
+- (BOOL)fb_openUrl:(NSString *)url withApplication:(NSString *)bundleId error:(NSError **)error
+{
+  NSURL *parsedUrl = [NSURL URLWithString:url];
+  if (nil == parsedUrl) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"'%@' is not a valid URL", url]
+            buildError:error];
+  }
+
+  return [FBXCTestDaemonsProxy openURL:parsedUrl usingApplication:bundleId error:error];
+}
+
+- (BOOL)fb_activateSiriVoiceRecognitionWithText:(NSString *)text error:(NSError **)error
+{
+  id siriService = [self valueForKey:@"siriService"];
+  if (nil == siriService) {
+    return [[[FBErrorBuilder builder]
+             withDescription:@"Siri service is not available on the device under test"]
+            buildError:error];
+  }
+  SEL selector = NSSelectorFromString(@"activateWithVoiceRecognitionText:");
+  NSMethodSignature *signature = [siriService methodSignatureForSelector:selector];
+  NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:signature];
+  [invocation setSelector:selector];
+  [invocation setArgument:&text atIndex:2];
+  @try {
+    [invocation invokeWithTarget:siriService];
+    return YES;
+  } @catch (NSException *e) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"%@", e.reason]
+            buildError:error];
+  }
+}
+
+- (BOOL)fb_pressButton:(NSString *)buttonName
+           forDuration:(nullable NSNumber *)duration
+                 error:(NSError **)error
+{
+#if !TARGET_OS_TV
+  return [self fb_pressButton:buttonName error:error];
+#else
+  NSMutableArray<NSString *> *supportedButtonNames = [NSMutableArray array];
+  NSInteger remoteButton = -1; // no remote button
+  if ([buttonName.lowercaseString isEqualToString:@"home"]) {
+    //  XCUIRemoteButtonHome        = 7
+    remoteButton = XCUIRemoteButtonHome;
+  }
+  [supportedButtonNames addObject:@"home"];
+
+  // https://developer.apple.com/design/human-interface-guidelines/tvos/remote-and-controllers/remote/
+  if ([buttonName.lowercaseString isEqualToString:@"up"]) {
+    //  XCUIRemoteButtonUp          = 0,
+    remoteButton = XCUIRemoteButtonUp;
+  }
+  [supportedButtonNames addObject:@"up"];
+
+  if ([buttonName.lowercaseString isEqualToString:@"down"]) {
+    //  XCUIRemoteButtonDown        = 1,
+    remoteButton = XCUIRemoteButtonDown;
+  }
+  [supportedButtonNames addObject:@"down"];
+
+  if ([buttonName.lowercaseString isEqualToString:@"left"]) {
+    //  XCUIRemoteButtonLeft        = 2,
+    remoteButton = XCUIRemoteButtonLeft;
+  }
+  [supportedButtonNames addObject:@"left"];
+
+  if ([buttonName.lowercaseString isEqualToString:@"right"]) {
+    //  XCUIRemoteButtonRight       = 3,
+    remoteButton = XCUIRemoteButtonRight;
+  }
+  [supportedButtonNames addObject:@"right"];
+
+  if ([buttonName.lowercaseString isEqualToString:@"menu"]) {
+    //  XCUIRemoteButtonMenu        = 5,
+    remoteButton = XCUIRemoteButtonMenu;
+  }
+  [supportedButtonNames addObject:@"menu"];
+
+  if ([buttonName.lowercaseString isEqualToString:@"playpause"]) {
+    //  XCUIRemoteButtonPlayPause   = 6,
+    remoteButton = XCUIRemoteButtonPlayPause;
+  }
+  [supportedButtonNames addObject:@"playpause"];
+
+  if ([buttonName.lowercaseString isEqualToString:@"select"]) {
+    //  XCUIRemoteButtonSelect      = 4,
+    remoteButton = XCUIRemoteButtonSelect;
+  }
+  [supportedButtonNames addObject:@"select"];
+
+  if (remoteButton == -1) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"The button '%@' is unknown. Only the following button names are supported: %@", buttonName, supportedButtonNames]
+            buildError:error];
+  }
+
+  if (duration) {
+    // https://developer.apple.com/documentation/xctest/xcuiremote/1627475-pressbutton
+    [[XCUIRemote sharedRemote] pressButton:remoteButton forDuration:duration.doubleValue];
+  } else {
+    // https://developer.apple.com/documentation/xctest/xcuiremote/1627476-pressbutton
+    [[XCUIRemote sharedRemote] pressButton:remoteButton];
+  }
+
+  return YES;
+#endif
+}
+
+#if !TARGET_OS_TV
+- (BOOL)fb_pressButton:(NSString *)buttonName
+                 error:(NSError **)error
+{
+  NSMutableArray<NSString *> *supportedButtonNames = [NSMutableArray array];
+  XCUIDeviceButton dstButton = 0;
+  if ([buttonName.lowercaseString isEqualToString:@"home"]) {
+    dstButton = XCUIDeviceButtonHome;
+  }
+  [supportedButtonNames addObject:@"home"];
+#if !TARGET_OS_SIMULATOR
+  if ([buttonName.lowercaseString isEqualToString:@"volumeup"]) {
+    dstButton = XCUIDeviceButtonVolumeUp;
+  }
+  if ([buttonName.lowercaseString isEqualToString:@"volumedown"]) {
+    dstButton = XCUIDeviceButtonVolumeDown;
+  }
+  [supportedButtonNames addObject:@"volumeUp"];
+  [supportedButtonNames addObject:@"volumeDown"];
+#endif
+
+  if (dstButton == 0) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"The button '%@' is unknown. Only the following button names are supported: %@", buttonName, supportedButtonNames]
+            buildError:error];
+  }
+  [self pressButton:dstButton];
+  return YES;
+}
+#endif
+
+- (BOOL)fb_performIOHIDEventWithPage:(unsigned int)page
+                               usage:(unsigned int)usage
+                            duration:(NSTimeInterval)duration
+                               error:(NSError **)error
+{
+  id<FBXCDeviceEvent> event = FBCreateXCDeviceEvent(page, usage, duration, error);
+  return nil == event ? NO : [self performDeviceEvent:event error:error];
+}
+
+- (BOOL)fb_setAppearance:(FBUIInterfaceAppearance)appearance error:(NSError **)error
+{
+  SEL selector = NSSelectorFromString(@"setAppearanceMode:");
+  if (nil != selector && [self respondsToSelector:selector]) {
+    NSMethodSignature *signature = [self methodSignatureForSelector:selector];
+    NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:signature];
+    [invocation setSelector:selector];
+    [invocation setTarget:self];
+    [invocation setArgument:&appearance atIndex:2];
+    [invocation invoke];
+    return YES;
+  }
+
+#if __clang_major__ >= 15 || (__clang_major__ >= 14 && __clang_minor__ >= 0 && __clang_patchlevel__ >= 3)
+  // Xcode 14.3.1 can build these values.
+  // For iOS 17+
+  if ([self respondsToSelector:NSSelectorFromString(@"appearance")]) {
+    self.appearance = (XCUIDeviceAppearance) appearance;
+    return YES;
+  }
+#endif
+
+  return [[[FBErrorBuilder builder]
+           withDescriptionFormat:@"Current Xcode SDK does not support appearance changing"]
+          buildError:error];
+}
+
+- (NSNumber *)fb_getAppearance
+{
+#if __clang_major__ >= 15 || (__clang_major__ >= 14 && __clang_minor__ >= 0 && __clang_patchlevel__ >= 3)
+  // Xcode 14.3.1 can build these values.
+  // For iOS 17+
+  if ([self respondsToSelector:NSSelectorFromString(@"appearance")]) {
+    return [NSNumber numberWithLongLong:[self appearance]];
+  }
+#endif
+
+  return [self respondsToSelector:@selector(appearanceMode)]
+  ? [NSNumber numberWithLongLong:[self appearanceMode]]
+  : nil;
+}
+
+#if !TARGET_OS_TV
+- (BOOL)fb_setSimulatedLocation:(CLLocation *)location error:(NSError **)error
+{
+  return [FBXCTestDaemonsProxy setSimulatedLocation:location error:error];
+}
+
+- (nullable CLLocation *)fb_getSimulatedLocation:(NSError **)error
+{
+  return [FBXCTestDaemonsProxy getSimulatedLocation:error];
+}
+
+- (BOOL)fb_clearSimulatedLocation:(NSError **)error
+{
+  return [FBXCTestDaemonsProxy clearSimulatedLocation:error];
+}
+#endif
+
+@end

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIDevice+FBRotation.h

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <XCTest/XCTest.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+#if !TARGET_OS_TV
+@interface XCUIDevice (FBRotation)
+
+/**
+ Sets requested device interface orientation.
+
+ @param orientation The interface orientation.
+ @return YES if the operation succeeds, otherwise NO.
+ */
+- (BOOL)fb_setDeviceInterfaceOrientation:(UIDeviceOrientation)orientation;
+
+/**
+ Sets the devices orientation to the rotation passed.
+ 
+ @param rotationObj The rotation defining the devices orientation.
+ @return YES if the operation succeeds, otherwise NO.
+ */
+- (BOOL)fb_setDeviceRotation:(NSDictionary *)rotationObj;
+
+/*! The UIDeviceOrientation to rotation mappings */
+@property (strong, nonatomic, readonly) NSDictionary *fb_rotationMapping;
+
+@end
+#endif
+
+NS_ASSUME_NONNULL_END

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIDevice+FBRotation.m

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "XCUIDevice+FBRotation.h"
+
+#import "FBConfiguration.h"
+#import "XCUIApplication.h"
+#import "XCUIApplication+FBHelpers.h"
+#import "XCUIElement+FBUtilities.h"
+
+# if !TARGET_OS_TV
+
+@implementation XCUIDevice (FBRotation)
+
+- (BOOL)fb_setDeviceInterfaceOrientation:(UIDeviceOrientation)orientation
+{
+  XCUIApplication *application = XCUIApplication.fb_activeApplication;
+  [XCUIDevice sharedDevice].orientation = orientation;
+  return [self waitUntilInterfaceIsAtOrientation:orientation application:application];
+}
+
+- (BOOL)fb_setDeviceRotation:(NSDictionary *)rotationObj
+{
+  NSArray<NSNumber *> *keysForRotationObj = [self.fb_rotationMapping allKeysForObject:rotationObj];
+  if (keysForRotationObj.count == 0) {
+    return NO;
+  }
+  NSInteger orientation = keysForRotationObj.firstObject.integerValue;
+  XCUIApplication *application = XCUIApplication.fb_activeApplication;
+  [XCUIDevice sharedDevice].orientation = orientation;
+  return [self waitUntilInterfaceIsAtOrientation:orientation application:application];
+}
+
+- (BOOL)waitUntilInterfaceIsAtOrientation:(NSInteger)orientation application:(XCUIApplication *)application
+{
+  // Tapping elements immediately after rotation may fail due to way UIKit is handling touches.
+  // We should wait till UI cools off, before continuing
+  [application fb_waitUntilStableWithTimeout:FBConfiguration.animationCoolOffTimeout];
+
+  return application.interfaceOrientation == orientation;
+}
+
+- (NSDictionary *)fb_rotationMapping
+{
+    static NSDictionary *rotationMap;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        rotationMap =
+        @{
+          @(UIDeviceOrientationUnknown) : @{@"x" : @(-1), @"y" : @(-1), @"z" : @(-1)},
+          @(UIDeviceOrientationPortrait) : @{@"x" : @(0), @"y" : @(0), @"z" : @(0)},
+          @(UIDeviceOrientationPortraitUpsideDown) : @{@"x" : @(0), @"y" : @(0), @"z" : @(180)},
+          @(UIDeviceOrientationLandscapeLeft) : @{@"x" : @(0), @"y" : @(0), @"z" : @(270)},
+          @(UIDeviceOrientationLandscapeRight) : @{@"x" : @(0), @"y" : @(0), @"z" : @(90)},
+          @(UIDeviceOrientationFaceUp) : @{@"x" : @(90), @"y" : @(0), @"z" : @(0)},
+          @(UIDeviceOrientationFaceDown) : @{@"x" : @(270), @"y" : @(0), @"z" : @(0)},
+          };
+    });
+    return rotationMap;
+}
+
+@end
+#endif

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIElement+FBAccessibility.h

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <WebDriverAgentLib/XCUIElement.h>
+#import <WebDriverAgentLib/FBXCElementSnapshotWrapper.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface XCUIElement (FBAccessibility)
+
+/*! Whether or not the element is accessible */
+@property (atomic, readonly) BOOL fb_isAccessibilityElement;
+
+@end
+
+
+@interface FBXCElementSnapshotWrapper (FBAccessibility)
+
+/*! Whether or not the element in snapshot is accessible */
+@property (atomic, readonly) BOOL fb_isAccessibilityElement;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIElement+FBAccessibility.m

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "XCUIElement+FBAccessibility.h"
+
+#import "FBConfiguration.h"
+#import "XCTestPrivateSymbols.h"
+#import "XCUIElement+FBUtilities.h"
+#import "FBXCElementSnapshotWrapper+Helpers.h"
+
+@implementation XCUIElement (FBAccessibility)
+
+- (BOOL)fb_isAccessibilityElement
+{
+  id<FBXCElementSnapshot> snapshot = [self fb_standardSnapshot];
+  return [FBXCElementSnapshotWrapper ensureWrapped:snapshot].fb_isAccessibilityElement;
+}
+
+@end
+
+@implementation FBXCElementSnapshotWrapper (FBAccessibility)
+
+- (BOOL)fb_isAccessibilityElement
+{
+  NSNumber *isAccessibilityElement = self.additionalAttributes[FB_XCAXAIsElementAttribute];
+  if (nil != isAccessibilityElement) {
+    return isAccessibilityElement.boolValue;
+  }
+
+  NSError *error;
+  NSNumber *attributeValue = [self fb_attributeValue:FB_XCAXAIsElementAttributeName
+                                               error:&error];
+  if (nil != attributeValue) {
+    NSMutableDictionary *updatedValue = [NSMutableDictionary dictionaryWithDictionary:self.additionalAttributes ?: @{}];
+    [updatedValue setObject:attributeValue forKey:FB_XCAXAIsElementAttribute];
+    self.snapshot.additionalAttributes = updatedValue.copy;
+    return [attributeValue boolValue];
+  }
+
+  NSLog(@"Cannot determine accessibility of '%@' natively: %@. Defaulting to: %@",
+        self.fb_description, error.description, @(NO));
+  return NO;
+}
+
+@end

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIElement+FBCaching.h

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <XCTest/XCTest.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface XCUIElement (FBCaching)
+
+@property (nonatomic, readonly) NSString *fb_cacheId;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIElement+FBCaching.m

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "XCUIElement+FBCaching.h"
+
+#import <objc/runtime.h>
+
+#import "FBXCElementSnapshotWrapper+Helpers.h"
+#import "XCUIElement+FBWebDriverAttributes.h"
+#import "XCUIElement+FBUtilities.h"
+#import "XCUIElement+FBUID.h"
+
+@implementation XCUIElement (FBCaching)
+
+static char XCUIELEMENT_CACHE_ID_KEY;
+
+@dynamic fb_cacheId;
+
+- (NSString *)fb_cacheId
+{
+  id result = objc_getAssociatedObject(self, &XCUIELEMENT_CACHE_ID_KEY);
+  if ([result isKindOfClass:NSString.class]) {
+    return (NSString *)result;
+  }
+
+  NSString *uid = self.fb_uid;
+  objc_setAssociatedObject(self, &XCUIELEMENT_CACHE_ID_KEY, uid, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+  return uid;
+}
+
+@end

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIElement+FBClassChain.h

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <XCTest/XCTest.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface XCUIElement (FBClassChain)
+
+/**
+ Returns an array of descendants matching given class chain query.
+ This query is similar to xpath, but can only include indexes, predicates and valid class names. Search by direct children and descendant elements is supported. Examples of direct search requests:
+ XCUIElementTypeWindow/XCUIElementTypeButton[3] - select the third child button of the first child window element.
+ XCUIElementTypeWindow - select all the children windows.
+ XCUIElementTypeWindow[2] - select the second child window in the hierarchy. Indexing starts at 1.
+ XCUIElementTypeWindow/XCUIElementTypeAny[3] - select the third child (of any type) of the first child. window
+ XCUIElementTypeWindow[2]/XCUIElementTypeAny - select all the children of the second child window.
+ XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2] - select the second last child of the second child window.
+ One may use '*' (star) character to substitute the universal 'XCUIElementTypeAny' class name.
+ XCUIElementTypeWindow[`name CONTAINS[cd] "blabla"`] - select all windows, where name attribute starts with "blabla" or "BlAbla".
+ XCUIElementTypeWindow[`label BEGINSWITH "blabla"`][-1] - select the last window, where label text begins with "blabla".
+ XCUIElementTypeWindow/XCUIElementTypeAny[`value == "bla1" OR label == "bla2"`] - select all children of the first window, where value is "bla1" or label is "bla2".
+ XCUIElementTypeWindow[`name == "you're the winner"`]/XCUIElementTypeAny[`visible == 1`] - select all visible children of the first window named "you're the winner".
+ XCUIElementTypeWindow/XCUIElementTypeTable/XCUIElementTypeCell[`visible == 1`][$type == XCUIElementTypeImage AND name == 'bla'$]/XCUIElementTypeTextField - select a text field, which is a direct child of a visible table cell, which has at least one descendant image with identifier 'bla'.
+ Predicate string should be always enclosed into ` or $ characters inside square brackets. Use `` or $$ to escape a single ` or $ character inside predicate expression.
+ Single backtick means the predicate expression is applied to the current children. It is the direct alternative of matchingPredicate: query selector.
+ Single dollar sign means the predicate expression is applied to all the descendants of the current element(s). It is the direct alternative of containingPredicate: query selector.
+ Predicate expression should be always put before the index, but never after it. All predicate expressions are executed in the same exact order, which is set in the chain query.
+ It is not recommended to set explicit indexes for intermediate chain elements, because it slows down the lookup speed.
+ 
+ Indirect descendant search requests are pretty similar to requests above:
+ ** /XCUIElementTypeCell[`name BEGINSWITH "A"`][-1]/XCUIElementTypeButton[10] - select the 10-th child button of the very last cell in the tree, whose name starts with 'A'.
+ ** /XCUIElementTypeCell[`name BEGINSWITH "B"`] - select all cells in the tree, where name starts with 'B'
+ ** /XCUIElementTypeCell[`name BEGINSWITH "C"`]/XCUIElementTypeButton[10] - select the 10-th child button of the first cell in the tree, whose name starts with 'C' and which has at least ten direct children of type XCUIElementTypeButton.
+ ** /XCUIElementTypeCell[`name BEGINSWITH "D"`]/ ** /XCUIElementTypeButton - select the all descendant buttons of the first cell in the tree, whose name starts with 'D'.
+
+ Double star and slash is the marker of the fact, that the next following item is the descendant of the previous chain item, rather than its child.
+ 
+ The matching result is similar to what XCTest's children... and descendants... selector calls of XCUIElement class instances produce when combined into a chain.
+ 
+ @param classChainQuery valid class chain query string
+ @param shouldReturnAfterFirstMatch set it to YES if you want only the first found element to be resolved and returned. 
+   This will speed up the search significantly if the given chain matches multiple nodes in the UI tree
+ @return an array of descendants matching given class chain
+ @throws FBUnknownAttributeException if any of predicates in the chain contains unknown attribute(s)
+ */
+- (NSArray<XCUIElement *> *)fb_descendantsMatchingClassChain:(NSString *)classChainQuery
+                                 shouldReturnAfterFirstMatch:(BOOL)shouldReturnAfterFirstMatch;
+
+@end
+
+NS_ASSUME_NONNULL_END