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

package/drivers/ios/WebDriverAgent/WebDriverAgentTests/UnitTests/FBSessionTests.m

@@ -9,9 +9,67 @@
 #import <XCTest/XCTest.h>
 
 #import "FBSession.h"
+#import "FBSession-Private.h"
+#import "FBExceptions.h"
 #import "FBConfiguration.h"
 #import "XCUIApplicationDouble.h"
 
+@interface FBSession (SystemApplicationTests)
+- (BOOL)fb_isApplicationSameAsSystemApp:(XCUIApplication *)application timeout:(NSTimeInterval)timeout;
+@end
+
+static id (^FBSystemApplicationLookup)(void);
+
+// Run teardown at the exact point where launch has started but the AUT has
+// not yet been published. No wall-clock sleeps or simulator launch timing.
+@interface FBAUTLaunchApplicationDouble : XCUIApplicationDouble
+@property (nonatomic, copy) void (^duringLaunch)(void);
+@property (nonatomic, copy) NSArray *launchArguments;
+@property (nonatomic, copy) NSDictionary *launchEnvironment;
+@property (nonatomic) BOOL didLaunch;
+@end
+
+@implementation FBAUTLaunchApplicationDouble
++ (id)fb_systemApplication
+{
+  return FBSystemApplicationLookup ? FBSystemApplicationLookup() : nil;
+}
+- (void)launch
+{
+  self.didLaunch = YES;
+  if (self.duringLaunch) {
+    self.duringLaunch();
+  }
+}
+- (BOOL)fb_isSameAppAs:(id)application
+{
+  return self == application;
+}
+@end
+
+@interface FBAUTTerminationFailureApplicationDouble : FBAUTLaunchApplicationDouble
+@property (nonatomic) BOOL didAttemptTermination;
+@end
+
+@implementation FBAUTTerminationFailureApplicationDouble
+- (void)terminate
+{
+  self.didAttemptTermination = YES;
+  @throw [NSException exceptionWithName:@"TerminationFailure" reason:nil userInfo:nil];
+}
+@end
+
+@interface FBAUTLaunchSession : FBSession
+@property (nonatomic, strong) FBAUTLaunchApplicationDouble *launchApplication;
+@end
+
+@implementation FBAUTLaunchSession
+- (XCUIApplication *)makeApplicationWithBundleId:(NSString *)bundleIdentifier
+{
+  return (id)self.launchApplication;
+}
+@end
+
 @interface FBSessionTests : XCTestCase
 @property (nonatomic, strong) FBSession *session;
 @property (nonatomic, strong) XCUIApplication *testedApplication;
@@ -31,6 +89,10 @@
 
 - (void)tearDown
 {
+  if ([self.session isKindOfClass:FBAUTLaunchSession.class]) {
+    ((FBAUTLaunchSession *)self.session).launchApplication.duringLaunch = nil;
+  }
+  FBSystemApplicationLookup = nil;
   [self.session kill];
   FBConfiguration.sharedInstance.shouldTerminateApp = self.shouldTerminateAppValue;
   [super tearDown];
@@ -64,4 +126,143 @@
   XCTAssertNil([FBSession activeSession]);
 }
 
