appium-webdriveragent 16.14.1 → 16.15.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [16.15.0](https://github.com/appium/WebDriverAgent/compare/v16.14.2...v16.15.0) (2026-10-12)
+
+### Features
+
+* add asAppUnderTest flag to /wda/apps/launch ([#1289](https://github.com/appium/WebDriverAgent/issues/1289)) ([f5c0688](https://github.com/appium/WebDriverAgent/commit/f5c068873ff6dcd1ce444d26246c102cc379d5bf))
+
+## [16.14.2](https://github.com/appium/WebDriverAgent/compare/v16.14.1...v16.14.2) (2026-10-08)
+
+### Bug Fixes
+
+* align Duo W3C actions and scrolling ([#1288](https://github.com/appium/WebDriverAgent/issues/1288)) ([104a31c](https://github.com/appium/WebDriverAgent/commit/104a31ce9aca53222bb312103f485b59f52f9894)), closes [#1294](https://github.com/appium/WebDriverAgent/issues/1294) [#1292](https://github.com/appium/WebDriverAgent/issues/1292)
+
 ## [16.14.1](https://github.com/appium/WebDriverAgent/compare/v16.14.0...v16.14.1) (2026-10-07)
 
 ### Bug Fixes

package/README.md

@@ -10,12 +10,12 @@
 WebDriverAgent is a [WebDriver server](https://w3c.github.io/webdriver/webdriver-spec.html) implementation for iOS that can be used to remote control iOS devices. It allows you to launch & kill applications, tap & scroll views or confirm view presence on a screen. This makes it a perfect tool for application end-to-end testing or general purpose device automation. It works by linking `XCTest.framework` and calling Apple's API to execute commands directly on a device. WebDriverAgent is developed for end-to-end testing and is successfully adopted by [Appium](http://appium.io) via [XCUITest driver](https://github.com/appium/appium-xcuitest-driver).
 
 ## Features
- * Both iOS and tvOS platforms are supported with devices & simulators
- * Implements most of [WebDriver Spec](https://w3c.github.io/webdriver/webdriver-spec.html)
- * Implements part of [Mobile JSON Wire Protocol Spec](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md)
- * USB support for devices is implemented via [appium-ios-device](https://github.com/appium/appium-ios-device) library and has zero dependencies on third-party tools.
- * Easy development cycle as it can be launched & debugged directly via Xcode
- * Use [Mac2Driver](https://github.com/appium/appium-mac2-driver) to automate macOS apps
+* Both iOS and tvOS platforms are supported with devices & simulators
+* Implements most of [WebDriver Spec](https://w3c.github.io/webdriver/webdriver-spec.html)
+* Implements part of [Mobile JSON Wire Protocol Spec](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md)
+* USB support for devices is implemented via [appium-ios-device](https://github.com/appium/appium-ios-device) library and has zero dependencies on third-party tools.
+* Easy development cycle as it can be launched & debugged directly via Xcode
+* Use [Mac2Driver](https://github.com/appium/appium-mac2-driver) to automate macOS apps
 
 ## Getting Started On This Repository
 
@@ -35,20 +35,21 @@ See [Hinge angle](docs/hinge-angle.md) for reading angles, sending simulated hin
 events, runtime requirements, and physical-device testing feedback.
 
 ## Known Issues
+
 If you are having some issues please checkout [wiki](https://github.com/facebook/WebDriverAgent/wiki/Common-Issues) first.
 
 ## For Contributors
+
 If you want to help us out, you are more than welcome to. However please make sure you have followed the guidelines in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Creating Bundles
 
 `npm run bundle`
 
-Then, you find `WebDriverAgentRunner-Runner-sim-<version>.zip`  for iOS and `WebDriverAgentRunner-Runner-tv_sim-<version>.zip` for tvOS files in the current directory.
+Then, you find `WebDriverAgentRunner-Runner-sim-<version>.zip` for iOS and `WebDriverAgentRunner-Runner-tv_sim-<version>.zip` for tvOS files in the current directory.
 
 ## License
 
 [`WebDriverAgent` is BSD-licensed](LICENSE).
 
-
 Have fun!

package/WebDriverAgent.xcodeproj/project.pbxproj

@@ -587,6 +587,7 @@
 		715AFAC11FFA29180053896D /* FBScreen.h in Headers */ = {isa = PBXBuildFile; fileRef = 715AFABF1FFA29180053896D /* FBScreen.h */; };
 		715AFAC21FFA29180053896D /* FBScreen.m in Sources */ = {isa = PBXBuildFile; fileRef = 715AFAC01FFA29180053896D /* FBScreen.m */; };
 		715AFAC41FFA2AAF0053896D /* FBScreenTests.m in Sources */ = {isa = PBXBuildFile; fileRef = 715AFAC31FFA2AAF0053896D /* FBScreenTests.m */; };
+		8EB95DF348A9438BBEAB4501 /* FBDisplayGestureTests.m in Sources */ = {isa = PBXBuildFile; fileRef = 8EB95DF348A9438BBEAB4502 /* FBDisplayGestureTests.m */; };
 		715D554B2229891B00524509 /* FBExceptionHandlerTests.m in Sources */ = {isa = PBXBuildFile; fileRef = 715D554A2229891B00524509 /* FBExceptionHandlerTests.m */; };
 		715D5773224DE02E00DA2D99 /* libxml2.tbd in Frameworks */ = {isa = PBXBuildFile; fileRef = 716C9345224D540C004B8542 /* libxml2.tbd */; };
 		715D5774224DE05400DA2D99 /* libxml2.tbd in Frameworks */ = {isa = PBXBuildFile; fileRef = 716C9345224D540C004B8542 /* libxml2.tbd */; };
@@ -1627,6 +1628,7 @@
 		715AFABF1FFA29180053896D /* FBScreen.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = FBScreen.h; sourceTree = "<group>"; };
 		715AFAC01FFA29180053896D /* FBScreen.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = FBScreen.m; sourceTree = "<group>"; };
 		715AFAC31FFA2AAF0053896D /* FBScreenTests.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = FBScreenTests.m; sourceTree = "<group>"; };
+		8EB95DF348A9438BBEAB4502 /* FBDisplayGestureTests.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = FBDisplayGestureTests.m; sourceTree = "<group>"; };
 		715D554A2229891B00524509 /* FBExceptionHandlerTests.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = FBExceptionHandlerTests.m; sourceTree = "<group>"; };
 		71649EC82518C19C0087F212 /* IOSTestSettings.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = IOSTestSettings.xcconfig; sourceTree = "<group>"; };
 		716C9342224D53A1004B8542 /* XCTest.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = XCTest.framework; path = Platforms/AppleTVOS.platform/Developer/Library/Frameworks/XCTest.framework; sourceTree = DEVELOPER_DIR; };
@@ -2704,6 +2706,7 @@
 				7119E1EB1E891F8600D0B125 /* FBPickerWheelSelectTests.m */,
 				71ACF5B7242F2FDC00F0AAD4 /* FBSafariAlertTests.m */,
 				715AFAC31FFA2AAF0053896D /* FBScreenTests.m */,
+				8EB95DF348A9438BBEAB4502 /* FBDisplayGestureTests.m */,
 				EE55B3261D1D54CF003AAAEC /* FBScrollingTests.m */,
 				7152EB2F1F41F9960047EEFF /* FBSessionIntegrationTests.m */,
 				EE26409A1D0EB5E8009BE6B0 /* FBTapTest.m */,
@@ -4861,6 +4864,7 @@
 				719CD8FF2126C90200C7D0C2 /* FBAutoAlertsHandlerTests.m in Sources */,
 				EE2202131ECC612200A29571 /* FBIntegrationTestCase.m in Sources */,
 				715AFAC41FFA2AAF0053896D /* FBScreenTests.m in Sources */,
+				8EB95DF348A9438BBEAB4501 /* FBDisplayGestureTests.m in Sources */,
 				71BB58EC2B96328700CB9BFE /* FBScreenRecordingRequest.m in Sources */,
 				EE22021E1ECC618900A29571 /* FBTapTest.m in Sources */,
 				71930C472066434000D3AFEC /* FBPasteboardTests.m in Sources */,

package/WebDriverAgentLib/Categories/XCUIElement+FBScrolling.m

@@ -9,7 +9,9 @@
 #import "XCUIElement+FBScrolling.h"
 
 #import "FBErrorBuilder.h"
+#import "FBExceptions.h"
 #import "FBLogger.h"
+#import "FBScreen.h"
 #import "FBMacros.h"
 #import "FBMathUtils.h"
 #import "FBXCodeCompatibility.h"
@@ -20,6 +22,7 @@
 #import "XCUIElement+FBUID.h"
 #import "XCUIApplication.h"
 #import "XCUICoordinate.h"
+#import "XCUIScreen.h"
 #import "XCUIElement+FBIsVisible.h"
 #import "XCUIElement+FBVisibleFrame.h"
 #import "XCUIElement.h"
@@ -35,14 +38,40 @@ const CGFloat FBScrollTouchProportion = 0.75f;
 
 #if !TARGET_OS_TV
 
+static void FBValidateScreenForScrolling(void)
+{
+  NSError *error = nil;
+  XCUIScreen *screen = [FBScreen currentScreenWithError:&error];
+  if (nil == screen) {
+    // Match active-app detection: never continue on a different coordinate space
+    // when the selected display is unavailable, including for void scroll APIs.
+    @throw [NSException exceptionWithName:FBInvalidArgumentException
+                                  reason:error.localizedDescription
+                                userInfo:nil];
+  }
+}
+
+static CGRect FBScrollFrameInApplication(CGRect frame, XCUIScreen *screen,
+                                        XCUIApplication *application)
+{
+#if !TARGET_OS_WATCH
+  // XCTest's visibleFrame is in portrait screen coordinates on both main and
+  // secondary displays. The live anchor's frame uses the app's orientation.
+  CGSize size = CGSizeMake(CGRectGetWidth(screen.bounds) / screen.scale,
+                           CGRectGetHeight(screen.bounds) / screen.scale);
+  frame = FBRectFromPortraitCoordinates(frame, size, application.interfaceOrientation);
+#endif
+  return frame;
+}
+
 @interface FBXCElementSnapshotWrapper (FBScrolling)
 
 - (BOOL)fb_scrollUpByNormalizedDistance:(CGFloat)distance anchorElement:(XCUIElement *)anchorElement;
 - (BOOL)fb_scrollDownByNormalizedDistance:(CGFloat)distance anchorElement:(XCUIElement *)anchorElement;
 - (BOOL)fb_scrollLeftByNormalizedDistance:(CGFloat)distance anchorElement:(XCUIElement *)anchorElement;
 - (BOOL)fb_scrollRightByNormalizedDistance:(CGFloat)distance anchorElement:(XCUIElement *)anchorElement;
-- (BOOL)fb_scrollByNormalizedVector:(CGVector)normalizedScrollVector anchorElement:(XCUIElement *)anchorElement;
-- (BOOL)fb_scrollByVector:(CGVector)vector anchorElement:(XCUIElement *)anchorElement error:(NSError **)error;
+- (BOOL)fb_scrollByNormalizedVector:(CGVector)normalizedScrollVector anchorElement:(XCUIElement *)anchorElement error:(NSError **)error;
+- (BOOL)fb_scrollByVector:(CGVector)vector inFrame:(CGRect)frame anchorElement:(XCUIElement *)anchorElement velocity:(CGFloat)velocity error:(NSError **)error;
 
 @end
 
@@ -126,6 +155,9 @@ static XCUIElement *FBLiveElementForSnapshot(id<FBXCElementSnapshot> snapshot, X
                                        scrollDirection:(FBXCUIElementScrollDirection)scrollDirection
                                                  error:(NSError **)error
 {
+  if (nil == [FBScreen currentScreenWithError:error]) {
+    return NO;
+  }
   FBXCElementSnapshotWrapper *prescrollSnapshot = [FBXCElementSnapshotWrapper ensureWrapped:[self fb_customSnapshot]];
 
   if (prescrollSnapshot.isWDVisible) {
@@ -202,7 +234,7 @@ static XCUIElement *FBLiveElementForSnapshot(id<FBXCElementSnapshot> snapshot, X
 
   // The scroll view's own identity is stable across scroll steps, so it only needs
   // to be resolved to a live element once, up front; its frame does not, since it can
-  // change across scroll steps (rotation, keyboard, dynamic layout).
+  // change across scroll steps (keyboard or dynamic layout).
   XCUIElement *scrollViewElement = FBLiveElementForSnapshot(scrollView, self.application);
   if (nil == scrollViewElement) {
     return
@@ -217,34 +249,27 @@ static XCUIElement *FBLiveElementForSnapshot(id<FBXCElementSnapshot> snapshot, X
   // Scrolling till cell is visible and get current value of frames
   while (![self fb_isEquivalentElementSnapshotVisible:prescrollSnapshot] && scrollCount < maxScrollCount) {
     BOOL didScroll;
+    __strong NSError *scrollError = nil;
     @autoreleasepool {
-      // Re-snapshotting the scroll view every step keeps its frame from drifting too far
-      // out of sync with the live anchor element's frame used to resolve touch points.
       scrollViewWrapped = [FBXCElementSnapshotWrapper ensureWrapped:[scrollViewElement fb_customSnapshot]];
-      if (targetCellIndex < visibleCellIndex) {
-        didScroll = scrollDirection == FBXCUIElementScrollDirectionVertical ?
-          [scrollViewWrapped fb_scrollUpByNormalizedDistance:normalizedScrollDistance
-                                                anchorElement:scrollViewElement] :
-          [scrollViewWrapped fb_scrollLeftByNormalizedDistance:normalizedScrollDistance
-                                                  anchorElement:scrollViewElement];
-      }
-      else {
-        didScroll = scrollDirection == FBXCUIElementScrollDirectionVertical ?
-          [scrollViewWrapped fb_scrollDownByNormalizedDistance:normalizedScrollDistance
-                                                  anchorElement:scrollViewElement] :
-          [scrollViewWrapped fb_scrollRightByNormalizedDistance:normalizedScrollDistance
-                                                   anchorElement:scrollViewElement];
-      }
+      CGFloat distance = targetCellIndex < visibleCellIndex ? normalizedScrollDistance : -normalizedScrollDistance;
+      CGVector vector = scrollDirection == FBXCUIElementScrollDirectionVertical
+        ? CGVectorMake(0, distance) : CGVectorMake(distance, 0);
+      NSError *stepError = nil;
+      didScroll = [scrollViewWrapped fb_scrollByNormalizedVector:vector
+                                                   anchorElement:scrollViewElement
+                                                           error:&stepError];
+      scrollError = stepError;
       scrollCount++;
       // Wait for scroll animation
       [self fb_waitUntilStableWithTimeout:FBConfiguration.sharedInstance.animationCoolOffTimeout];
     }
     // The `error` out-param must not be written from inside the autorelease pool above.
     if (!didScroll) {
-      return
-      [[[FBErrorBuilder builder]
-        withDescriptionFormat:@"Failed to scroll '%@': its frame is empty", self.description]
-       buildError:error];
+      if (error) {
+        *error = scrollError;
+      }
+      return NO;
     }
   }
 
@@ -260,14 +285,39 @@ static XCUIElement *FBLiveElementForSnapshot(id<FBXCElementSnapshot> snapshot, X
   // Trying fb_cachedSnapshot first
   FBXCElementSnapshotWrapper *targetCellSnapshotWrapped = [FBXCElementSnapshotWrapper ensureWrapped:[self fb_customSnapshot]];
   targetCellSnapshot = [targetCellSnapshotWrapped fb_parentCellSnapshot];
-  CGRect visibleFrame = [FBXCElementSnapshotWrapper ensureWrapped:targetCellSnapshot].fb_visibleFrame;
-
-  CGVector scrollVector = CGVectorMake(visibleFrame.size.width - targetCellSnapshot.frame.size.width,
-                                       visibleFrame.size.height - targetCellSnapshot.frame.size.height
-                                       );
+  XCUIScreen *screen = [FBScreen currentScreenWithError:error];
+  if (nil == screen) {
+    return NO;
+  }
+  CGRect visibleFrame = FBScrollFrameInApplication(
+    [FBXCElementSnapshotWrapper ensureWrapped:targetCellSnapshot].fb_visibleFrame, screen, self.application);
+
+  CGRect targetFrame = targetCellSnapshot.frame;
+  // A cell can be clipped at the leading edge after a drag. Move back toward
+  // that edge instead of always scrolling down/right and hiding it further.
+  CGVector scrollVector = CGVectorMake(
+    CGRectGetMinX(visibleFrame) > CGRectGetMinX(targetFrame)
+      ? CGRectGetMinX(visibleFrame) - CGRectGetMinX(targetFrame)
+      : CGRectGetMaxX(visibleFrame) - CGRectGetMaxX(targetFrame),
+    CGRectGetMinY(visibleFrame) > CGRectGetMinY(targetFrame)
+      ? CGRectGetMinY(visibleFrame) - CGRectGetMinY(targetFrame)
+      : CGRectGetMaxY(visibleFrame) - CGRectGetMaxY(targetFrame));
+  // UIKit consumes the start of a drag before recognizing a pan. Include that
+  // margin so a small clipped edge is actually moved into view.
+  if (fabs(scrollVector.dx) > 1) {
+    scrollVector.dx += copysign(FBFuzzyPointThreshold, scrollVector.dx);
+  }
+  if (fabs(scrollVector.dy) > 1) {
+    scrollVector.dy += copysign(FBFuzzyPointThreshold, scrollVector.dy);
+  }
+  // Short fast corrections can turn into a flick and overshoot the target.
+  CGFloat velocity = MIN(FBTouchVelocity, MAX(fabs(scrollVector.dx), fabs(scrollVector.dy)) / FBTouchEventDelay);
   scrollViewWrapped = [FBXCElementSnapshotWrapper ensureWrapped:[scrollViewElement fb_customSnapshot]];
+  CGRect scrollingFrame = FBScrollFrameInApplication(scrollViewWrapped.visibleFrame, screen, self.application);
   return [scrollViewWrapped fb_scrollByVector:scrollVector
+                                       inFrame:scrollingFrame
                                 anchorElement:scrollViewElement
+                                     velocity:velocity
                                         error:error];
 }
 
@@ -296,64 +346,73 @@ static XCUIElement *FBLiveElementForSnapshot(id<FBXCElementSnapshot> snapshot, X
 
 @implementation FBXCElementSnapshotWrapper (FBScrolling)
 
-- (CGRect)scrollingFrame
-{
-  return self.visibleFrame;
-}
-
 - (BOOL)fb_scrollUpByNormalizedDistance:(CGFloat)distance
                            anchorElement:(XCUIElement *)anchorElement
 {
-  return [self fb_scrollByNormalizedVector:CGVectorMake(0.0, distance) anchorElement:anchorElement];
+  FBValidateScreenForScrolling();
+  return [self fb_scrollByNormalizedVector:CGVectorMake(0.0, distance) anchorElement:anchorElement error:nil];
 }
 
 - (BOOL)fb_scrollDownByNormalizedDistance:(CGFloat)distance
                              anchorElement:(XCUIElement *)anchorElement
 {
-  return [self fb_scrollByNormalizedVector:CGVectorMake(0.0, -distance) anchorElement:anchorElement];
+  FBValidateScreenForScrolling();
+  return [self fb_scrollByNormalizedVector:CGVectorMake(0.0, -distance) anchorElement:anchorElement error:nil];
 }
 
 - (BOOL)fb_scrollLeftByNormalizedDistance:(CGFloat)distance
                              anchorElement:(XCUIElement *)anchorElement
 {
-  return [self fb_scrollByNormalizedVector:CGVectorMake(distance, 0.0) anchorElement:anchorElement];
+  FBValidateScreenForScrolling();
+  return [self fb_scrollByNormalizedVector:CGVectorMake(distance, 0.0) anchorElement:anchorElement error:nil];
 }
 
 - (BOOL)fb_scrollRightByNormalizedDistance:(CGFloat)distance
                               anchorElement:(XCUIElement *)anchorElement
 {
-  return [self fb_scrollByNormalizedVector:CGVectorMake(-distance, 0.0) anchorElement:anchorElement];
+  FBValidateScreenForScrolling();
+  return [self fb_scrollByNormalizedVector:CGVectorMake(-distance, 0.0) anchorElement:anchorElement error:nil];
 }
 
 - (BOOL)fb_scrollByNormalizedVector:(CGVector)normalizedScrollVector
                        anchorElement:(XCUIElement *)anchorElement
+                               error:(NSError **)error
 {
-  CGVector scrollVector = CGVectorMake(CGRectGetWidth(self.scrollingFrame) * normalizedScrollVector.dx,
-                                       CGRectGetHeight(self.scrollingFrame) * normalizedScrollVector.dy
+  XCUIScreen *screen = [FBScreen currentScreenWithError:error];
+  if (nil == screen) {
+    return NO;
+  }
+  CGRect frame = FBScrollFrameInApplication(self.visibleFrame, screen, anchorElement.application);
+  CGVector scrollVector = CGVectorMake(CGRectGetWidth(frame) * normalizedScrollVector.dx,
+                                       CGRectGetHeight(frame) * normalizedScrollVector.dy
                                        );
-  return [self fb_scrollByVector:scrollVector anchorElement:anchorElement error:nil];
+  return [self fb_scrollByVector:scrollVector inFrame:frame anchorElement:anchorElement velocity:FBTouchVelocity error:error];
 }
 
 - (BOOL)fb_scrollByVector:(CGVector)vector
+                     inFrame:(CGRect)frame
              anchorElement:(XCUIElement *)anchorElement
+                  velocity:(CGFloat)velocity
                      error:(NSError **)error
 {
-  CGVector scrollBoundingVector = CGVectorMake(
-                                               CGRectGetWidth(self.scrollingFrame) * FBScrollTouchProportion,
-                                               CGRectGetHeight(self.scrollingFrame) * FBScrollTouchProportion
-                                               );
-  scrollBoundingVector.dx = (CGFloat)floor(copysign(scrollBoundingVector.dx, vector.dx));
-  scrollBoundingVector.dy = (CGFloat)floor(copysign(scrollBoundingVector.dy, vector.dy));
-
+  // Keep the vector and clipped frame in the same coordinate space throughout
+  // this multi-drag gesture. Rotation or folding during a gesture is unsupported.
   NSInteger preciseScrollAttemptsCount = 20;
   CGVector CGZeroVector = CGVectorMake(0, 0);
   BOOL shouldFinishScrolling = NO;
   while (!shouldFinishScrolling) {
+    CGVector scrollBoundingVector = CGVectorMake(
+      (CGFloat)floor(copysign(CGRectGetWidth(frame) * FBScrollTouchProportion, vector.dx)),
+      (CGFloat)floor(copysign(CGRectGetHeight(frame) * FBScrollTouchProportion, vector.dy)));
     CGVector scrollVector = CGVectorMake(fabs(vector.dx) > fabs(scrollBoundingVector.dx) ? scrollBoundingVector.dx : vector.dx,
                                          fabs(vector.dy) > fabs(scrollBoundingVector.dy) ? scrollBoundingVector.dy : vector.dy);
     vector = CGVectorMake(vector.dx - scrollVector.dx, vector.dy - scrollVector.dy);
     shouldFinishScrolling = FBVectorFuzzyEqualToVector(vector, CGZeroVector, 1) || --preciseScrollAttemptsCount <= 0;
-    if (![self fb_scrollAncestorScrollViewByVectorWithinScrollViewFrame:scrollVector anchorElement:anchorElement error:error]){
+    if (![self fb_scrollAncestorScrollViewByVectorWithinScrollViewFrame:scrollVector
+                                                               inFrame:frame
+                                                         anchorElement:anchorElement
+                                                              velocity:velocity
+                                                                 error:error]) {
       return NO;
     }
   }
@@ -370,10 +429,11 @@ static XCUIElement *FBLiveElementForSnapshot(id<FBXCElementSnapshot> snapshot, X
 }
 
 - (BOOL)fb_scrollAncestorScrollViewByVectorWithinScrollViewFrame:(CGVector)vector
+                                                               inFrame:(CGRect)scrollingFrame
                                                      anchorElement:(XCUIElement *)anchorElement
+                                                          velocity:(CGFloat)velocity
                                                              error:(NSError **)error
 {
-  CGRect scrollingFrame = self.scrollingFrame;
   // wdFrame matches scrollingFrame's coordinate space; raw .frame can be pre-scaled or
   // dimension-swapped and drift out of sync with it (appium/appium#16185).
   CGRect anchorFrame = anchorElement.wdFrame;
@@ -395,7 +455,7 @@ static XCUIElement *FBLiveElementForSnapshot(id<FBXCElementSnapshot> snapshot, X
 
   [startCoordinate pressForDuration:FBTouchEventDelay
                thenDragToCoordinate:endCoordinate
-                       withVelocity:FBTouchVelocity
+                       withVelocity:velocity
                 thenHoldForDuration:FBTouchEventDelay];
   return YES;
 }

package/WebDriverAgentLib/Commands/FBCustomCommands.m

@@ -174,7 +174,14 @@
                                  CGRectGetHeight(screen.bounds) / screen.scale);
 #if !TARGET_OS_TV && !TARGET_OS_WATCH
   XCUIApplication *activeApp = request.session ? request.session.activeApplication : XCUIApplication.fb_activeApplication;
-  screenSize = FBAdjustDimensionsForApplication(screenSize, activeApp.interfaceOrientation);
+  UIInterfaceOrientation orientation = activeApp.interfaceOrientation;
+  // Screen bounds describe the panel's native orientation. Some physical iPads
+  // expose landscape-native bounds even while the application is in portrait.
+  // Normalize the full screen separately from compatibility-mode app frames.
+  if (UIInterfaceOrientationIsPortrait(orientation) && screenSize.width > screenSize.height) {
+    screenSize = CGSizeMake(screenSize.height, screenSize.width);
+  }
+  screenSize = FBAdjustDimensionsForApplication(screenSize, orientation);
 #endif
 
   // SpringBoard can expose hidden status bars belonging to other displays, and

package/WebDriverAgentLib/Commands/FBElementCommands.m

@@ -9,6 +9,8 @@
 #import "FBElementCommands.h"
 
 #import "FBConfiguration.h"
+#import "FBScreen.h"
+#import "XCUIScreen.h"
 #import "FBKeyboard.h"
 #import "FBRoute.h"
 #import "FBRouteRequest.h"
@@ -698,7 +700,34 @@ static const NSInteger DEFAULT_MAX_PICKER_ATTEMPTS = 25;
                                                   element:(XCUIElement *)element
                                                     error:(NSError **)error
 {
-  return FBCoordinateWithAnchorOffset(element, CGVectorMake(0, 0), offset, error);
+  if (element.elementType != XCUIElementTypeApplication) {
+    return FBCoordinateWithAnchorOffset(element, CGVectorMake(0, 0), offset, error);
+  }
+  XCUIScreen *screen = [FBScreen currentScreenWithError:error];
+  if (nil == screen) {
+    return nil;
+  }
+  if (screen.displayID == XCUIScreen.mainScreen.displayID) {
+    return FBCoordinateWithAnchorOffset(element, CGVectorMake(0, 0), offset, error);
+  }
+  // Application-root coordinates are rotated using the main display on Duo.
+  // A window coordinate keeps XCTest's display affinity and rotation intact.
+  // It is only a coordinate anchor, not a hit-test boundary. Preserve edge and
+  // outside offsets just as on the main display; XCTest handles their delivery.
+  CGPoint point = CGPointMake(offset.dx, offset.dy);
+  for (XCUIElement *window in [element childrenMatchingType:XCUIElementTypeWindow].allElementsBoundByIndex) {
+    // Resolve the window before reading its display affinity: an unresolved
+    // element may report displayID == 0.
+    (void)window.frame;
+    CGRect frame = window.wdFrame;
+    if (window.screen.displayID == screen.displayID && !CGRectIsEmpty(frame)) {
+      return FBCoordinateWithAnchorOffset(window, CGVectorMake(0, 0),
+        CGVectorMake(point.x - frame.origin.x, point.y - frame.origin.y), error);
+    }
+  }
+  [[[FBErrorBuilder builder] withDescriptionFormat:@"No non-empty application window on display %lld is available as a coordinate anchor", screen.displayID]
+    buildError:error];
+  return nil;
 }
 
 /**

package/WebDriverAgentLib/Commands/FBSessionCommands.m

@@ -131,7 +131,8 @@
   [request.session launchApplicationWithBundleId:(id)request.arguments[@"bundleId"]
                          shouldWaitForQuiescence:request.arguments[@"shouldWaitForQuiescence"]
                                        arguments:request.arguments[@"arguments"]
-                                     environment:request.arguments[@"environment"]];
+                                     environment:request.arguments[@"environment"]
+                          asApplicationUnderTest:[request.arguments[@"asAppUnderTest"] boolValue]];
   return FBResponseWithOK();
 }
 

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentLib/Routing/FBSession.h

@@ -107,6 +107,28 @@ extern NSString* const FBSessionWasKilledNotification;
                                          arguments:(nullable NSArray<NSString *> *)arguments
                                        environment:(nullable NSDictionary <NSString *, NSString *> *)environment;
 
+/**
+ Launch an application with given bundle identifier in scope of current session
+ and optionally make it the application under test of this session.
+
+ @param bundleIdentifier Valid bundle identifier of the application to be launched
+ @param shouldWaitForQuiescence whether to wait for quiescence on application startup.
+ If not provided then the setting of the current application under test is inherited.
+ If there is no application under test yet then quiescence is only awaited if asApplicationUnderTest is YES
+ @param arguments The optional array of application command line arguments. The arguments are going to be applied if the application was not running before.
+ @param environment The optional dictionary of environment variables for the application, which is going to be executed. The environment variables are going to be applied if the application was not running before.
+ @param asApplicationUnderTest If YES then the launched application replaces the current application under test
+ of the session (if any), the same way as if it was launched on session startup: other applications launched later
+ inherit its quiescence setting, system alerts over it are respected, its unexpected termination is reported as a crash
+ and it gets terminated on session deletion if shouldTerminateApp is enabled
+ @return The application instance
+ */
+- (XCUIApplication *)launchApplicationWithBundleId:(NSString *)bundleIdentifier
+                           shouldWaitForQuiescence:(nullable NSNumber *)shouldWaitForQuiescence
+                                         arguments:(nullable NSArray<NSString *> *)arguments
+                                       environment:(nullable NSDictionary <NSString *, NSString *> *)environment
+                            asApplicationUnderTest:(BOOL)asApplicationUnderTest;
+
 /**
  Activate an application with given bundle identifier in scope of current session.
  !This method is only available since Xcode9 SDK

package/WebDriverAgentLib/Routing/FBSession.m

@@ -43,7 +43,8 @@ static const NSTimeInterval FB_KILL_WAIT_TIMEOUT_SEC = 35.;
 NSString *const FBSessionWasKilledNotification = @"FBSessionWasKilledNotification";
 
 @interface FBSession ()
-@property (nullable, nonatomic) XCUIApplication *testedApplication;
+// Atomic, since /wda/apps/launch may replace it while a concurrent DELETE /session reads it in -kill
+@property (nullable, atomic) XCUIApplication *testedApplication;
 @property (nonatomic) BOOL isTestedApplicationExpectedToRun;
 @property (nonatomic) BOOL shouldAppsWaitForQuiescence;
 @property (nonatomic, nullable) FBAlertsMonitor *alertsMonitor;
@@ -386,11 +387,27 @@ static NSUInteger _committedTerminationCount = 0;
                            shouldWaitForQuiescence:(nullable NSNumber *)shouldWaitForQuiescence
                                          arguments:(nullable NSArray<NSString *> *)arguments
                                        environment:(nullable NSDictionary <NSString *, NSString *> *)environment
+{
+  return [self launchApplicationWithBundleId:bundleIdentifier
+                     shouldWaitForQuiescence:shouldWaitForQuiescence
+                                   arguments:arguments
+                                 environment:environment
+                      asApplicationUnderTest:NO];
+}
+
+- (XCUIApplication *)launchApplicationWithBundleId:(NSString *)bundleIdentifier
+                           shouldWaitForQuiescence:(nullable NSNumber *)shouldWaitForQuiescence
+                                         arguments:(nullable NSArray<NSString *> *)arguments
+                                       environment:(nullable NSDictionary <NSString *, NSString *> *)environment
+                            asApplicationUnderTest:(BOOL)asApplicationUnderTest
 {
   XCUIApplication *app = [self makeApplicationWithBundleId:bundleIdentifier];
   if (nil == shouldWaitForQuiescence) {
-    // Iherit the quiescence check setting from the main app under test by default
-    app.fb_shouldWaitForQuiescence = nil != self.testedApplication && self.shouldAppsWaitForQuiescence;
+    // Iherit the quiescence check setting from the main app under test by default.
+    // The first app under test of the session waits for quiescence, as it would on session startup
+    app.fb_shouldWaitForQuiescence = nil == self.testedApplication
+      ? asApplicationUnderTest
+      : self.shouldAppsWaitForQuiescence;
   } else {
     app.fb_shouldWaitForQuiescence = [shouldWaitForQuiescence boolValue];
   }
@@ -401,6 +418,11 @@ static NSUInteger _committedTerminationCount = 0;
   } else {
     [app activate];
   }
+  if (asApplicationUnderTest) {
+    [FBLogger logFmt:@"The application '%@' is set as the application under test", bundleIdentifier];
+    self.testedApplication = app;
+    self.shouldAppsWaitForQuiescence = app.fb_shouldWaitForQuiescence;
+  }
   if ([app fb_isSameAppAs:self.testedApplication]) {
     self.isTestedApplicationExpectedToRun = YES;
   }

package/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/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