@devicelab/maestro-runner-darwin-arm64 1.1.29 → 1.1.30

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBHIDOperations.h

@@ -0,0 +1,41 @@
+/**
+ * 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>
+#import <UIKit/UIKit.h>
+
+/**
+ HID paths for Home, lock/unlock, and rotation on hinged iOS devices.
+
+ Remove each workaround once its XCTest-only path passes the corresponding regression
+ test on supported runtimes and both panels: testHomeButtonBackgroundsApplication,
+ testRepeatedLockUnlockAcrossHingePoses, and testRotationOnSelectedDuoDisplay.
+ Physical-device Home, lock/unlock, and rotation behavior require verification.
+
+ Once all paths are obsolete, remove the FBHIDOperations branches and imports from
+ XCUIDevice+FBHelpers.m and XCUIDevice+FBRotation.m, then delete this module and its
+ Xcode project entries. Hinge control in XCUIDevice+FBHinge is independent.
+
+ Tracking: https://github.com/appium/appium/issues/22857
+ Rotation: https://github.com/appium/appium-ios/pull/81
+ */
+@interface FBHIDOperations : NSObject
+
+// All operations apply to hinged iOS devices, including physical devices.
++ (BOOL)appliesToDevice:(XCUIDevice *)device;
+
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+// Call only after the corresponding applicability check succeeds.
++ (BOOL)pressHomeWithError:(NSError **)error;
++ (BOOL)pressLockWithError:(NSError **)error;
+// interfaceOrientation is the UIKit equivalent of the requested device orientation.
++ (BOOL)rotateToOrientation:(UIDeviceOrientation)orientation
+     interfaceOrientation:(UIInterfaceOrientation)interfaceOrientation;
+#endif
+
+@end

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBHIDOperations.m

