appium-webdriveragent 16.7.3 → 16.9.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [16.9.0](https://github.com/appium/WebDriverAgent/compare/v16.8.0...v16.9.0) (2026-08-27)
+
+### Features
+
+* cache the system application resolution for WDA's process lifetime ([#1232](https://github.com/appium/WebDriverAgent/issues/1232)) ([21c98f2](https://github.com/appium/WebDriverAgent/commit/21c98f253561ee3dfc93edfb1c4de6afc3200b50))
+
+## [16.8.0](https://github.com/appium/WebDriverAgent/compare/v16.7.3...v16.8.0) (2026-08-24)
+
+### Features
+
+* bound accessibility snapshot requests to avoid indefinite hangs ([#1214](https://github.com/appium/WebDriverAgent/issues/1214)) ([cd829eb](https://github.com/appium/WebDriverAgent/commit/cd829eb9725f57efbfb9538a073de059020ddd38))
+
 ## [16.7.3](https://github.com/appium/WebDriverAgent/compare/v16.7.2...v16.7.3) (2026-08-24)
 
 ### Bug Fixes

package/WebDriverAgentLib/Categories/XCAXClient_iOS+FBSnapshotReqParams.m

@@ -10,6 +10,13 @@
 
 #import <objc/runtime.h>
 
+#import "FBConfiguration.h"
+#import "FBErrorBuilder.h"
+#import "FBLogger.h"
+#import "FBXCAccessibilityElement.h"
+#import "FBXCAXClientProxy.h"
+#import "XCUIApplication.h"
+
 /**
  Available parameters with their default values for XCTest:
   @"maxChildren" : (int)2147483647
@@ -60,6 +67,82 @@ static id swizzledSnapshotParameters(id self, SEL _cmd)
   return result;
 }
 
+static id (*original_requestSnapshotForElement)(id, SEL, id, id, id, NSError **);
+
+// pid -> last-unresponsive-at. XCTest retries a failed snapshot request several
+// times in a row; this lets retries fail fast within `timeout` of the last check
+// instead of each re-running the full wait.
+static NSMutableDictionary<NSNumber *, NSDate *> *unresponsiveApplicationPids;
+static NSObject *unresponsiveApplicationPidsLock;
+
+static NSError *FBBuildUnresponsiveApplicationError(int pid, NSTimeInterval timeout)
+{
+  // https://github.com/appium/WebDriverAgent/issues/1210
+  NSString *description = [NSString stringWithFormat:
+    @"The application with process identifier %d did not confirm its main run loop is "
+     @"responsive within %.1f second(s) and is likely in an unresponsive state. "
+     @"Aborting the accessibility snapshot request instead of risking an indefinite "
+     @"hang.",
+    pid, timeout];
+  [FBLogger logFmt:@"%@", description];
+  NSError *error;
+  [[[FBErrorBuilder builder] withDescription:description] buildError:&error];
+  return error;
+}
+
+// Guards -[XCAXClient_iOS requestSnapshotForElement:...] against hanging forever
+// on an unresponsive app (#1210). If accessibilityDeadline > 0, checks run loop
+// responsiveness first and aborts with an error instead of risking an unbounded
+// wait; otherwise falls through to the original, unbounded behavior.
+static id swizzledRequestSnapshotForElement(id self, SEL _cmd, id element, id attributes, id parameters, NSError **error)
+{
+  NSTimeInterval timeout = FBConfiguration.sharedInstance.accessibilityDeadline;
+  if (timeout < DBL_EPSILON) {
+    return original_requestSnapshotForElement(self, _cmd, element, attributes, parameters, error);
+  }
+
+  int pid = [(id<FBXCAccessibilityElement>)element processIdentifier];
+  XCUIApplication *application = [FBXCAXClientProxy.sharedClient monitoredApplicationWithProcessIdentifier:pid];
+  if (nil == application) {
+    // Nothing to confirm responsiveness for (e.g. the system element) - fall
+    // through to the original behavior.
+    return original_requestSnapshotForElement(self, _cmd, element, attributes, parameters, error);
+  }
+
+  NSNumber *pidKey = @(pid);
+  @synchronized (unresponsiveApplicationPidsLock) {
+    NSDate *markedUnresponsiveAt = unresponsiveApplicationPids[pidKey];
+    if (nil != markedUnresponsiveAt && -markedUnresponsiveAt.timeIntervalSinceNow < timeout) {
+      if (nil != error) {
+        *error = FBBuildUnresponsiveApplicationError(pid, timeout);
+      }
+      return nil;
+    }
+  }
+
+  dispatch_semaphore_t sem = dispatch_semaphore_create(0);
+  __block BOOL isResponsive = NO;
+  [FBXCAXClientProxy.sharedClient notifyWhenEventLoopIsIdleForApplication:application
+                                                                     reply:^(id result, NSError *idleError) {
+    isResponsive = (nil == idleError);
+    dispatch_semaphore_signal(sem);
+  }];
+  BOOL didReplyInTime = 0 == dispatch_semaphore_wait(sem, dispatch_time(DISPATCH_TIME_NOW, (int64_t)(timeout * NSEC_PER_SEC)));
+  if (didReplyInTime && isResponsive) {
+    @synchronized (unresponsiveApplicationPidsLock) {
+      [unresponsiveApplicationPids removeObjectForKey:pidKey];
+    }
+    return original_requestSnapshotForElement(self, _cmd, element, attributes, parameters, error);
+  }
+
+  @synchronized (unresponsiveApplicationPidsLock) {
+    unresponsiveApplicationPids[pidKey] = [NSDate date];
+  }
+  if (nil != error) {
+    *error = FBBuildUnresponsiveApplicationError(pid, timeout);
+  }
+  return nil;
+}
 
 @implementation XCAXClient_iOS (FBSnapshotReqParams)
 
@@ -69,6 +152,9 @@ static id swizzledSnapshotParameters(id self, SEL _cmd)
 
 + (void)load
 {
+  unresponsiveApplicationPids = [NSMutableDictionary new];
+  unresponsiveApplicationPidsLock = [NSObject new];
+
   Method original_defaultParametersMethod = class_getInstanceMethod(self.class, @selector(defaultParameters));
   IMP swizzledDefaultParametersImp = (IMP)swizzledDefaultParameters;
   original_defaultParameters = (id (*)(id, SEL)) method_setImplementation(original_defaultParametersMethod, swizzledDefaultParametersImp);
@@ -76,6 +162,10 @@ static id swizzledSnapshotParameters(id self, SEL _cmd)
   Method original_snapshotParametersMethod = class_getInstanceMethod(NSClassFromString(@"XCTElementQuery"), NSSelectorFromString(@"snapshotParameters"));
   IMP swizzledSnapshotParametersImp = (IMP)swizzledSnapshotParameters;
   original_snapshotParameters = (id (*)(id, SEL)) method_setImplementation(original_snapshotParametersMethod, swizzledSnapshotParametersImp);
+
+  Method original_requestSnapshotForElementMethod = class_getInstanceMethod(self.class, @selector(requestSnapshotForElement:attributes:parameters:error:));
+  IMP swizzledRequestSnapshotForElementImp = (IMP)swizzledRequestSnapshotForElement;
+  original_requestSnapshotForElement = (id (*)(id, SEL, id, id, id, NSError **)) method_setImplementation(original_requestSnapshotForElementMethod, swizzledRequestSnapshotForElementImp);
 }
 
 #pragma clang diagnostic pop

package/WebDriverAgentLib/Commands/FBCustomCommands.m

@@ -205,10 +205,13 @@
 + (id<FBResponsePayload>)handleActiveAppInfo:(FBRouteRequest *)request
 {
   XCUIApplication *app = request.session.activeApplication ?: XCUIApplication.fb_activeApplication;
+  // .identifier can be nil if the app stopped answering accessibility requests
+  // and accessibilityDeadline aborted the underlying snapshot fetch (#1210).
+  NSString *name = app.identifier ?: @"unknown";
   return FBResponseWithObject(@{
     @"pid": @(app.processID),
     @"bundleId": app.bundleID,
-    @"name": app.identifier,
+    @"name": name,
     @"processArguments": [self processArguments:app],
   });
 }

package/WebDriverAgentLib/Commands/FBSessionCommands.m

@@ -309,6 +309,9 @@
   if (nil != capabilities[FB_SETTING_WAIT_FOR_IDLE_TIMEOUT]) {
     FBConfiguration.sharedInstance.waitForIdleTimeout = [capabilities[FB_SETTING_WAIT_FOR_IDLE_TIMEOUT] doubleValue];
   }
+  if (nil != capabilities[FB_SETTING_ACCESSIBILITY_DEADLINE]) {
+    FBConfiguration.sharedInstance.accessibilityDeadline = [capabilities[FB_SETTING_ACCESSIBILITY_DEADLINE] doubleValue];
+  }
   if (nil == capabilities[FB_CAP_FORCE_SIMULATOR_SOFTWARE_KEYBOARD_PRESENCE] ||
       [capabilities[FB_CAP_FORCE_SIMULATOR_SOFTWARE_KEYBOARD_PRESENCE] boolValue]) {
     [FBConfiguration.sharedInstance forceSimulatorSoftwareKeyboardPresence];

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentLib/Routing/FBWebServer.m

@@ -269,6 +269,9 @@ static NSString *const FBServerURLEndMarker = @"<-ServerURLHere";
     [response respondWithString:@"<!DOCTYPE html><html><title>Health Check</title><body><p>I-AM-ALIVE</p></body></html>"];
   }];
 
+  // Deprecated: no longer needed since appium-xcuitest-driver handles calibration
+  // itself (https://github.com/appium/appium-xcuitest-driver/pull/2948). Kept for
+  // backward compatibility; will be removed in a future major release.
   NSString *calibrationPage = @"<html>"
   "<title>{\"x\":null,\"y\":null}</title>"
   "<header>"
@@ -276,6 +279,7 @@ static NSString *const FBServerURLEndMarker = @"<-ServerURLHere";
   "</header>"
   "</html>";
   [self.server get:@"/calibrate" withBlock:^(RouteRequest *request, RouteResponse *response) {
+    [FBLogger logFmt:@"The /calibrate endpoint is deprecated and will be removed in a future release"];
     [response respondWithString:calibrationPage];
   }];
 

package/WebDriverAgentLib/Utilities/FBConfiguration.h

@@ -234,6 +234,17 @@ typedef NS_ENUM(NSInteger, FBConfigurationKeyboardPreference) {
  */
 @property (atomic, assign) NSTimeInterval animationCoolOffTimeout;
 
+/**
+ * Maximum time to wait for the frontmost application to confirm its main run loop
+ * is responsive before an accessibility snapshot request (element attribute
+ * lookups, active app detection, etc). XCTest has no bounded timeout of its own
+ * here, so a frozen app could otherwise block WDA forever (#1210); past this
+ * timeout the request is aborted with an error instead.
+ * Set to zero or negative to disable, restoring unbounded behavior. Disabled (0)
+ * by default.
+ */
+@property (atomic, assign) NSTimeInterval accessibilityDeadline;
+
 /**
  Custom class chain locator for accept alert button location.
  This might be useful if the default buttons detection algorithm fails to determine alert buttons properly

package/WebDriverAgentLib/Utilities/FBConfiguration.m

@@ -351,6 +351,7 @@ static NSString *const axSettingsClassName = @"AXSettings";
   self.autoClickAlertSelector = @"";
   self.waitForIdleTimeout = 10.;
   self.animationCoolOffTimeout = 2.;
+  self.accessibilityDeadline = 0.;
   // 50 should be enough for the majority of the cases. The performance is acceptable for values up to 100.
   FBSetCustomParameterForElementSnapshot(FBSnapshotMaxDepthKey, @50);
   FBSetCustomParameterForElementSnapshot(FBSnapshotMaxChildrenKey, @INT_MAX);

package/WebDriverAgentLib/Utilities/FBSettings.h

@@ -23,6 +23,7 @@ extern NSString* const FB_SETTING_KEYBOARD_AUTOCORRECTION;
 extern NSString* const FB_SETTING_KEYBOARD_PREDICTION;
 extern NSString* const FB_SETTING_SNAPSHOT_MAX_DEPTH;
 extern NSString* const FB_SETTING_SNAPSHOT_MAX_CHILDREN;
+extern NSString* const FB_SETTING_ACCESSIBILITY_DEADLINE;
 extern NSString* const FB_SETTING_USE_FIRST_MATCH;
 extern NSString* const FB_SETTING_BOUND_ELEMENTS_BY_INDEX;
 extern NSString* const FB_SETTING_REDUCE_MOTION;

package/WebDriverAgentLib/Utilities/FBSettings.m

@@ -19,6 +19,7 @@ NSString* const FB_SETTING_KEYBOARD_AUTOCORRECTION = @"keyboardAutocorrection";
 NSString* const FB_SETTING_KEYBOARD_PREDICTION = @"keyboardPrediction";
 NSString* const FB_SETTING_SNAPSHOT_MAX_DEPTH = @"snapshotMaxDepth";
 NSString* const FB_SETTING_SNAPSHOT_MAX_CHILDREN = @"snapshotMaxChildren";
+NSString* const FB_SETTING_ACCESSIBILITY_DEADLINE = @"accessibilityDeadline";
 NSString* const FB_SETTING_USE_FIRST_MATCH = @"useFirstMatch";
 NSString* const FB_SETTING_BOUND_ELEMENTS_BY_INDEX = @"boundElementsByIndex";
 NSString* const FB_SETTING_REDUCE_MOTION = @"reduceMotion";

package/WebDriverAgentLib/Utilities/FBSettingsHandler.m

@@ -142,6 +142,10 @@ static NSSet<NSString *> *FBNilClearableSettingKeys(void)
       FBConfiguration.sharedInstance.animationCoolOffTimeout = [value doubleValue];
       return nil;
     };
+    map[FB_SETTING_ACCESSIBILITY_DEADLINE] = ^FBCommandStatus *(FBSession *session, id value) {
+      FBConfiguration.sharedInstance.accessibilityDeadline = [value doubleValue];
+      return nil;
+    };
     map[FB_SETTING_DEFAULT_ALERT_ACTION] = ^FBCommandStatus *(FBSession *session, id value) {
       if (nil == value) {
         session.defaultAlertAction = nil;
@@ -249,6 +253,9 @@ static NSSet<NSString *> *FBNilClearableSettingKeys(void)
     map[FB_SETTING_ANIMATION_COOL_OFF_TIMEOUT] = ^id(FBSession *session) {
       return @(FBConfiguration.sharedInstance.animationCoolOffTimeout);
     };
+    map[FB_SETTING_ACCESSIBILITY_DEADLINE] = ^id(FBSession *session) {
+      return @(FBConfiguration.sharedInstance.accessibilityDeadline);
+    };
     map[FB_SETTING_BOUND_ELEMENTS_BY_INDEX] = ^id(FBSession *session) {
       return @(FBConfiguration.sharedInstance.boundElementsByIndex);
     };

package/WebDriverAgentLib/Utilities/FBXCAXClientProxy.h

@@ -38,6 +38,15 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)notifyWhenNoAnimationsAreActiveForApplication:(XCUIApplication *)application
                                                 reply:(void (^)(void))reply;
 
+/**
+ Wraps the private -[XCAXClient_iOS notifyWhenEventLoopIsIdleForApplication:reply:],
+ used to check run loop responsiveness before a snapshot request (#1210).
+ `reply` may fire more than once per call; `error` is non-nil only if monitoring
+ itself could not be started.
+ */
+- (void)notifyWhenEventLoopIsIdleForApplication:(XCUIApplication *)application
+                                           reply:(void (^)(id _Nullable result, NSError * _Nullable error))reply;
+
 - (nullable NSDictionary *)attributesForElement:(id<FBXCAccessibilityElement>)element
                                      attributes:(NSArray *)attributes
                                           error:(NSError**)error;

package/WebDriverAgentLib/Utilities/FBXCAXClientProxy.m

@@ -20,6 +20,7 @@ static id FBAXClient = nil;
 @interface FBXCAXClientProxy ()
 
 @property (nonatomic) NSMutableDictionary<NSNumber *, XCUIApplication *> *appsCache;
+@property (nonatomic, nullable) id<FBXCAccessibilityElement> cachedSystemApplication;
 
 @end
 
@@ -67,7 +68,14 @@ static id FBAXClient = nil;
 
 - (id<FBXCAccessibilityElement>)systemApplication
 {
-  return [FBAXClient systemApplication];
+  @synchronized (self) {
+    if (nil == self.cachedSystemApplication) {
+      // The system application's identity cannot change without it being killed,
+      // which takes WDA down with it, so it is safe to cache it forever.
+      self.cachedSystemApplication = [FBAXClient systemApplication];
+    }
+    return self.cachedSystemApplication;
+  }
 }
 
 - (NSDictionary *)defaultParameters
@@ -81,6 +89,12 @@ static id FBAXClient = nil;
   [FBAXClient notifyWhenNoAnimationsAreActiveForApplication:application reply:reply];
 }
 
+- (void)notifyWhenEventLoopIsIdleForApplication:(XCUIApplication *)application
+                                           reply:(void (^)(id _Nullable result, NSError * _Nullable error))reply
+{
+  [FBAXClient notifyWhenEventLoopIsIdleForApplication:application reply:reply];
+}
+
 - (NSDictionary *)attributesForElement:(id<FBXCAccessibilityElement>)element
                             attributes:(NSArray *)attributes
                                  error:(NSError**)error;
@@ -92,28 +106,30 @@ static id FBAXClient = nil;
 
 - (XCUIApplication *)monitoredApplicationWithProcessIdentifier:(int)pid
 {
-  NSMutableSet *terminatedAppIds = [NSMutableSet set];
-  for (NSNumber *appPid in self.appsCache) {
-    if (![self.appsCache[appPid] running]) {
-      [terminatedAppIds addObject:appPid];
+  @synchronized (self) {
+    NSMutableSet *terminatedAppIds = [NSMutableSet set];
+    for (NSNumber *appPid in self.appsCache) {
+      if (![self.appsCache[appPid] running]) {
+        [terminatedAppIds addObject:appPid];
+      }
+    }
+    for (NSNumber *appPid in terminatedAppIds) {
+      [self.appsCache removeObjectForKey:appPid];
     }
-  }
-  for (NSNumber *appPid in terminatedAppIds) {
-    [self.appsCache removeObjectForKey:appPid];
-  }
 
-  XCUIApplication *result = [self.appsCache objectForKey:@(pid)];
-  if (nil != result) {
-    return result;
-  }
+    XCUIApplication *result = [self.appsCache objectForKey:@(pid)];
+    if (nil != result) {
+      return result;
+    }
 
-  XCUIApplication *app = [[FBAXClient applicationProcessTracker]
-                          monitoredApplicationWithProcessIdentifier:pid];
-  if (nil == app) {
-    return nil;
+    XCUIApplication *app = [[FBAXClient applicationProcessTracker]
+                            monitoredApplicationWithProcessIdentifier:pid];
+    if (nil == app) {
+      return nil;
+    }
+    [self.appsCache setObject:app forKey:@(pid)];
+    return app;
   }
-  [self.appsCache setObject:app forKey:@(pid)];
-  return app;
 }
 
 @end

package/WebDriverAgentTests/IntegrationApp/Classes/ViewController.m

@@ -38,9 +38,10 @@
 
 - (IBAction)deadlockApp:(id)sender
 {
-  dispatch_sync(dispatch_get_main_queue(), ^{
-    // This will never execute
-  });
+  // A self dispatch_sync would trip the OS watchdog and get the process
+  // killed outright. Sleeping instead simulates an app that stops answering
+  // accessibility requests while staying alive, per #1210.
+  [NSThread sleepForTimeInterval:20.0];
 }
 
 - (IBAction)didTapButton:(UIButton *)button

package/WebDriverAgentTests/IntegrationApp/Resources/Base.lproj/Main.storyboard

@@ -38,7 +38,6 @@
                                 <state key="normal" title="Deadlock app"/>
                                 <connections>
                                     <action selector="deadlockApp:" destination="BYZ-38-t0r" eventType="touchUpInside" id="53X-DJ-KNY"/>
-                                    <action selector="showAlert:" destination="BYZ-38-t0r" eventType="touchUpInside" id="FEN-VX-MMc"/>
                                 </connections>
                             </button>
                             <button opaque="NO" contentMode="scaleToFill" contentHorizontalAlignment="center" contentVerticalAlignment="center" buttonType="system" lineBreakMode="middleTruncation" translatesAutoresizingMaskIntoConstraints="NO" id="M2N-Yn-ytb">

package/WebDriverAgentTests/IntegrationTests/FBConfigurationTests.m

@@ -11,6 +11,9 @@
 
 #import "FBConfiguration.h"
 #import "FBRuntimeUtils.h"
+#import "FBTestMacros.h"
+#import "XCUIElement.h"
+#import "XCUIElement+FBIsVisible.h"
 
 @interface FBConfigurationTests : FBIntegrationTestCase
 
@@ -35,4 +38,35 @@
   XCTAssertEqual(FBConfiguration.sharedInstance.reduceMotionEnabled, defaultReduceMotionEnabled);
 }
 
+- (void)testAccessibilityDeadlineAbortsSnapshotRequestForDeadlockedApp
+{
+  if (nil != NSProcessInfo.processInfo.environment[@"CI"]) {
+    XCTSkip(@"Deliberately freezes the app for several seconds, too slow/flaky for CI");
+  }
+
+  NSTimeInterval previousDeadline = FBConfiguration.sharedInstance.accessibilityDeadline;
+  // Also bounds any snapshot-based wait -tap itself may perform once the app is stuck.
+  FBConfiguration.sharedInstance.accessibilityDeadline = 3.0;
+  @try {
+    XCUIElement *deadlockButton = self.testedApplication.buttons[@"Deadlock app"];
+    FBAssertWaitTillBecomesTrue(deadlockButton.fb_isVisible);
+    // Freezes the app's main thread for 20s - see -[ViewController deadlockApp:].
+    [deadlockButton tap];
+
+    NSError *error;
+    NSDate *start = [NSDate date];
+    id snapshot = [self.testedApplication snapshotWithError:&error];
+    NSTimeInterval elapsed = -start.timeIntervalSinceNow;
+
+    XCTAssertNil(snapshot);
+    XCTAssertNotNil(error);
+    // Should abort close to accessibilityDeadline (plus XCTest's own internal
+    // retries), not hang indefinitely waiting for the frozen app (#1210).
+    XCTAssertLessThan(elapsed, 20.0);
+  } @finally {
+    FBConfiguration.sharedInstance.accessibilityDeadline = previousDeadline;
+    [self.testedApplication terminate];
+  }
+}
+
 @end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-webdriveragent",
-  "version": "16.7.3",
+  "version": "16.9.0",
   "description": "Package bundling WebDriverAgent",
   "keywords": [
     "Appium",