+- (FBAUTLaunchApplicationDouble *)prepareAUTLaunch
+{
+  FBAUTLaunchSession *session = [FBAUTLaunchSession new];
+  session.identifier = NSUUID.UUID.UUIDString;
+  session.launchApplication = [FBAUTLaunchApplicationDouble new];
+  [FBSession markSessionActive:session];
+  self.session = session;
+  return session.launchApplication;
+}
+
+- (void)launchAsAUT
+{
+  [self.session launchApplicationWithBundleId:@"com.facebook.awesome"
+                    shouldWaitForQuiescence:nil
+                                  arguments:nil
+                                environment:nil
+                     asApplicationUnderTest:YES];
+}
+
+- (void)testCompletedLaunchRegistersAUT
+{
+  FBAUTLaunchApplicationDouble *app = [self prepareAUTLaunch];
+  XCTAssertNoThrow([self launchAsAUT]);
+  XCTAssertEqual([self.session valueForKey:@"testedApplication"], app);
+  XCTAssertFalse(app.didTerminate);
+}
+
+- (void)testDeletedSessionCleansUpInFlightAUTLaunch
+{
+  FBAUTLaunchApplicationDouble *app = [self prepareAUTLaunch];
+  FBConfiguration.sharedInstance.shouldTerminateApp = YES;
+  FBSession *session = self.session;
+  app.duringLaunch = ^{ [session kill]; };
+  XCTAssertThrowsSpecificNamed([self launchAsAUT], NSException,
+                              FBSessionDoesNotExistException);
+  XCTAssertTrue(app.didTerminate);
+  XCTAssertNil([self.session valueForKey:@"testedApplication"]);
+  XCTAssertNil(FBSession.activeSession);
+}
+
+- (void)testTerminationFailurePreservesDeletedSessionErrorAndReleasesClaim
+{
+  [self prepareAUTLaunch];
+  FBAUTTerminationFailureApplicationDouble *app = [FBAUTTerminationFailureApplicationDouble new];
+  ((FBAUTLaunchSession *)self.session).launchApplication = app;
+  FBConfiguration.sharedInstance.shouldTerminateApp = YES;
+  FBSession *session = self.session;
+  app.duringLaunch = ^{ [session kill]; };
+
+  XCTAssertThrowsSpecificNamed([self launchAsAUT], NSException, FBSessionDoesNotExistException);
+  XCTAssertTrue(app.didAttemptTermination);
+  XCTAssertNil([self.session valueForKey:@"testedApplication"]);
+  XCTAssertNil(FBSession.activeSession);
+
+  // Creating the next session must succeed even when cleanup termination throws.
+  // A leaked generation claim would make this fail with a session creation error.
+  FBSession *replacement = nil;
+  XCTAssertNoThrow(replacement = [FBSession initWithApplication:nil]);
+  XCTAssertNotNil(replacement);
+  XCTAssertEqual(FBSession.activeSession, replacement);
+  [replacement kill];
+}
+
+- (void)testDeletedSessionPreservesAppWhenTerminationIsDisabled
+{
+  FBAUTLaunchApplicationDouble *app = [self prepareAUTLaunch];
+  FBSession *session = self.session;
+  app.duringLaunch = ^{ [session kill]; };
+  XCTAssertThrowsSpecificNamed([self launchAsAUT], NSException,
+                              FBSessionDoesNotExistException);
+  XCTAssertFalse(app.didTerminate);
+}
+
+- (void)testAbandonedAUTLaunchDoesNotTerminateReplacementSessionApp
+{
+  FBAUTLaunchApplicationDouble *app = [self prepareAUTLaunch];
+  FBConfiguration.sharedInstance.shouldTerminateApp = YES;
+  FBSession *session = self.session;
+  __block FBSession *replacement;
+  app.duringLaunch = ^{
+    [session kill];
+    replacement = [FBSession initWithApplication:(id)app];
+  };
+  XCTAssertThrowsSpecificNamed([self launchAsAUT], NSException,
+                              FBSessionDoesNotExistException);
+  XCTAssertFalse(app.didTerminate);
+  XCTAssertEqual(FBSession.activeSession, replacement);
+  [replacement kill];
+}
+
+- (void)testAUTLaunchRejectsAnAlreadyDeletedSession
+{
+  FBAUTLaunchApplicationDouble *app = [self prepareAUTLaunch];
+  [self.session kill];
+  XCTAssertThrowsSpecificNamed([self launchAsAUT], NSException,
+                              FBSessionDoesNotExistException);
+  XCTAssertFalse(app.didLaunch);
+}
+
+- (void)testSystemApplicationCheckUsesSuppliedApplication
+{
+  FBAUTLaunchApplicationDouble *app = [self prepareAUTLaunch];
+  FBSystemApplicationLookup = ^id { return app; };
+  XCTAssertTrue([self.session fb_isApplicationSameAsSystemApp:(id)app timeout:1.]);
+  FBSystemApplicationLookup = ^id { return nil; };
+  XCTAssertFalse([self.session fb_isApplicationSameAsSystemApp:(id)app timeout:1.]);
+}
+
+- (void)testSystemApplicationLookupExceptionSkipsTermination
+{
+  FBAUTLaunchApplicationDouble *app = [self prepareAUTLaunch];
+  FBConfiguration.sharedInstance.shouldTerminateApp = YES;
+  FBSession *session = self.session;
+  app.duringLaunch = ^{ [session kill]; };
+  FBSystemApplicationLookup = ^id {
+    @throw [NSException exceptionWithName:@"LookupFailure" reason:nil userInfo:nil];
+  };
+  XCTAssertThrowsSpecificNamed([self launchAsAUT], NSException, FBSessionDoesNotExistException);
+  XCTAssertFalse(app.didTerminate);
+}
+
+- (void)testSystemApplicationLookupTimeoutSkipsTermination
+{
+  FBAUTLaunchApplicationDouble *app = [self prepareAUTLaunch];
+  dispatch_semaphore_t releaseLookup = dispatch_semaphore_create(0);
+  XCTestExpectation *finished = [self expectationWithDescription:@"System application lookup finished"];
+  FBSystemApplicationLookup = ^id {
+    dispatch_semaphore_wait(releaseLookup, DISPATCH_TIME_FOREVER);
+    [finished fulfill];
+    return nil;
+  };
+  @try {
+    XCTAssertTrue([self.session fb_isApplicationSameAsSystemApp:(id)app timeout:0.01]);
+  } @finally {
+    dispatch_semaphore_signal(releaseLookup);
+    [self waitForExpectationsWithTimeout:5. handler:nil];
+  }
+}
+
 @end