@@ -0,0 +1,244 @@
+/**
+ * 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 "FBHIDOperations.h"
+
+#import <dlfcn.h>
+#import <mach/mach_time.h>
+
+#import "FBConfiguration.h"
+#import "FBErrorBuilder.h"
+#import "FBLogger.h"
+#import "FBRunLoopSpinner.h"
+#import "FBScreen.h"
+#import "FBSession.h"
+#import "XCUIScreen.h"
+#import "XCUIDevice+FBHinge.h"
+#import "XCUIApplication.h"
+#import "XCUIApplication+FBHelpers.h"
+#import "XCUIElement+FBUtilities.h"
+
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+
+static const uint32_t FBHIDConsumerUsagePage = 0x0C;
+static const uint32_t FBHIDHomeUsage = 0x40;
+static const uint32_t FBHIDPowerUsage = 0x30;
+static const uint32_t FBHIDOrientationUsagePage = 0xff61;
+static const uint32_t FBHIDOrientationUsage = 0x5b;
+static const CFOptionFlags FBHIDBinarySerialization = 1;
+static const NSTimeInterval FBHIDButtonPressDuration = 0.03;
+static const NSTimeInterval FBHIDRotationTimeout = 5.0;
+
+typedef struct {
+  CFTypeRef (*createKeyboardEvent)(CFAllocatorRef, uint64_t, uint32_t, uint32_t, Boolean, uint32_t);
+  CFTypeRef (*createVendorEvent)(CFAllocatorRef, uint64_t, uint32_t, uint32_t,
+                               uint32_t, uint8_t *, CFIndex, uint32_t);
+  CFTypeRef (*createClient)(CFAllocatorRef);
+  void (*dispatchEvent)(CFTypeRef, CFTypeRef);
+  void (*setTimestamp)(CFTypeRef, uint64_t);
+  CFDataRef (*serialize)(CFTypeRef, CFOptionFlags);
+} FBHIDAPI;
+
+static const FBHIDAPI *FBGetHIDAPI(void)
+{
+  static FBHIDAPI api;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    // Keep the framework loaded for the lifetime of the cached function pointers.
+    void *handle = dlopen("/System/Library/Frameworks/IOKit.framework/IOKit", RTLD_LAZY);
+    if (NULL == handle) {
+      return;
+    }
+    api.createKeyboardEvent = (CFTypeRef (*)(CFAllocatorRef, uint64_t, uint32_t, uint32_t, Boolean, uint32_t))
+      dlsym(handle, "IOHIDEventCreateKeyboardEvent");
+    api.createVendorEvent = (CFTypeRef (*)(CFAllocatorRef, uint64_t, uint32_t, uint32_t,
+                                         uint32_t, uint8_t *, CFIndex, uint32_t))
+      dlsym(handle, "IOHIDEventCreateVendorDefinedEvent");
+    api.createClient = (CFTypeRef (*)(CFAllocatorRef))dlsym(handle, "IOHIDEventSystemClientCreate");
+    api.dispatchEvent = (void (*)(CFTypeRef, CFTypeRef))dlsym(handle, "IOHIDEventSystemClientDispatchEvent");
+    api.setTimestamp = (void (*)(CFTypeRef, uint64_t))dlsym(handle, "IOHIDEventSetTimeStamp");
+    api.serialize = (CFDataRef (*)(CFTypeRef, CFOptionFlags))dlsym(handle, "IOCFSerialize");
+  });
+  // Each operation checks only the symbols it needs.
+  return &api;
+}
+
+static void FBLogUnverifiedPhysicalHIDOperation(NSString *operation)
+{
+#if !TARGET_OS_SIMULATOR
+  [FBLogger logFmt:@"HID %@ on physical hinged devices: not verified yet.", operation];
+#endif
+}
+
+static BOOL FBWaitForStableInterfaceOrientation(XCUIApplication *application,
+                                               UIInterfaceOrientation orientation)
+{
+  [application fb_waitUntilStableWithTimeout:FBConfiguration.sharedInstance.animationCoolOffTimeout];
+  return application.interfaceOrientation == orientation;
+}
+
+// Workaround tracked in https://github.com/appium/appium/issues/22857.
+// Reproduced on the iOS 27.1 Duo simulator with Xcode 27.1: XCTest's Home
+// request returns without backgrounding the app. This direct HID path is also
+// enabled on physical hinged devices, but Home behavior there is unverified.
+// The affected Xcode/runtime version range has not been established. Remove
+// the Home workaround when XCTest-only presses pass testHomeButtonBackgroundsApplication
+// on supported Duo environments, including physical devices and both panels.
+static BOOL FBPressHIDButton(uint32_t usage, NSError **error)
+{
+  const FBHIDAPI *api = FBGetHIDAPI();
+  if (NULL == api->createKeyboardEvent || NULL == api->createClient
+      || NULL == api->dispatchEvent || NULL == api->setTimestamp) {
+    return [[FBErrorBuilder.builder withDescription:@"The button HID APIs are unavailable"] buildError:error];
+  }
+  CFTypeRef client = api->createClient(kCFAllocatorDefault);
+  CFTypeRef down = api->createKeyboardEvent(kCFAllocatorDefault, mach_absolute_time(),
+                                           FBHIDConsumerUsagePage, usage, YES, 0);
+  CFTypeRef up = api->createKeyboardEvent(kCFAllocatorDefault, mach_absolute_time(),
+                                           FBHIDConsumerUsagePage, usage, NO, 0);
+  BOOL ready = NULL != client && NULL != down && NULL != up;
+  if (ready) {
+    // Dispatch a short paired press. Holding Power for 0.5s invokes Siri on Duo.
+    api->dispatchEvent(client, down);
+    [NSThread sleepForTimeInterval:FBHIDButtonPressDuration];
+    api->setTimestamp(up, mach_absolute_time());
+    api->dispatchEvent(client, up);
+  }
+  if (NULL != down) {
+    CFRelease(down);
+  }
+  if (NULL != up) {
+    CFRelease(up);
+  }
+  if (NULL != client) {
+    CFRelease(client);
+  }
+  return ready || [[FBErrorBuilder.builder
+                    withDescription:@"Cannot create the button HID event or client"] buildError:error];
+}
+
+// Work around XCTest updating Duo device orientation without rotating the app.
+// Reproduction details and checks required before removing this workaround:
+// https://github.com/appium/appium-ios/pull/81
+static BOOL FBDispatchHIDOrientation(UIDeviceOrientation orientation)
+{
+  XCUIScreen *screen = [FBScreen currentScreenWithError:nil];
+  if (nil == screen) {
+    return NO;
+  }
+  // The inner panel's native orientation is a quarter turn from the cover.
+  // Values match DeviceKit's orientation-picker-control (Xcode 27.1).
+  NSString *value;
+  switch (orientation) {
+    case UIDeviceOrientationPortrait:
+      value = screen.isMainScreen ? @"portrait" : @"landscape-left";
+      break;
+    case UIDeviceOrientationLandscapeLeft:
+      value = screen.isMainScreen ? @"landscape-left" : @"pud";
+      break;
+    case UIDeviceOrientationLandscapeRight:
+      value = screen.isMainScreen ? @"landscape-right" : @"portrait";
+      break;
+    case UIDeviceOrientationPortraitUpsideDown:
+      value = screen.isMainScreen ? @"pud" : @"landscape-right";
+      break;
+    case UIDeviceOrientationUnknown:
+    case UIDeviceOrientationFaceUp:
+    case UIDeviceOrientationFaceDown:
+    default:
+      return NO;
+  }
+
+  const FBHIDAPI *api = FBGetHIDAPI();
+  if (NULL == api->serialize || NULL == api->createVendorEvent
+      || NULL == api->createClient || NULL == api->dispatchEvent) {
+    return NO;
+  }
+  NSDictionary *payload = @{
+    @"provider": @"com.apple.Virtualization.VirtualMachines",
+    @"source": @"orientation-picker-control",
+    @"type": @"enum",
+    @"value": value,
+  };
+  // The receiver expects IOCF binary serialization, not a binary plist.
+  CFDataRef data = api->serialize((__bridge CFTypeRef)payload, FBHIDBinarySerialization);
+  if (NULL == data) {
+    return NO;
+  }
+  CFTypeRef event = api->createVendorEvent(kCFAllocatorDefault, mach_absolute_time(),
+                                         FBHIDOrientationUsagePage, FBHIDOrientationUsage, 0,
+                                         (uint8_t *)CFDataGetBytePtr(data), CFDataGetLength(data), 0);
+  CFRelease(data);
+  CFTypeRef client = api->createClient(kCFAllocatorDefault);
+  BOOL canDispatch = NULL != event && NULL != client;
+  if (canDispatch) {
+    api->dispatchEvent(client, event);
+  }
+  if (NULL != event) {
+    CFRelease(event);
+  }
+  if (NULL != client) {
+    CFRelease(client);
+  }
+  return canDispatch;
+}
+
+#endif
+
+@implementation FBHIDOperations
+
++ (BOOL)appliesToDevice:(XCUIDevice *)device
+{
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+  return device.fb_supportsHingeAngleReading;
+#else
+  return NO;
+#endif
+}
+
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
++ (BOOL)pressHomeWithError:(NSError **)error
+{
+  FBLogUnverifiedPhysicalHIDOperation(@"Home");
+  return FBPressHIDButton(FBHIDHomeUsage, error);
+}
+
++ (BOOL)pressLockWithError:(NSError **)error
+{
+  FBLogUnverifiedPhysicalHIDOperation(@"lock");
+  // XCTest locking times out on Duo / iOS 27.1 (Xcode 27.1). Remove this
+  // workaround once XCTest alone passes testRepeatedLockUnlockAcrossHingePoses.
+  return FBPressHIDButton(FBHIDPowerUsage, error);
+}
+
++ (BOOL)rotateToOrientation:(UIDeviceOrientation)orientation
+     interfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
+{
+  FBLogUnverifiedPhysicalHIDOperation(@"rotation");
+  XCUIApplication *application = XCUIApplication.fb_activeApplication;
+  // Point-based detection can select the cover SpringBoard while the app
+  // is on the inner panel. Prefer the session's active application.
+  application = FBSession.activeSession.activeApplication ?: application;
+  // Keep XCTest's reported device orientation in sync on the simulator too.
+  [XCUIDevice sharedDevice].orientation = orientation;
+  // On Duo simulators XCTest can update its value without rotating the app.
+  // Use the same direct HID path on simulators and physical hinged devices.
+  if (!FBDispatchHIDOrientation(orientation)) {
+    return NO;
+  }
+  // Event dispatch is asynchronous. Check the app, not just XCTest's value.
+  if (![[[FBRunLoopSpinner new] timeout:FBHIDRotationTimeout] spinUntilTrue:^BOOL{
+    return application.interfaceOrientation == interfaceOrientation;
+  }]) {
+    return NO;
+  }
+  return FBWaitForStableInterfaceOrientation(application, interfaceOrientation);
+}
+#endif
+
+@end

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBImageProcessor.m

@@ -144,7 +144,9 @@ const CGFloat FBMaxCompressionQuality = 1.0f;
     }
   
     UIGraphicsImageRendererFormat *format = [[UIGraphicsImageRendererFormat alloc] init];
-    format.scale = scalingFactor;
+    // scaledSize already applies the requested factor in points. Preserve the
+    // image's pixels-per-point scale instead of applying that factor twice.
+    format.scale = image.scale;
     UIGraphicsImageRenderer *renderer = [[UIGraphicsImageRenderer alloc] initWithSize:scaledSize
                                                                                format:format];
     UIImageOrientation desiredOrientation = orientation == nil

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBMathUtils.h

@@ -35,8 +35,19 @@ BOOL FBSizeFuzzyEqualToSize(CGSize size1, CGSize size2, CGFloat threshold);
 BOOL FBRectFuzzyEqualToRect(CGRect rect1, CGRect rect2, CGFloat threshold);
 
 #if !TARGET_OS_TV && !TARGET_OS_WATCH
+/*! Converts a portrait-screen rect into the application's orientation, preserving its clipping. */
+CGRect FBRectFromPortraitCoordinates(CGRect frame, CGSize screenSize, UIInterfaceOrientation orientation);
+
 /*! Inverts size if necessary to match current screen orientation */
 CGSize FBAdjustDimensionsForApplication(CGSize actualSize, UIInterfaceOrientation orientation);
