appium-webdriveragent 16.12.11 → 16.13.1

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [16.13.1](https://github.com/appium/WebDriverAgent/compare/v16.13.0...v16.13.1) (2026-09-30)
+
+### Performance Improvements
+
+* reuse sibling indices and geometry during XML serialization ([#1283](https://github.com/appium/WebDriverAgent/issues/1283)) ([f352660](https://github.com/appium/WebDriverAgent/commit/f352660deb52728c195a875b4172e38e1a1496b8))
+
+## [16.13.0](https://github.com/appium/WebDriverAgent/compare/v16.12.11...v16.13.0) (2026-09-30)
+
+### Features
+
+* add currentDisplayId setting for screenshots ([#1267](https://github.com/appium/WebDriverAgent/issues/1267)) ([c9366a2](https://github.com/appium/WebDriverAgent/commit/c9366a227b6de19381c96d56a548e9fb53d77dba))
+
+### Bug Fixes
+
+* apply screenshot scaling once when correcting orientation ([#1278](https://github.com/appium/WebDriverAgent/issues/1278)) ([17fd4d0](https://github.com/appium/WebDriverAgent/commit/17fd4d059c351d73384604be40bbade4a03be9a9))
+* avoid infinite-point assertion and hang in coordinate drag gestures ([#1270](https://github.com/appium/WebDriverAgent/issues/1270)) ([c9290a0](https://github.com/appium/WebDriverAgent/commit/c9290a01a63fa195c8aba35c9f0cdad1cd9a6d64)), closes [#1056](https://github.com/appium/WebDriverAgent/issues/1056)
+* cancel connections that end on the client side ([#1273](https://github.com/appium/WebDriverAgent/issues/1273)) ([261c08d](https://github.com/appium/WebDriverAgent/commit/261c08d53917b138eaf2f7d8a744d1151fe3bc8d))
+* isolate xcodebuild readiness state between launches ([#1275](https://github.com/appium/WebDriverAgent/issues/1275)) ([ccc46fe](https://github.com/appium/WebDriverAgent/commit/ccc46fe6de1871a020205488533c1d5b9b7dc756))
+* release LRU cache values when the cache is destroyed ([#1274](https://github.com/appium/WebDriverAgent/issues/1274)) ([fb52865](https://github.com/appium/WebDriverAgent/commit/fb5286515584157659ed86bccdbb64bc3094d91f))
+
 ## [16.12.11](https://github.com/appium/WebDriverAgent/compare/v16.12.10...v16.12.11) (2026-09-28)
 
 ### Bug Fixes

package/WebDriverAgentLib/Categories/XCUIApplication+FBTouchAction.h

@@ -10,6 +10,8 @@
 #import <XCTest/XCTest.h>
 #import "FBElementCache.h"
 
+@class XCSynthesizedEventRecord;
+
 NS_ASSUME_NONNULL_BEGIN
 
 @interface XCUIApplication (FBTouchAction)
@@ -24,6 +26,57 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (BOOL)fb_performW3CActions:(NSArray *)actions elementCache:(nullable FBElementCache *)elementCache error:(NSError * _Nullable*)error;
 
+/**
+ Presses at startCoordinate, drags to endCoordinate and holds there, producing the same touch event
+ path as -[XCUICoordinate pressForDuration:thenDragToCoordinate:withVelocity:thenHoldForDuration:].
+
+ Unlike that XCTest method, both screen points are resolved exactly once, up front, and validated
+ before anything is sent; the resulting event is then synthesized directly, without XCTest's
+ dispatch-time re-snapshot and quiescence wait of the application. XCTest resolves the points
+ inside that dispatch, so an application that is busy (e.g. right after an app switch) makes it
+ hang and then assert on an infinite point instead of failing cleanly.
+ See https://github.com/appium/WebDriverAgent/issues/1056
+
+ @param startCoordinate The coordinate to press at
+ @param pressDuration How long to hold still at startCoordinate before dragging, in seconds (>= 0)
+ @param endCoordinate The coordinate to drag to
+ @param velocity Drag velocity in points per second, or one of the XCUIGestureVelocity constants
+ @param holdDuration How long to hold still at endCoordinate before lifting, in seconds (>= 0)
+ @param error If there is an error, upon return contains an NSError object that describes the problem
+ @return YES if the gesture has been successfully performed
+ @throws FBInvalidArgumentException if a duration or the velocity is out of range
+ */
+- (BOOL)fb_pressAtCoordinate:(XCUICoordinate *)startCoordinate
+                 forDuration:(NSTimeInterval)pressDuration
+        thenDragToCoordinate:(XCUICoordinate *)endCoordinate
+                withVelocity:(XCUIGestureVelocity)velocity
+         thenHoldForDuration:(NSTimeInterval)holdDuration
+                       error:(NSError * _Nullable*)error;
+
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+/**
+ Builds the synthesized event used by
+ -fb_pressAtCoordinate:forDuration:thenDragToCoordinate:withVelocity:thenHoldForDuration:error:
+ from already resolved screen points. Exposed for testing.
+
+ @param startPoint The screen point to press at
+ @param pressDuration How long to hold still at startPoint before dragging, in seconds
+ @param endPoint The screen point to drag to
+ @param pointsPerSecond The drag speed
+ @param holdDuration How long to hold still at endPoint before lifting, in seconds
+ @param displayID The display to send the gesture to (0 is the main display)
+ @param interfaceOrientation The interface orientation the points are expressed in
+ @return The event record, ready to be synthesized
+ */
++ (XCSynthesizedEventRecord *)fb_pressDragEventFromPoint:(CGPoint)startPoint
+                                             forDuration:(NSTimeInterval)pressDuration
+                                                 toPoint:(CGPoint)endPoint
+                                         pointsPerSecond:(CGFloat)pointsPerSecond
+                                     thenHoldForDuration:(NSTimeInterval)holdDuration
+                                               displayID:(long long)displayID
+                                    interfaceOrientation:(UIInterfaceOrientation)interfaceOrientation;
+#endif
+
 @end
 
 NS_ASSUME_NONNULL_END

package/WebDriverAgentLib/Categories/XCUIApplication+FBTouchAction.m

@@ -9,17 +9,67 @@
 
 #import "XCUIApplication+FBTouchAction.h"
 
+#import <dlfcn.h>
+
 #import "FBBaseActionsSynthesizer.h"
 #import "FBConfiguration.h"
+#import "FBErrorBuilder.h"
 #import "FBExceptions.h"
 #import "FBLogger.h"
+#import "FBMathUtils.h"
 #import "FBRunLoopSpinner.h"
 #import "FBW3CActionsSynthesizer.h"
 #import "FBXCTestDaemonsProxy.h"
+#import "XCPointerEventPath.h"
+#import "XCSynthesizedEventRecord.h"
+#import "XCUIElement.h"
 #import "XCUIElement+FBUtilities.h"
 
 #if !TARGET_OS_TV && !TARGET_OS_WATCH
 
+/**
+ Maps a drag XCUIGestureVelocity to the speed XCTest drags at. XCTest calls the result "pixels per
+ second", but divides the distance between the two screen points (which are in points) by it.
+ Prefers XCTest's own (exported, but undeclared) mapping function, so any future change to its
+ presets is picked up; falls back to the values it returns now.
+
+ @throws FBInvalidArgumentException if the velocity is neither one of the XCUIGestureVelocity
+ presets nor a positive finite number
+ */
+static CGFloat FBPointsPerSecondForDragVelocity(XCUIGestureVelocity velocity)
+{
+  BOOL isDefault = FBFloatFuzzyEqualToFloat(velocity, XCUIGestureVelocityDefault, 0);
+  BOOL isSlow = FBFloatFuzzyEqualToFloat(velocity, XCUIGestureVelocitySlow, 0);
+  BOOL isFast = FBFloatFuzzyEqualToFloat(velocity, XCUIGestureVelocityFast, 0);
+  if (!isDefault && !isSlow && !isFast && !(isfinite(velocity) && velocity > 0)) {
+    NSString *reason = [NSString stringWithFormat:@"%@ is an invalid drag velocity. It must be greater than 0", @(velocity)];
+    @throw [NSException exceptionWithName:FBInvalidArgumentException reason:reason userInfo:nil];
+  }
+  static double (*xctestMapping)(double) = NULL;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    xctestMapping = (double (*)(double))dlsym(RTLD_DEFAULT, "XCUIPixelsPerSecondForDragGestureVelocity");
+    if (NULL == xctestMapping) {
+      [FBLogger log:@"Could not find XCUIPixelsPerSecondForDragGestureVelocity. Using built-in drag velocity presets instead"];
+    }
+  });
+  if (NULL != xctestMapping) {
+    return (CGFloat)xctestMapping(velocity);
+  }
+  if (isSlow) {
+    return 250;
+  }
+  if (isFast) {
+    return 750;
+  }
+  return isDefault ? 500 : velocity;
+}
+
+static BOOL FBIsFinitePoint(CGPoint point)
+{
+  return isfinite(point.x) && isfinite(point.y);
+}
+
 @implementation XCUIApplication (FBTouchAction)
 
 + (BOOL)handleEventSynthesWithError:(NSError *)error
@@ -65,6 +115,80 @@
   return YES;
 }
 
+- (BOOL)fb_pressAtCoordinate:(XCUICoordinate *)startCoordinate
+                 forDuration:(NSTimeInterval)pressDuration
+        thenDragToCoordinate:(XCUICoordinate *)endCoordinate
+                withVelocity:(XCUIGestureVelocity)velocity
+         thenHoldForDuration:(NSTimeInterval)holdDuration
+                       error:(NSError **)error
+{
+  CGFloat pointsPerSecond = FBPointsPerSecondForDragVelocity(velocity);
+  if (!isfinite(pressDuration) || pressDuration < 0 || !isfinite(holdDuration) || holdDuration < 0) {
+    NSString *reason = [NSString stringWithFormat:@"Drag press and hold durations must be non-negative numbers of seconds. Got %@ and %@", @(pressDuration), @(holdDuration)];
+    @throw [NSException exceptionWithName:FBInvalidArgumentException reason:reason userInfo:nil];
+  }
+
+  // Resolved once, here, so the points validated below are exactly the ones sent. XCTest's own
+  // drag re-resolves them inside its event dispatch instead, after re-snapshotting the application.
+  CGPoint startPoint = startCoordinate.screenPoint;
+  CGPoint endPoint = endCoordinate.screenPoint;
+  if (!FBIsFinitePoint(startPoint) || !FBIsFinitePoint(endPoint)) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"Cannot resolve the on-screen position of the drag gesture (from %@ to %@). "
+             "This usually means '%@' did not deliver a valid accessibility snapshot, e.g. because it is busy "
+             "or still transitioning after an application switch. Make sure it is idle and retry",
+             NSStringFromCGPoint(startPoint), NSStringFromCGPoint(endPoint), self.bundleID]
+            buildError:error];
+  }
+
+  // Like XCTest, target the display of the element the start coordinate belongs to. displayID
+  // only reads the element's last snapshot, which resolving screenPoint above has just refreshed.
+  XCUIElement *referencedElement = startCoordinate.referencedElement;
+  long long displayID = [referencedElement respondsToSelector:@selector(displayID)]
+    ? referencedElement.displayID
+    : 0;
+  XCSynthesizedEventRecord *event = [self.class fb_pressDragEventFromPoint:startPoint
+                                                               forDuration:pressDuration
+                                                                   toPoint:endPoint
+                                                           pointsPerSecond:pointsPerSecond
+                                                       thenHoldForDuration:holdDuration
+                                                                 displayID:displayID
+                                                      interfaceOrientation:self.interfaceOrientation];
+  if (![self fb_synthesizeEvent:event error:error]) {
+    return NO;
+  }
+  [self fb_waitUntilStableWithTimeout:FBConfiguration.sharedInstance.animationCoolOffTimeout];
+  return YES;
+}
+
++ (XCSynthesizedEventRecord *)fb_pressDragEventFromPoint:(CGPoint)startPoint
+                                             forDuration:(NSTimeInterval)pressDuration
+                                                 toPoint:(CGPoint)endPoint
+                                         pointsPerSecond:(CGFloat)pointsPerSecond
+                                     thenHoldForDuration:(NSTimeInterval)holdDuration
+                                               displayID:(long long)displayID
+                                    interfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
+{
+  // Mirrors XCTest's own press-hold-drag event builder
+  XCPointerEventPath *path = [[XCPointerEventPath alloc] initForTouchAtPoint:startPoint offset:0];
+  if (pressDuration > 0) {
+    [path moveToPoint:startPoint atOffset:pressDuration];
+  }
+  CGFloat distance = (CGFloat)hypot(endPoint.x - startPoint.x, endPoint.y - startPoint.y);
+  NSTimeInterval dragEndOffset = pressDuration + distance / pointsPerSecond;
+  [path moveToPoint:endPoint atOffset:dragEndOffset];
+  [path liftUpAtOffset:dragEndOffset + holdDuration];
+
+  NSString *name = @"Press, drag and hold";
+  XCSynthesizedEventRecord *event = [XCSynthesizedEventRecord instancesRespondToSelector:@selector(initWithName:displayID:interfaceOrientation:)]
+    ? [[XCSynthesizedEventRecord alloc] initWithName:name
+                                           displayID:(unsigned long long)displayID
+                                interfaceOrientation:interfaceOrientation]
+    : [[XCSynthesizedEventRecord alloc] initWithName:name interfaceOrientation:interfaceOrientation];
+  [event addPointerEventPath:path];
+  return event;
+}
+
 - (BOOL)fb_synthesizeEvent:(XCSynthesizedEventRecord *)event error:(NSError *__autoreleasing*)error
 {
   return [FBXCTestDaemonsProxy synthesizeEventWithRecord:event error:error];

package/WebDriverAgentLib/Commands/FBElementCommands.m

@@ -22,6 +22,7 @@
 #import "FBRuntimeUtils.h"
 #import "NSPredicate+FBFormat.h"
 #import "XCTestPrivateSymbols.h"
+#import "XCUIApplication+FBTouchAction.h"
 #import "XCUICoordinate.h"
 #import "XCUIDevice.h"
 #import "XCUIElement+FBIsVisible.h"
@@ -370,10 +371,14 @@
   if (nil == endCoordinate) {
     return FBResponseWithStatus([FBCommandStatus invalidElementStateErrorWithMessage:error.description traceback:nil]);
   }
-  [startCoordinate pressForDuration:[request.arguments[@"pressDuration"] doubleValue]
-               thenDragToCoordinate:endCoordinate
-                       withVelocity:[request.arguments[@"velocity"] doubleValue]
-                thenHoldForDuration:[request.arguments[@"holdDuration"] doubleValue]];
+  if (![application fb_pressAtCoordinate:startCoordinate
+                             forDuration:[request.arguments[@"pressDuration"] doubleValue]
+                    thenDragToCoordinate:endCoordinate
+                            withVelocity:[request.arguments[@"velocity"] doubleValue]
+                     thenHoldForDuration:[request.arguments[@"holdDuration"] doubleValue]
+                                   error:&error]) {
+    return FBResponseWithStatus([FBCommandStatus invalidElementStateErrorWithMessage:error.description traceback:nil]);
+  }
   return FBResponseWithOK();
 }
 
@@ -456,7 +461,17 @@
     return FBResponseWithStatus([FBCommandStatus invalidElementStateErrorWithMessage:error.description traceback:nil]);
   }
   NSTimeInterval duration = [request.arguments[@"duration"] doubleValue];
-  [startCoordinate pressForDuration:duration thenDragToCoordinate:endCoordinate];
+  XCUIApplication *application = [target isKindOfClass:XCUIApplication.class]
+    ? (XCUIApplication *)target
+    : target.application;
+  if (![application fb_pressAtCoordinate:startCoordinate
+                             forDuration:duration
+                    thenDragToCoordinate:endCoordinate
+                            withVelocity:XCUIGestureVelocityDefault
+                     thenHoldForDuration:0
+                                   error:&error]) {
+    return FBResponseWithStatus([FBCommandStatus invalidElementStateErrorWithMessage:error.description traceback:nil]);
+  }
   return FBResponseWithOK();
 }
 

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentLib/Routing/FBHTTPServer.m

@@ -340,12 +340,18 @@ static const int64_t FBStaleConnectionSweepIntervalSec = 10;
 
 - (void)didClientDisconnect:(nw_connection_t)client
 {
+  BOOL isAwaitingResponse;
   @synchronized (self.connectionBuffers) {
+    isAwaitingResponse = [self.connectionsAwaitingResponse containsObject:client];
     [self.connectionBuffers removeObjectForKey:client];
     [self.pendingRequestHeaders removeObjectForKey:client];
-    [self.connectionsAwaitingResponse removeObject:client];
     [self.incompleteRequestStarts removeObjectForKey:client];
   }
+  // A client that only stopped sending may still read the response to its in-flight request, so
+  // that response's send completion closes the connection instead (it finds no buffer left).
+  if (!isAwaitingResponse) {
+    nw_connection_cancel(client);
+  }
 }
 
 - (void)client:(nw_connection_t)client didReceiveData:(NSData *)data
@@ -881,14 +887,21 @@ static const int64_t FBStaleConnectionSweepIntervalSec = 10;
         if (nil == queuedSelf) {
           return;
         }
+        BOOL isDisconnected;
         @synchronized (queuedSelf.connectionBuffers) {
           [queuedSelf.connectionsAwaitingResponse removeObject:client];
+          isDisconnected = nil == [queuedSelf.connectionBuffers objectForKey:client];
           // Mid-request connections get their window from when parsing could resume, not from the
           // previous request. Absent entries stay absent, so idle keep-alives remain exempt.
           if (nil != [queuedSelf.incompleteRequestStarts objectForKey:client]) {
             [queuedSelf.incompleteRequestStarts setObject:[NSDate date] forKey:client];
           }
         }
+        if (isDisconnected) {
+          // The peer stopped sending while this request was in flight - see -didClientDisconnect:.
+          [queuedSelf closeClient:client];
+          return;
+        }
         [queuedSelf processBufferForClient:client];
       });
     }];

package/WebDriverAgentLib/Routing/FBTCPSocket.h

@@ -36,7 +36,11 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)client:(nw_connection_t)client didReceiveData:(NSData *)data;
 
 /**
- The callback which is fired when TCP client disconnects
+ The callback which is fired when TCP client disconnects or finishes sending
+
+ A connection that failed is cancelled by the socket. One whose peer only finished sending stays
+ writable (the peer may be awaiting a response), and the delegate must cancel it once it has
+ nothing left to send - an uncancelled connection keeps its socket open.
 
  @param client The actual disconnected client
  */

package/WebDriverAgentLib/Routing/FBTCPSocket.m

@@ -137,6 +137,8 @@
     } else if (nw_connection_state_failed == state || nw_connection_state_cancelled == state) {
       __strong typeof(weakSelf) strongSelf = weakSelf;
       [strongSelf handleDisconnectForConnection:connection];
+      // A failed connection keeps its socket until cancelled (a no-op once cancelled).
+      nw_connection_cancel(connection);
     }
   });
   nw_connection_start(connection);