package/drivers/ios/WebDriverAgent/WebDriverAgentTests/UnitTests/FBXPathTests.m

@@ -16,11 +16,112 @@
 #import "FBXCElementSnapshotWrapper+Helpers.h"
 #import "XCTestPrivateSymbols.h"
 
+// libxml's node callbacks are thread-local; restore any existing callbacks after each probe.
+static __thread NSUInteger FBReviewCreatedDocs;
+static __thread NSUInteger FBReviewFreedDocs;
+static __thread xmlRegisterNodeFunc FBReviewPreviousRegister;
+static __thread xmlDeregisterNodeFunc FBReviewPreviousDeregister;
+
+static void FBReviewRegisterNode(xmlNodePtr node)
+{
+  if (node->type == XML_DOCUMENT_NODE) { FBReviewCreatedDocs++; }
+  if (NULL != FBReviewPreviousRegister) { FBReviewPreviousRegister(node); }
+}
+
+static void FBReviewDeregisterNode(xmlNodePtr node)
+{
+  if (node->type == XML_DOCUMENT_NODE) { FBReviewFreedDocs++; }
+  if (NULL != FBReviewPreviousDeregister) { FBReviewPreviousDeregister(node); }
+}
+
+@interface FBThrowingLabelSnapshot : XCElementSnapshotDouble
+@end
+@implementation FBThrowingLabelSnapshot
+- (NSString *)label
+{
+  @throw [NSException exceptionWithName:@"SnapshotAttributeFailure" reason:@"test" userInfo:nil];
+}
+@end
+
+@interface FBTraversalSnapshot : XCElementSnapshotDouble
+@property (nonatomic, copy) NSArray *childSnapshots;
+@property (nonatomic, weak) FBTraversalSnapshot *parentSnapshot;
+@property (nonatomic) NSUInteger childrenReads;
+@property (nonatomic) NSUInteger frameReads;
+@end
+@implementation FBTraversalSnapshot
+- (NSArray *)children { self.childrenReads++; return self.childSnapshots ?: @[]; }
+- (id)parent { return self.parentSnapshot; }
+- (CGRect)frame { self.frameReads++; return CGRectMake(1, 2, 3, 4); }
+@end
+
 @interface FBXPathTests : XCTestCase
 @end
 
 @implementation FBXPathTests
 