+
+/*!
+ Offsets XCTest screenPoint coordinates for an explicitly selected display.
+ XCTest rotates these coordinates using the main screen's dimensions even when
+ the synthesized event record targets another display. Sizes are in points.
+ */
+CGVector FBDisplayCoordinateOffset(CGSize mainSize, CGSize displaySize,
+                                  UIInterfaceOrientation orientation);
 #endif
 
 #if !TARGET_OS_TV

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBMathUtils.m

@@ -50,6 +50,27 @@ BOOL FBRectFuzzyEqualToRect(CGRect rect1, CGRect rect2, CGFloat threshold)
 
 #if !TARGET_OS_TV && !TARGET_OS_WATCH
 
+CGRect FBRectFromPortraitCoordinates(CGRect frame, CGSize screenSize, UIInterfaceOrientation orientation)
+{
+  if (CGRectIsEmpty(frame)) {
+    return frame;
+  }
+  CGFloat width = MIN(screenSize.width, screenSize.height);
+  CGFloat height = MAX(screenSize.width, screenSize.height);
+  switch (orientation) {
+    case UIInterfaceOrientationLandscapeLeft:
+      return CGRectMake(height - CGRectGetMaxY(frame), CGRectGetMinX(frame), frame.size.height, frame.size.width);
+    case UIInterfaceOrientationLandscapeRight:
+      return CGRectMake(CGRectGetMinY(frame), width - CGRectGetMaxX(frame), frame.size.height, frame.size.width);
+    case UIInterfaceOrientationPortraitUpsideDown:
+      return CGRectMake(width - CGRectGetMaxX(frame), height - CGRectGetMaxY(frame), frame.size.width, frame.size.height);
+    case UIInterfaceOrientationUnknown:
+    case UIInterfaceOrientationPortrait:
+    default:
+      return frame;
+  }
+}
+
 CGSize FBAdjustDimensionsForApplication(CGSize actualSize, UIInterfaceOrientation orientation)
 {
   if (orientation == UIInterfaceOrientationLandscapeLeft || orientation == UIInterfaceOrientationLandscapeRight) {
@@ -107,3 +128,20 @@ BOOL FBScrollGestureOffsets(CGRect scrollingFrame,
                             (endPoint.y - anchorFrame.origin.y) / anchorFrame.size.height);
   return YES;
 }
+
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+CGVector FBDisplayCoordinateOffset(CGSize mainSize, CGSize displaySize,
+                                  UIInterfaceOrientation orientation)
+{
+  CGVector offset = CGVectorMake(0, 0);
+  if (orientation == UIInterfaceOrientationLandscapeRight
+      || orientation == UIInterfaceOrientationPortraitUpsideDown) {
+    offset.dx = displaySize.width - mainSize.width;
+  }
+  if (orientation == UIInterfaceOrientationLandscapeLeft
+      || orientation == UIInterfaceOrientationPortraitUpsideDown) {
+    offset.dy = displaySize.height - mainSize.height;
+  }
+  return offset;
+}
+#endif

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBMjpegServer.m

@@ -16,6 +16,7 @@
 #import "FBConfiguration.h"
 #import "FBLogger.h"
 #import "FBScreenshot.h"
+#import "FBScreen.h"
 #import "FBImageProcessor.h"
 #import "FBImageUtils.h"
 #import "XCUIScreen.h"
@@ -42,7 +43,6 @@ static NSUInteger FBNormalizedMjpegFramerate(NSUInteger framerate)
 @property (nonatomic, readonly) dispatch_queue_t backgroundQueue;
 @property (nonatomic, readonly) NSMutableArray<nw_connection_t> *listeningClients;
 @property (nonatomic, readonly) FBImageProcessor *imageProcessor;
-@property (nonatomic, readonly) long long mainScreenID;
 @property (nonatomic, assign) NSUInteger consecutiveScreenshotFailures;
 @property (atomic, assign) BOOL isStreaming;
 @property (nonatomic, assign) NSUInteger sentFramesCount;
@@ -67,7 +67,6 @@ static NSUInteger FBNormalizedMjpegFramerate(NSUInteger framerate)
     _pendingFrameCounts = [NSMapTable mapTableWithKeyOptions:(NSPointerFunctionsOptions)(NSMapTableObjectPointerPersonality | NSMapTableStrongMemory)
                                                 valueOptions:(NSPointerFunctionsOptions)NSMapTableStrongMemory];
     _imageProcessor = [[FBImageProcessor alloc] init];
-    _mainScreenID = [XCUIScreen.mainScreen displayID];
     dispatch_queue_attr_t queueAttributes = dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL, QOS_CLASS_UTILITY, 0);
     _backgroundQueue = dispatch_queue_create(QUEUE_NAME, queueAttributes);
     __weak typeof(self) weakSelf = self;