@@ -167,7 +169,14 @@
         }
       }
     }
-    if (nil != receiveError || (isComplete && nil == content)) {
+    if (nil != receiveError) {
+      [strongSelf handleDisconnectForConnection:connection];
+      nw_connection_cancel(connection);
+      return;
+    }
+    if (isComplete && nil == content) {
+      // The peer is done sending but may still be reading - a half-closed client awaits its
+      // response - so the delegate cancels the connection once it has nothing left to send.
       [strongSelf handleDisconnectForConnection:connection];
       return;
     }

package/WebDriverAgentLib/Utilities/FBConfiguration.h

@@ -368,6 +368,12 @@ typedef NS_ENUM(NSInteger, FBConfigurationKeyboardPreference) {
  */
 @property (atomic, assign) BOOL enforceCustomSnapshots;
 
+/**
+ * The identifier of the display targeted by screenshots.
+ * nil means the main display. Reset to nil for each new session.
+ */
+@property (atomic, copy, nullable) NSNumber *currentDisplayId;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/WebDriverAgentLib/Utilities/FBConfiguration.m

@@ -357,6 +357,7 @@ static NSString *const axSettingsClassName = @"AXSettings";
   FBSetCustomParameterForElementSnapshot(FBSnapshotMaxChildrenKey, @INT_MAX);
   self.useClearTextShortcut = YES;
   self.limitXpathContextScope = YES;
+  self.currentDisplayId = nil;
 #if !TARGET_OS_TV && !TARGET_OS_WATCH
   self.screenshotOrientationStorage = UIInterfaceOrientationUnknown;
 #endif

package/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/WebDriverAgentLib/Utilities/FBMjpegServer.m

@@ -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/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/WebDriverAgentLib/Utilities/FBScreen.m

@@ -7,6 +7,8 @@
  */
 
 #import "FBScreen.h"
+#import "FBConfiguration.h"
+#import "FBErrorBuilder.h"
 #import "XCUIElement+FBIsVisible.h"
 #import "FBXCodeCompatibility.h"
 #import "XCUIDevice.h"
@@ -40,6 +42,36 @@
   return result.copy;
 }
 
++ (nullable XCUIScreen *)screenWithDisplayID:(long long)displayID error:(NSError **)error
+{
+  NSArray<XCUIScreen *> *screens = [XCUIDevice.sharedDevice screensOrError:error];
+  if (nil == screens) {
+    return nil;
+  }
+  for (XCUIScreen *screen in screens) {
+    if (screen.displayID == displayID) {
+      return screen;
+    }
+  }
+  NSMutableArray<NSNumber *> *availableIDs = [NSMutableArray arrayWithCapacity:screens.count];
+  for (XCUIScreen *screen in screens) {
+    [availableIDs addObject:@(screen.displayID)];
+  }
+  [[FBErrorBuilder.builder withDescriptionFormat:@"No display with id %lld is available. Available display ids: [%@]",
+    displayID, [availableIDs componentsJoinedByString:@", "]]
+   buildError:error];
+  return nil;
+}
+
++ (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/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/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/WebDriverAgentLib/Utilities/FBSettings.h

@@ -46,5 +46,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/WebDriverAgentLib/Utilities/FBSettings.m

@@ -42,3 +42,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";

package/WebDriverAgentLib/Utilities/FBSettingsHandler.m

@@ -12,6 +12,7 @@
 #import "FBClassChainQueryParser.h"
 #import "FBCommandStatus.h"
 #import "FBConfiguration.h"
+#import "FBScreen.h"
 #import "FBSession.h"
 #import "FBSettings.h"
 
@@ -33,6 +34,7 @@ static NSSet<NSString *> *FBNilClearableSettingKeys(void)
       FB_SETTING_ACCEPT_ALERT_BUTTON_SELECTOR,
       FB_SETTING_DISMISS_ALERT_BUTTON_SELECTOR,
       FB_SETTING_AUTO_CLICK_ALERT_SELECTOR,
+      FB_SETTING_CURRENT_DISPLAY_ID,
       nil];
   });
   return keys;