+- (void)testSerializationVisitsSiblingListAndFrameOnce
+{
+  FBTraversalSnapshot *root = [FBTraversalSnapshot new];
+  NSMutableArray *children = [NSMutableArray array];
+  for (NSUInteger index = 0; index < 64; index++) {
+    FBTraversalSnapshot *child = [FBTraversalSnapshot new];
+    child.parentSnapshot = root;
+    [children addObject:child];
+  }
+  root.childSnapshots = children;
+  NSString *query = @"//*[@index >= 0 and @x=1 and @y=2 and @width=3 and @height=4]";
+  xmlDocPtr doc = [self documentForSnapshot:root query:query];
+  @try {
+    XCTAssertEqual(root.childrenReads, 1u);
+    XCTAssertEqual(root.frameReads, 1u);
+    for (FBTraversalSnapshot *child in children) {
+      XCTAssertEqual(child.frameReads, 1u);
+    }
+    XCTAssertEqualObjects([self xpathStringResultForQuery:@"count(//*[@index=63])" document:doc], @"1");
+  } @finally {
+    xmlFreeDoc(doc);
+  }
+}
+
+- (void)testDirectXmlWriterPreservesEscapingAndFormatting
+{
+  XCElementSnapshotDouble *snapshot = [XCElementSnapshotDouble new];
+  snapshot.label = @"line one\nline two\t& < > \" йоло";
+  snapshot.value = @"value";
+  NSString *expected = [[self xmlStringWithElement:(id)snapshot xpathQuery:nil excludingAttributes:nil]
+    stringByReplacingOccurrencesOfString:@" private_indexPath=\"top\"" withString:@""];
+  NSString *actual = [FBXPath xmlStringWithRootElement:(id)snapshot options:nil];
+  XCTAssertEqualObjects(actual, expected);
+}
+
+- (void)testXmlDocumentsAreFreedWhenSnapshotAttributesThrow
+{
+  for (NSNumber *isLookup in @[@NO, @YES]) {
+    FBReviewCreatedDocs = 0;
+    FBReviewFreedDocs = 0;
+    FBReviewPreviousRegister = xmlRegisterNodeDefault(FBReviewRegisterNode);
+    FBReviewPreviousDeregister = xmlDeregisterNodeDefault(FBReviewDeregisterNode);
+    @try {
+      id<FBElement> snapshot = (id)[FBThrowingLabelSnapshot new];
+      if (isLookup.boolValue) {
+        XCTAssertThrowsSpecificNamed([FBXPath matchesWithRootElement:snapshot forQuery:@"//*[@label]"],
+                                     NSException, @"SnapshotAttributeFailure");
+      } else {
+        XCTAssertThrowsSpecificNamed([FBXPath xmlStringWithRootElement:snapshot options:nil],
+                                     NSException, @"SnapshotAttributeFailure");
+      }
+      if (isLookup.boolValue) {
+        XCTAssertGreaterThan(FBReviewCreatedDocs, 0u);
+      }
+      XCTAssertEqual(FBReviewCreatedDocs, FBReviewFreedDocs);
+    } @finally {
+      xmlRegisterNodeDefault(FBReviewPreviousRegister);
+      xmlDeregisterNodeDefault(FBReviewPreviousDeregister);
+    }
+  }
+}
+
 - (NSString *)xmlStringWithElement:(id<FBXCElementSnapshot>)snapshot
                         xpathQuery:(nullable NSString *)query
                excludingAttributes:(nullable NSArray<NSString *> *)excludedAttributes

package/drivers/ios/WebDriverAgent/docs/hinge-angle.md