@@ -116,7 +115,8 @@ static NSUInteger FBNormalizedMjpegFramerate(NSUInteger framerate)
   NSError *error;
   CGFloat compressionQuality = MAX(FBMinCompressionQuality,
                                    MIN(FBMaxCompressionQuality, (double)FBConfiguration.sharedInstance.mjpegServerScreenshotQuality / 100.0));
-  NSData *screenshotData = [FBScreenshot takeInOriginalResolutionWithScreenID:self.mainScreenID
+  XCUIScreen *screen = [FBScreen currentScreenWithError:&error];
+  NSData *screenshotData = nil == screen ? nil : [FBScreenshot takeInOriginalResolutionWithScreenID:screen.displayID
                                                            compressionQuality:compressionQuality
                                                                           uti:UTTypeJPEG
                                                                       timeout:FRAME_TIMEOUT
@@ -221,6 +221,8 @@ static NSUInteger FBNormalizedMjpegFramerate(NSUInteger framerate)
     [self.listeningClients removeObject:client];
     [self.pendingFrameCounts removeObjectForKey:client];
   }
+  // Nothing is owed to a client that stopped listening, so its socket can go right away.
+  nw_connection_cancel(client);
   [FBLogger log:@"Disconnected a client from screenshots broadcast"];
 }
 

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBScreen.h