@@ -190,6 +192,25 @@ static NSSet<NSString *> *FBNilClearableSettingKeys(void)
       FBConfiguration.sharedInstance.limitXpathContextScope = [value boolValue];
       return nil;
     };
+    map[FB_SETTING_CURRENT_DISPLAY_ID] = ^FBCommandStatus *(FBSession *session, id value) {
+      if (nil == value) {
+        FBConfiguration.sharedInstance.currentDisplayId = nil;
+        return nil;
+      }
+      if (![value isKindOfClass:NSNumber.class]
+          || CFGetTypeID((__bridge CFTypeRef)value) == CFBooleanGetTypeID()
+          || [value compare:@([value longLongValue])] != NSOrderedSame) {
+        return [FBCommandStatus invalidArgumentErrorWithMessage:@"currentDisplayId must be an integer display id returned by /wda/screens"
+                                                      traceback:nil];
+      }
+      NSError *error;
+      if (nil == [FBScreen screenWithDisplayID:[value longLongValue] error:&error]) {
+        return [FBCommandStatus invalidArgumentErrorWithMessage:error.localizedDescription
+                                                      traceback:nil];
+      }
+      FBConfiguration.sharedInstance.currentDisplayId = @([value longLongValue]);
+      return nil;
+    };
 #if !TARGET_OS_TV && !TARGET_OS_WATCH
     map[FB_SETTING_SCREENSHOT_ORIENTATION] = ^FBCommandStatus *(FBSession *session, id value) {
       NSError *error;
@@ -310,6 +331,9 @@ static NSSet<NSString *> *FBNilClearableSettingKeys(void)
     map[FB_SETTING_LIMIT_XPATH_CONTEXT_SCOPE] = ^id(FBSession *session) {
       return @(FBConfiguration.sharedInstance.limitXpathContextScope);
     };
+    map[FB_SETTING_CURRENT_DISPLAY_ID] = ^id(FBSession *session) {
+      return FBConfiguration.sharedInstance.currentDisplayId ?: @([FBScreen displayID]);
+    };
 #if !TARGET_OS_TV && !TARGET_OS_WATCH
     map[FB_SETTING_SCREENSHOT_ORIENTATION] = ^id(FBSession *session) {
       return FBConfiguration.sharedInstance.humanReadableScreenshotOrientation;