@@ -0,0 +1,54 @@
+# Hinge angle
+
+These endpoints use runtime capability checks on both simulators and physical
+devices, rather than restricting access to a particular device model or to
+Simulator builds. Reading an angle and injecting a simulated angle have separate
+requirements.
+
+`POST /session/:sessionId/wda/device/hingeAngle` with `{"angle": 90}` sends an
+event requesting a simulated hinge angle of 90 degrees. The angle
+must be a finite number from `0` (closed) to `180` (fully open); fractional values
+are supported. POST checks for a hinge and the required IOKit serialization,
+event creation, and dispatch APIs. This permits an injection attempt; it does not
+establish that the device accepts this vendor payload. Physical devices may attempt
+injection when those prerequisites exist, but event acceptance and the resulting
+angle/layout changes on a physical Duo remain unverified. Devices without these
+prerequisites, tvOS, and watchOS return `unsupported operation`.
+
+The response confirms event dispatch, not that the device applied the angle.
+Wait for the expected app layout before continuing, since folding completes
+asynchronously. The command does not rotate the device or update
+`currentDisplayId`; select the desired display separately.
+
+`GET /session/:sessionId/wda/device/hingeAngle` reads the current angle in degrees
+and returns a numeric value, for example `{"value": 90.5}`. It reads CoreMotion
+rather than remembering the last angle sent by WDA, so changes made outside WDA
+are reflected too. The request waits up to five seconds for a valid reading and
+returns an error if none arrives. GET separately checks for a hinge and the
+CoreMotion subscription APIs; it does not depend on the IOKit injection APIs.
+Devices without these reading prerequisites return `unsupported operation`.
+A reading during a fold may reflect an intermediate angle; it does not wait for
+the transition to finish.
+
+Both hinge angle endpoints are also available without a session:
+`GET /wda/device/hingeAngle` and `POST /wda/device/hingeAngle`. They operate on
+the device and do not require creating an Appium session first.
+
+## Validation and feedback
+
+Hinge operations have been tested on the iPhone Duo simulator with Xcode 27.1.
+We have not had access to a physical Duo for testing,
+so hinge readings, acceptance of the private HID events, and the resulting
+display/layout behavior on that hardware remain unverified. Loading CoreMotion
+and finding `CMAngleManager` were verified on a physical iPad mini, which reported
+no available hinge. On the same iPad mini running iPadOS 27.0.1, IOKit loading,
+resolution of all four injection functions, payload serialization, vendor-event
+creation, and HID client creation also succeeded. Event dispatch was not called.
+These checks do not validate hinge readings or event acceptance on physical
+hardware with a hinge.
+
+If you have access to a physical device with a hinge, we would appreciate your
+help testing these endpoints and [reporting the observed behavior](https://github.com/appium/WebDriverAgent/issues).
+Please include the device model, iOS and Xcode versions, WDA version, requests and
+responses, and any observed angle or display/layout changes. Reports of unsupported
+operations or successful responses with no observable change are useful too.

package/drivers/ios/WebDriverAgent/docs/multiple-displays.md

@@ -0,0 +1,168 @@
+# Multiple displays
+
+On devices such as iPhone Duo, `GET /wda/screens` lists the available displays.
+Set `currentDisplayId` through `POST /session/:sessionId/appium/settings` to select
+one of these IDs. Do not assume that the main display is the currently visible
+one after folding or unfolding the device.
+
+The setting selects the display for screenshots and MJPEG frames, and passes the
+selected display ID to newly started XCTest screen recordings (see the
+[simulator recording limitation](#xctest-recording-on-the-duo-simulator) below). MJPEG follows setting changes on the existing
+connection; an in-progress recording keeps the display selected when it started.
+An unavailable display causes screenshots and recording requests to fail; MJPEG
+pauses frame delivery until a valid display is selected. Set `currentDisplayId`
+to `null` to restore the main display. WDA does not automatically switch this
+setting when the device changes pose.
+
+`GET /wda/screen` also follows `currentDisplayId`: `displayId` and `scale`
+belong to the selected screen, and `screenSize` is its size in logical pixels,
+adjusted to the active application's orientation. Unavailable selections return
+an error. The status bar must belong to that display and be visible at its top.
+Hidden containers and side-mounted status UI do not define a top-edge crop;
+`statusBarSize` is zero when no such bar is present. Clients should refresh this
+information after display, orientation, or status-bar changes.
+
+The XCTest point lookup used by WDA has no display argument, including in the
+Xcode 27.1 interfaces checked for this change. When a secondary display is
+selected, WDA uses its active-app fallback instead of that main-display lookup.
+This is not display-specific app filtering: set `defaultActiveApplication` to the
+app's bundle ID when multiple foreground apps make the result ambiguous. An app
+specified when creating the session retains its existing priority.
+
+W3C touch actions target the selected display. Viewport, element, and pointer
+origins can be mixed within one action sequence; element offsets remain relative
+to the element's center. Element origins require `currentDisplayId` to match the
+element's display; they do not override the selected display. Key-only and
+pause-only sequences do not require the selected display to be available.
+For an application-element origin on a secondary display, compute offsets from
+its returned element rect, just as for any other element. XCTest may report that
+rect with dimensions transposed relative to the application's window; WDA uses
+the returned rect's center plus the requested offset as a viewport point and
+applies the selected-display correction. Do not substitute the window's center
+when calculating an offset for an application-element origin. This is separate
+from the older-SDK compatibility issue below. Main-display application origins
+retain their existing behavior.
+Element scrolling uses the visible area in the same
+coordinate space as the element frame, including on rotated main and secondary displays.
+WDA scrolling rejects an unavailable selected display instead of using an
+uncorrected frame. Each normalized scroll keeps its converted frame and vector
+in the same coordinate space across its drags. Keep the device orientation and
+fold state stable until the command completes; change the display setting between
+commands. Scroll-to-visible takes a fresh parent snapshot for each scroll step.
+
+Native application-root coordinates on a secondary display require a
+non-empty application window on that display as a coordinate anchor. Edge and
+outside coordinates are preserved, as on the main display; XCTest determines
+how the gesture is delivered. No hit testing or clamping is performed here.
+Requests fail if no such window exists on the selected display.
+
+This gesture support builds on [#1269](https://github.com/appium/WebDriverAgent/pull/1269).
+
+## Legacy SDK compatibility windows
+
+“Legacy SDK” here means the SDK used to build the app: the tested older app was
+built with **iOS SDK 26.5 (Xcode 26.6)** and ran in a compatibility window on
+iPhone Duo. It does not refer to the device's iOS version or the SDK used to build
+WDA. See Apple's [SDK-dependent layout guidance](https://developer.apple.com/videos/play/tech-talks/111461/).
+
+On the **iPhone Duo simulator, iOS 27.1 (24A94401), with an Xcode 27.2 beta 2
+UI-test runner**, direct XCTest element and coordinate taps failed to deliver
+input to that app in fully open and some intermediate poses. The same app source
+built with **SDK 27.2** received the taps. The failure reproduced without WDA;
+it is a known limitation observed in the Apple compatibility-layout/XCTest path,
+although the failing internal component has not been identified. Physical devices
+and other SDK/runtime combinations remain unverified.
+
+Select the app's `currentDisplayId` explicitly, but be aware that selecting the
+correct display does not resolve this issue. WDA does not apply a compatibility
+coordinate correction. Rebuilding with SDK 27.2 avoided the failure in the tested
+app; for diagnosis, compare direct XCTest taps with app-recorded input.
+
+## XCTest recording on the Duo simulator
+
+On **iOS 27.1 (24A94401), with Xcode 27.2 beta 2**, the native XCTest
+recording path produced black video for the closed Duo's outer display.
+This reproduced after starting WDA afresh while the device was closed, as well
+as after switching from the inner display back to the outer display.
+
+The recorded native `XCTScreenRecordingRequest.screenID` was `1` for the outer
+screen and `3` for the inner screen, matching the selected IDs returned by
+`GET /wda/screens`. Simultaneous outer-display screenshots were correct at
+1398 x 2034 pixels. Nevertheless, each four-second outer recording in the fresh
+runner experiment contained only one black frame at 2006 x 2852 pixels; the
+inner-display recording contained visible content. A successful start/stop
+response is therefore insufficient to verify captured video.
+
+The failure occurs downstream of the selected ID being supplied to XCTest;
+this experiment does not identify the failing internal Apple component or
+establish behavior on other runtimes or physical devices. WDA does not remap
+display IDs to work around it. Use the MJPEG/ffmpeg recording path when affected;
+that path was verified across closed, book, and fully open poses with both MJPEG
+and H.264 output. Set `mjpegFixOrientation` to `true` if upright encoded MJPEG
+pixels are required: the default preserves the existing EXIF-oriented output.
+
+## Waiting for rotated layouts
+
+An application's reported interface orientation can update before its element
+frames settle. On an iPad simulator running iOS 26.5, the gesture fixture's Alerts
+button briefly retained transposed dimensions immediately after rotation;
+resolving an element-origin gesture during that interval missed the button.
+The same failure reproduced on the unmodified WDA baseline. Waiting for the
+fixture's expected landscape geometry resolved it; direct XCTest gesture
+controls also passed. Tests should wait for the application's expected layout
+before resolving coordinates, in addition to keeping its pose stable during a
+command. This observation does not imply that every missed gesture is an
+XCTest defect.
+
+## Home button on Duo devices
+
+On the Duo simulator running iOS 27.1, XCTest's Home button and its IOHID
+wrapper can return success without leaving the foreground application. WDA
+uses a directly dispatched IOKit Home key-down/key-up pair for Home requests
+on iOS devices with an available hinge sensor, including simulators and physical
+devices. Devices without a hinge retain the XCTest path. The direct path sends button events;
+it does not substitute application activation or change the selected display.
+
+The Home key event has been verified on the Duo simulator; physical Duo Home
+behavior remains unverified and feedback is welcome. Availability of IOKit APIs
+and successful event dispatch do not by themselves confirm that the app left
+the foreground.
+
+This workaround does not address rotation or input immediately after an
+application is reactivated. See [Appium #22857](https://github.com/appium/appium/issues/22857).
+
+## Validation and feedback
+
+Duo display behavior has been tested on the iPhone Duo simulator with Xcode 27.1
+and Xcode 27.2 beta 2.
+We have not had access to a physical Duo for testing. If you have access to one,
+we would appreciate [reports of its display and capture behavior](https://github.com/appium/WebDriverAgent/issues),
+including the device model, iOS/Xcode and WDA versions, selected display IDs,
+requests and responses, and observed results.
+
+### Rotation on Duo devices
+
+On Duo Simulator 27.1, assigning `XCUIDevice.orientation` can update XCTest's
+reported orientation without rotating the application. On Duo simulators with
+an available hinge sensor, WDA directly dispatches the vendor-defined
+`orientation-picker-control` event used by Xcode 27.1's Duo controls, while also
+keeping XCTest's reported device orientation in sync.
+
+On physical devices with an available hinge sensor, WDA first uses XCTest and
+checks the application's interface orientation after waiting for stability.
+Only if that check fails does WDA log the transition to the vendor HID fallback
+and attempt it. Devices without a hinge retain the XCTest path.
+
+The vendor event has only been verified on the Duo simulator. Its
+`com.apple.Virtualization.VirtualMachines` receiver may not exist on physical
+hardware. Physical-device feedback is welcome; availability of the IOKit APIs
+or successful event submission does not establish that rotation works.
+
+Select the active panel with `currentDisplayId` before rotating. The inner
+panel's native orientation is a quarter turn from the cover panel, so WDA
+translates the requested orientation for the selected display. Both orientation
+and numeric rotation commands use the same path. WDA waits up to five seconds
+for the application's interface orientation to match, then waits for stability;
+event submission alone is not success. An app or panel that does not support
+the requested orientation still returns an error. In particular, the tested
+cover panel did not adopt upside-down portrait.

package/drivers/ios/WebDriverAgent/lib/webdriveragent.ts

@@ -4,8 +4,7 @@ import {WebDriverProxy} from '@appium/base-driver';
 import {strongbox} from '@appium/strongbox';
 import {fs, util} from '@appium/support';
 import type {AppiumLogger, StringRecord} from '@appium/types';
-import AsyncLock from 'async-lock';
-import {waitForCondition} from 'asyncbox';
+import {AsyncLock, waitForCondition} from 'asyncbox';
 
 import {WDA_RUNNER_BUNDLE_ID, WDA_BASE_URL, DEFAULT_TEST_BUNDLE_SUFFIX} from './constants.js';
 import {log as defaultLogger} from './logger.js';