@@ -17,6 +17,23 @@ NS_ASSUME_NONNULL_BEGIN
  */
 + (nullable NSArray<NSDictionary<NSString *, id> *> *)screensWithError:(NSError **)error;
 
+/**
+ The display with the given identifier
+
+ @param displayID The display identifier, as returned by screensWithError:
+ @param error Set if the display is not available
+ @return The matching display or nil
+ */
++ (nullable XCUIScreen *)screenWithDisplayID:(long long)displayID error:(NSError **)error;
+
+/**
+ The display selected by the currentDisplayId setting, or the main display if the setting is not set
+
+ @param error Set if the selected display is no longer available
+ @return The selected display or nil
+ */
++ (nullable XCUIScreen *)currentScreenWithError:(NSError **)error;
+
 /**
  The identifier of the main device's display
  */

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBScreen.m

@@ -7,16 +7,32 @@
  */
 
 #import "FBScreen.h"
+#import "FBConfiguration.h"
+#import "FBErrorBuilder.h"
 #import "XCUIElement+FBIsVisible.h"
 #import "FBXCodeCompatibility.h"
 #import "XCUIDevice.h"
 #import "XCUIScreen.h"
+#import <objc/message.h>
+
+static NSArray<XCUIScreen *> *FBScreensForDevice(id device, NSError **error)
+{
+  SEL selector = NSSelectorFromString(@"screensOrError:");
+  if ([device respondsToSelector:selector]) {
+    return ((NSArray<XCUIScreen *> *(*)(id, SEL, NSError **))objc_msgSend)(device, selector, error);
+  }
+  // Older XCTest versions expose screens on XCUIScreen instead of XCUIDevice.
+  if ([XCUIScreen respondsToSelector:NSSelectorFromString(@"screens")]) {
+    return XCUIScreen.screens;
+  }
+  return @[XCUIScreen.mainScreen];
+}
 
 @implementation FBScreen
 
 + (nullable NSArray<NSDictionary<NSString *, id> *> *)screensWithError:(NSError **)error
 {
-  NSArray<XCUIScreen *> *screens = [XCUIDevice.sharedDevice screensOrError:error];
+  NSArray<XCUIScreen *> *screens = FBScreensForDevice(XCUIDevice.sharedDevice, error);
   if (nil == screens) {
     return nil;
   }
@@ -40,6 +56,65 @@
   return result.copy;
 }
 
+// Kept separate from sharedDevice so legacy lookup behavior can be tested.
++ (nullable XCUIScreen *)screenWithDisplayID:(long long)displayID
+                                    device:(XCUIDevice *)device
+                                     error:(NSError **)error
+{
+  SEL lookupSelector = NSSelectorFromString(@"screenWithDisplayID:orError:");
+  BOOL hasNativeLookup = [device respondsToSelector:lookupSelector];
+  BOOL needsEnumeratedLookup = !hasNativeLookup;
+  NSError *lookupError = nil;
+  if (hasNativeLookup) {
+    XCUIScreen *screen = ((XCUIScreen *(*)(id, SEL, long long, NSError **))objc_msgSend)(
+      device, lookupSelector, displayID, &lookupError);
+    if ([screen respondsToSelector:NSSelectorFromString(@"bounds")] && !CGRectIsEmpty(screen.bounds)) {
+      return screen;
+    }
+    // XCTest may return a zero-sized placeholder for an inactive wireless
+    // display which screensOrError: omits. Confirm its availability by listing.
+    needsEnumeratedLookup = nil != screen;
+  }
+  // Enumerate only for legacy/placeholder lookups or to enrich a lookup error.
+  NSError *enumerationError = nil;
+  NSArray<XCUIScreen *> *screens = FBScreensForDevice(device, &enumerationError);
+  if (nil == screens) {
+    if (NULL != error) {
+      *error = lookupError ?: enumerationError;
+    }
+    return nil;
+  }
+  NSMutableArray<NSNumber *> *availableIDs = [NSMutableArray arrayWithCapacity:screens.count];
+  for (XCUIScreen *screen in screens) {
+    if (needsEnumeratedLookup && screen.displayID == displayID) {
+      return screen;
+    }
+    [availableIDs addObject:@(screen.displayID)];
+  }
+  FBErrorBuilder *builder = [FBErrorBuilder.builder withDescriptionFormat:
+    @"No display with id %lld is available. Available display ids: [%@]",
+    displayID, [availableIDs componentsJoinedByString:@", "]];
+  if (nil != lookupError) {
+    [builder withInnerError:lookupError];
+  }
+  [builder buildError:error];
+  return nil;
+}
+
++ (nullable XCUIScreen *)screenWithDisplayID:(long long)displayID error:(NSError **)error
+{
+  return [self screenWithDisplayID:displayID device:XCUIDevice.sharedDevice error:error];
+}
+
++ (nullable XCUIScreen *)currentScreenWithError:(NSError **)error
+{
+  NSNumber *displayID = FBConfiguration.sharedInstance.currentDisplayId;
+  if (nil == displayID) {
+    return XCUIScreen.mainScreen;
+  }
+  return [self screenWithDisplayID:displayID.longLongValue error:error];
+}
+
 + (long long)displayID
 {
   return XCUIScreen.mainScreen.displayID;

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBScreenshot.h

@@ -14,7 +14,7 @@ NS_ASSUME_NONNULL_BEGIN
 @interface FBScreenshot : NSObject
 
 /**
- Retrieves non-scaled screenshot of the whole screen
+ Retrieves non-scaled screenshot of the display selected by the currentDisplayId setting
 
  @param quality The number in range 0-3, where 0 is PNG (lossless), 3 is HEIC (lossless), 1- low quality JPEG and 2 - high quality JPEG
  @param error If there is an error, upon return contains an NSError object that describes the problem.
@@ -24,7 +24,7 @@ NS_ASSUME_NONNULL_BEGIN
                                                    error:(NSError **)error;
 
 /**
- Retrieves non-scaled screenshot of the whole screen
+ Retrieves non-scaled screenshot of the display selected by the currentDisplayId setting
 
  @param screenID The screen identifier to take the screenshot from
  @param compressionQuality Normalized screenshot quality value in range 0..1, where 1 is the best quality

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBScreenshot.m

@@ -15,6 +15,7 @@
 #import "FBImageProcessor.h"
 #import "FBLogger.h"
 #import "FBMacros.h"
+#import "FBScreen.h"
 #import "FBXCodeCompatibility.h"
 #import "FBXCTestDaemonsProxy.h"
 #import "XCTMessagingChannel_RunnerToDaemon-Protocol.h"
@@ -60,8 +61,11 @@ NSString *formatTimeInterval(NSTimeInterval interval) {
 + (NSData *)takeInOriginalResolutionWithQuality:(NSUInteger)quality
                                           error:(NSError **)error
 {
-  XCUIScreen *mainScreen = XCUIScreen.mainScreen;
-  return [self.class takeWithScreenID:mainScreen.displayID
+  XCUIScreen *screen = [FBScreen currentScreenWithError:error];
+  if (nil == screen) {
+    return nil;
+  }
+  return [self.class takeWithScreenID:screen.displayID
                                 scale:SCREENSHOT_SCALE
                    compressionQuality:[self.class compressionQualityWithQuality:quality]
                             sourceUTI:[self.class imageUtiWithQuality:quality]

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBSettings.h

@@ -36,6 +36,7 @@ extern NSString* const FB_SETTING_SCREENSHOT_ORIENTATION;
 extern NSString* const FB_SETTING_WAIT_FOR_IDLE_TIMEOUT;
 extern NSString* const FB_SETTING_ANIMATION_COOL_OFF_TIMEOUT;
 extern NSString* const FB_SETTING_MAX_TYPING_FREQUENCY;
+extern NSString* const FB_SETTING_KEYBOARD_WAIT_TIMEOUT;
 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;
@@ -46,5 +47,6 @@ extern NSString *const FB_SETTING_INCLUDE_NATIVE_ACCESSIBILITY_ELEMENT_IN_PAGE_S
 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;
+extern NSString *const FB_SETTING_CURRENT_DISPLAY_ID;
 
 NS_ASSUME_NONNULL_END

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Utilities/FBSettings.m

@@ -32,6 +32,7 @@ NSString* const FB_SETTING_SCREENSHOT_ORIENTATION = @"screenshotOrientation";
 NSString* const FB_SETTING_WAIT_FOR_IDLE_TIMEOUT = @"waitForIdleTimeout";
 NSString* const FB_SETTING_ANIMATION_COOL_OFF_TIMEOUT = @"animationCoolOffTimeout";
 NSString* const FB_SETTING_MAX_TYPING_FREQUENCY = @"maxTypingFrequency";
+NSString* const FB_SETTING_KEYBOARD_WAIT_TIMEOUT = @"keyboardWaitTimeout";
 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";
@@ -42,3 +43,4 @@ NSString* const FB_SETTING_INCLUDE_NATIVE_ACCESSIBILITY_ELEMENT_IN_PAGE_SOURCE =
 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";
+NSString* const FB_SETTING_CURRENT_DISPLAY_ID = @"currentDisplayId";