appium-webdriveragent 16.1.2 → 16.1.4

package/WebDriverAgentLib/FBAlert.h

@@ -9,7 +9,6 @@
 #import <Foundation/Foundation.h>
 
 @class XCUIApplication;
-@class XCUIElement;
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -26,65 +25,79 @@ NS_ASSUME_NONNULL_BEGIN
 + (instancetype)alertWithApplication:(XCUIApplication *)application;
 
 /**
- Creates alert helper for given application
-
- @param element The element which represents the alert
- */
-+ (instancetype)alertWithElement:(XCUIElement *)element;
-
-/**
- Determines whether alert is present
+ Determines whether alert is present.
+
+ An FBAlert instance resolves the alert (and, if found, its snapshot) at
+ most once, lazily, on the first call to isPresent, text, buttonLabels,
+ accept, dismiss, clickAlertButton:, clickElementMatchingClassChain:, or
+ typeText: - every subsequent call on the same instance reuses that result
+ rather than re-querying the live UI. This makes an isPresent check
+ immediately followed by an action (e.g. the auto-accept flow) act on the
+ exact same alert it just observed. Create a fresh FBAlert instance (via
+ alertWithApplication:) to observe the current UI state again.
  */
 - (BOOL)isPresent;
 
 /**
- Gets the labels of the buttons visible in the alert
+ Gets the labels of the buttons visible in the alert.
+ See isPresent for how presence is resolved.
  */
 - (nullable NSArray *)buttonLabels;
 
 /**
- Returns alert's title and description separated by new lines
+ Returns alert's title and description separated by new lines.
+ See isPresent for how presence is resolved.
  */
 - (nullable NSString *)text;
 
 /**
- Accepts alert, if present
+ Accepts alert, if present.
+ See isPresent for how presence is resolved.
 
- @param error If there is an error, upon return contains an NSError object that describes the problem.
- @return YES if the operation succeeds, otherwise NO.
+ @throws FBAlertNotPresentException if no alert is present.
+ @throws FBAlertActionFailedException if the accept button could not be found.
  */
-- (BOOL)acceptWithError:(NSError **)error;
+- (void)accept;
 
 /**
- Dismisses alert, if present
+ Dismisses alert, if present.
+ See isPresent for how presence is resolved.
 
- @param error If there is an error, upon return contains an NSError object that describes the problem.
- @return YES if the operation succeeds, otherwise NO.
+ @throws FBAlertNotPresentException if no alert is present.
+ @throws FBAlertActionFailedException if the dismiss button could not be found.
  */
-- (BOOL)dismissWithError:(NSError **)error;
+- (void)dismiss;
 
 /**
- Clicks on an alert button, if present
- 
+ Clicks on an alert button, if present.
+ See isPresent for how presence is resolved.
+
  @param label The label of the button on which to click.
- @param error If there is an error, upon return contains an NSError object that describes the problem.
- @return YES if the operation suceeds, otherwise NO.
+ @throws FBAlertNotPresentException if no alert is present.
+ @throws FBAlertActionFailedException if no button with the given label could be found.
  */
-- (BOOL)clickAlertButton:(NSString *)label error:(NSError **)error;
+- (void)clickAlertButton:(NSString *)label;
 
 /**
- XCUElement that represents alert
+ Taps the first descendant of the alert matching the given class chain
+ selector, if present.
+ See isPresent for how presence is resolved.
+
+ @param classChain The class chain selector to match against the alert's descendants.
+ @throws FBAlertNotPresentException if no alert is present.
+ @throws FBAlertActionFailedException if no matching element could be found.
  */
-- (nullable XCUIElement *)alertElement;
+- (void)clickElementMatchingClassChain:(NSString *)classChain;
 
 /**
- Types a text into an input inside the alert container, if it is present
+ Types a text into an input inside the alert container, if it is present.
+ See isPresent for how presence is resolved.
 
  @param text the text to type
- @param error If there is an error, upon return contains an NSError object that describes the problem.
- @return YES if the operation succeeds, otherwise NO.
+ @throws FBAlertNotPresentException if no alert is present.
+ @throws FBAlertSetTextFailedException if there is no single input field to type into, or typing itself fails.
  */
-- (BOOL)typeText:(NSString *)text error:(NSError **)error;
+- (void)typeText:(NSString *)text;
 
 @end
 

package/WebDriverAgentLib/FBAlert.m

@@ -9,21 +9,26 @@
 #import "FBAlert.h"
 
 #import "FBConfiguration.h"
-#import "FBErrorBuilder.h"
+#import "FBExceptions.h"
 #import "FBLogger.h"
 #import "FBXCElementSnapshotWrapper+Helpers.h"
 #import "FBXCodeCompatibility.h"
 #import "XCUIApplication.h"
 #import "XCUIApplication+FBAlert.h"
+#import "XCUIApplication+FBHelpers.h"
 #import "XCUIElement+FBClassChain.h"
 #import "XCUIElement+FBTyping.h"
+#import "XCUIElement+FBUID.h"
 #import "XCUIElement+FBUtilities.h"
 #import "XCUIElement+FBWebDriverAttributes.h"
 
 
 @interface FBAlert ()
 @property (nonatomic, strong) XCUIApplication *application;
-@property (nonatomic, strong, nullable) XCUIElement *element;
+@property (nonatomic, nullable) XCUIElement *cachedAlertElement;
+@property (nonatomic) BOOL hasCachedAlertElement;
+@property (nonatomic, nullable) id<FBXCElementSnapshot> cachedAlertSnapshot;
+@property (nonatomic) BOOL hasCachedAlertSnapshot;
 @end
 
 @implementation FBAlert
@@ -35,32 +40,81 @@
   return alert;
 }
 
-+ (instancetype)alertWithElement:(XCUIElement *)element
+// Resolved (and, if found, snapshotted) at most once per instance and then
+// reused for every subsequent call - see FBAlert.h. This is what makes an
+// isPresent check followed by an action (the FBAlertsMonitor/FBSession
+// auto-accept flow) act on the exact same alert it just observed, instead of
+// re-resolving against a UI that may have changed in between.
+- (nullable XCUIElement *)alertElement
 {
-  FBAlert *alert = [FBAlert new];
-  alert.element = element;
-  alert.application = element.application;
-  return alert;
+  if (!self.hasCachedAlertElement) {
+    id<FBXCElementSnapshot> snapshot = nil;
+    self.cachedAlertElement = [self alertElementFromApplication:&snapshot];
+    self.hasCachedAlertElement = YES;
+    if (nil != snapshot) {
+      self.cachedAlertSnapshot = snapshot;
+      self.hasCachedAlertSnapshot = YES;
+    }
+  }
+  return self.cachedAlertElement;
+}
+
+// The alert element's own subtree snapshot, taken once. All read-only
+// accessors (text, buttonLabels) and all element lookups (buttons, input
+// fields) work off this single snapshot in memory - only tapping/typing into
+// a specific already-located element pays for one more, narrowly targeted
+// accessibility round trip (see XCUIApplication.fb_elementForSnapshot:underElement:).
+// fb_cachedSnapshot is tried before fb_customSnapshot: it can reconstruct
+// the element's snapshot from the detection query's already-fetched
+// rootElementSnapshot without a further round trip (verified empirically -
+// see XCUIApplication+FBAlert.m).
+- (nullable id<FBXCElementSnapshot>)alertSnapshot
+{
+  if (!self.hasCachedAlertSnapshot) {
+    XCUIElement *alertElement = self.alertElement;
+    self.cachedAlertSnapshot = nil == alertElement
+      ? nil
+      : (alertElement.lastSnapshot ?: alertElement.fb_cachedSnapshot ?: [alertElement fb_customSnapshot]);
+    self.hasCachedAlertSnapshot = YES;
+  }
+  return self.cachedAlertSnapshot;
 }
 
 - (BOOL)isPresent
 {
-  @try {
-    if (nil == self.alertElement) {
-      return NO;
+  return nil != self.alertElement;
+}
+
++ (NSArray<id<FBXCElementSnapshot>> *)fb_buttonSnapshotsInSnapshot:(id<FBXCElementSnapshot>)snapshot
+{
+  NSMutableArray<id<FBXCElementSnapshot>> *buttons = [NSMutableArray array];
+  [snapshot enumerateDescendantsUsingBlock:^(id<FBXCElementSnapshot> descendant) {
+    if (descendant.elementType == XCUIElementTypeButton) {
+      [buttons addObject:descendant];
     }
-    [self.alertElement fb_customSnapshot];
-    return YES;
-  } @catch (NSException *) {
-    return NO;
-  }
+  }];
+  return buttons.copy;
+}
+
+- (void)fb_raiseNotPresentException __attribute__((noreturn))
+{
+  @throw [NSException exceptionWithName:FBAlertNotPresentException
+                                  reason:@"No alert is open"
+                                userInfo:nil];
 }
 
-- (BOOL)notPresentWithError:(NSError **)error
+- (void)fb_raiseActionFailedExceptionWithReason:(NSString *)reason __attribute__((noreturn))
 {
-  return [[[FBErrorBuilder builder]
-           withDescriptionFormat:@"No alert is open"]
-          buildError:error];
+  @throw [NSException exceptionWithName:FBAlertActionFailedException
+                                  reason:reason
+                                userInfo:nil];
+}
+
+- (void)fb_raiseSetTextFailedExceptionWithReason:(NSString *)reason __attribute__((noreturn))
+{
+  @throw [NSException exceptionWithName:FBAlertSetTextFailedException
+                                  reason:reason
+                                userInfo:nil];
 }
 
 + (BOOL)isSafariWebAlertWithSnapshot:(id<FBXCElementSnapshot>)snapshot
@@ -76,19 +130,19 @@
 
 - (NSString *)text
 {
-  if (!self.isPresent) {
+  id<FBXCElementSnapshot> snapshot = self.alertSnapshot;
+  if (nil == snapshot) {
     return nil;
   }
 
   NSMutableArray<NSString *> *resultText = [NSMutableArray array];
-  id<FBXCElementSnapshot> snapshot = self.alertElement.lastSnapshot ?: [self.alertElement fb_customSnapshot];
   BOOL isSafariAlert = [self.class isSafariWebAlertWithSnapshot:snapshot];
   [snapshot enumerateDescendantsUsingBlock:^(id<FBXCElementSnapshot> descendant) {
     XCUIElementType elementType = descendant.elementType;
     if (!(elementType == XCUIElementTypeTextView || elementType == XCUIElementTypeStaticText)) {
       return;
     }
-    
+
     FBXCElementSnapshotWrapper *descendantWrapper = [FBXCElementSnapshotWrapper ensureWrapped:descendant];
     if (elementType == XCUIElementTypeStaticText
         && nil != [descendantWrapper fb_parentMatchingType:XCUIElementTypeButton]) {
@@ -112,39 +166,47 @@
   return [resultText componentsJoinedByString:@"\n"];
 }
 
-- (BOOL)typeText:(NSString *)text error:(NSError **)error
+- (void)typeText:(NSString *)text
 {
-  if (!self.isPresent) {
-    return [self notPresentWithError:error];
+  XCUIElement *alertElement = self.alertElement;
+  id<FBXCElementSnapshot> alertSnapshot = self.alertSnapshot;
+  if (nil == alertElement || nil == alertSnapshot) {
+    [self fb_raiseNotPresentException];
   }
 
-  NSPredicate *textCollectorPredicate = [NSPredicate predicateWithFormat:@"elementType IN {%lu,%lu}",
-                                         XCUIElementTypeTextField, XCUIElementTypeSecureTextField];
-  NSArray<XCUIElement *> *dstFields = [[self.alertElement descendantsMatchingType:XCUIElementTypeAny]
-                                       matchingPredicate:textCollectorPredicate].allElementsBoundByIndex;
-  if (dstFields.count > 1) {
-    return [[[FBErrorBuilder builder]
-      withDescriptionFormat:@"The alert contains more than one input field"]
-     buildError:error];
+  NSMutableArray<id<FBXCElementSnapshot>> *dstFieldSnapshots = [NSMutableArray array];
+  [alertSnapshot enumerateDescendantsUsingBlock:^(id<FBXCElementSnapshot> descendant) {
+    XCUIElementType elementType = descendant.elementType;
+    if (elementType == XCUIElementTypeTextField || elementType == XCUIElementTypeSecureTextField) {
+      [dstFieldSnapshots addObject:descendant];
+    }
+  }];
+  if (dstFieldSnapshots.count > 1) {
+    [self fb_raiseSetTextFailedExceptionWithReason:@"The alert contains more than one input field"];
   }
-  if (0 == dstFields.count) {
-    return [[[FBErrorBuilder builder]
-             withDescriptionFormat:@"The alert contains no input fields"]
-            buildError:error];
+  id<FBXCElementSnapshot> dstFieldSnapshot = dstFieldSnapshots.firstObject;
+  if (nil == dstFieldSnapshot) {
+    [self fb_raiseSetTextFailedExceptionWithReason:@"The alert contains no input fields"];
+  }
+  XCUIElement *dstField = [XCUIApplication fb_elementForSnapshot:dstFieldSnapshot
+                                                      underElement:alertElement];
+  if (nil == dstField) {
+    [self fb_raiseSetTextFailedExceptionWithReason:@"Failed to resolve the input field element"];
+  }
+  NSError *error;
+  if (![dstField fb_typeText:text shouldClear:YES error:&error]) {
+    [self fb_raiseSetTextFailedExceptionWithReason:error.description];
   }
-  return [dstFields.firstObject fb_typeText:text
-                                shouldClear:YES
-                                      error:error];
 }
 
 - (NSArray *)buttonLabels
 {
-  if (!self.isPresent) {
+  id<FBXCElementSnapshot> alertSnapshot = self.alertSnapshot;
+  if (nil == alertSnapshot) {
     return nil;
   }
 
   NSMutableArray<NSString *> *labels = [NSMutableArray array];
-  id<FBXCElementSnapshot> alertSnapshot = self.alertElement.lastSnapshot ?: [self.alertElement fb_customSnapshot];
   [alertSnapshot enumerateDescendantsUsingBlock:^(id<FBXCElementSnapshot> descendant) {
     if (descendant.elementType != XCUIElementTypeButton) {
       return;
@@ -157,19 +219,20 @@
   return labels.copy;
 }
 
-- (BOOL)acceptWithError:(NSError **)error
+- (void)accept
 {
-  if (!self.isPresent) {
-    return [self notPresentWithError:error];
+  XCUIElement *alertElement = self.alertElement;
+  id<FBXCElementSnapshot> alertSnapshot = self.alertSnapshot;
+  if (nil == alertElement || nil == alertSnapshot) {
+    [self fb_raiseNotPresentException];
   }
 
-  id<FBXCElementSnapshot> alertSnapshot = self.alertElement.lastSnapshot ?: [self.alertElement fb_customSnapshot];
   XCUIElement *acceptButton = nil;
   if (FBConfiguration.acceptAlertButtonSelector.length) {
     NSString *errorReason = nil;
     @try {
-      acceptButton = [[self.alertElement fb_descendantsMatchingClassChain:FBConfiguration.acceptAlertButtonSelector
-                                         shouldReturnAfterFirstMatch:YES] firstObject];
+      acceptButton = [[alertElement fb_descendantsMatchingClassChain:FBConfiguration.acceptAlertButtonSelector
+                                           shouldReturnAfterFirstMatch:YES] firstObject];
     } @catch (NSException *ex) {
       errorReason = ex.reason;
     }
@@ -183,34 +246,50 @@
    }
   }
   if (nil == acceptButton) {
-    NSArray<XCUIElement *> *buttons = [self.alertElement.fb_query
-                                       descendantsMatchingType:XCUIElementTypeButton].allElementsBoundByIndex;
-    acceptButton = (alertSnapshot.elementType == XCUIElementTypeAlert || [self.class isSafariWebAlertWithSnapshot:alertSnapshot])
-      ? buttons.lastObject
-      : buttons.firstObject;
+    // buttonSnapshotsInSnapshot's tree-order walk doesn't always match a
+    // live query's ordering: on the system location-permission alert (iOS
+    // 17.5, confirmed via manual testing), that mismatch put a
+    // non-dismissing "Precise: On/Off" toggle first, so accept/dismiss
+    // silently tapped the wrong control and left the alert on screen. Not
+    // reproduced on iOS 18+, so keep the cheaper snapshot walk there and
+    // only pay for a live query below iOS 18.
+    if (@available(iOS 18.0, *)) {
+      NSArray<id<FBXCElementSnapshot>> *buttonSnapshots = [self.class fb_buttonSnapshotsInSnapshot:alertSnapshot];
+      id<FBXCElementSnapshot> chosenSnapshot = (alertSnapshot.elementType == XCUIElementTypeAlert || [self.class isSafariWebAlertWithSnapshot:alertSnapshot])
+        ? buttonSnapshots.lastObject
+        : buttonSnapshots.firstObject;
+      if (nil != chosenSnapshot) {
+        acceptButton = [XCUIApplication fb_elementForSnapshot:chosenSnapshot underElement:alertElement];
+      }
+    } else {
+      NSArray<XCUIElement *> *buttons = [alertElement.fb_query
+                                         descendantsMatchingType:XCUIElementTypeButton].allElementsBoundByIndex;
+      acceptButton = (alertSnapshot.elementType == XCUIElementTypeAlert || [self.class isSafariWebAlertWithSnapshot:alertSnapshot])
+        ? buttons.lastObject
+        : buttons.firstObject;
+    }
   }
   if (nil == acceptButton) {
-    return [[[FBErrorBuilder builder]
-        withDescriptionFormat:@"Failed to find accept button for alert: %@", self.alertElement]
-       buildError:error];
+    [self fb_raiseActionFailedExceptionWithReason:
+     [NSString stringWithFormat:@"Failed to find accept button for alert: %@", alertElement]];
   }
   [acceptButton tap];
-  return YES;
 }
 
-- (BOOL)dismissWithError:(NSError **)error
+- (void)dismiss
 {
-  if (!self.isPresent) {
-    return [self notPresentWithError:error];
+  XCUIElement *alertElement = self.alertElement;
+  id<FBXCElementSnapshot> alertSnapshot = self.alertSnapshot;
+  if (nil == alertElement || nil == alertSnapshot) {
+    [self fb_raiseNotPresentException];
   }
 
-  id<FBXCElementSnapshot> alertSnapshot = self.alertElement.lastSnapshot ?: [self.alertElement fb_customSnapshot];
   XCUIElement *dismissButton = nil;
   if (FBConfiguration.dismissAlertButtonSelector.length) {
     NSString *errorReason = nil;
     @try {
-      dismissButton = [[self.alertElement fb_descendantsMatchingClassChain:FBConfiguration.dismissAlertButtonSelector
-                                          shouldReturnAfterFirstMatch:YES] firstObject];
+      dismissButton = [[alertElement fb_descendantsMatchingClassChain:FBConfiguration.dismissAlertButtonSelector
+                                            shouldReturnAfterFirstMatch:YES] firstObject];
     } @catch (NSException *ex) {
       errorReason = ex.reason;
     }
@@ -224,54 +303,141 @@
     }
   }
   if (nil == dismissButton) {
-    NSArray<XCUIElement *> *buttons = [self.alertElement.fb_query
-                                       descendantsMatchingType:XCUIElementTypeButton].allElementsBoundByIndex;
-    dismissButton = (alertSnapshot.elementType == XCUIElementTypeAlert || [self.class isSafariWebAlertWithSnapshot:alertSnapshot])
-      ? buttons.firstObject
-      : buttons.lastObject;
+    // See the matching comment in accept.
+    if (@available(iOS 18.0, *)) {
+      NSArray<id<FBXCElementSnapshot>> *buttonSnapshots = [self.class fb_buttonSnapshotsInSnapshot:alertSnapshot];
+      id<FBXCElementSnapshot> chosenSnapshot = (alertSnapshot.elementType == XCUIElementTypeAlert || [self.class isSafariWebAlertWithSnapshot:alertSnapshot])
+        ? buttonSnapshots.firstObject
+        : buttonSnapshots.lastObject;
+      if (nil != chosenSnapshot) {
+        dismissButton = [XCUIApplication fb_elementForSnapshot:chosenSnapshot underElement:alertElement];
+      }
+    } else {
+      NSArray<XCUIElement *> *buttons = [alertElement.fb_query
+                                         descendantsMatchingType:XCUIElementTypeButton].allElementsBoundByIndex;
+      dismissButton = (alertSnapshot.elementType == XCUIElementTypeAlert || [self.class isSafariWebAlertWithSnapshot:alertSnapshot])
+        ? buttons.firstObject
+        : buttons.lastObject;
+    }
   }
 
   if (nil == dismissButton) {
-    return [[[FBErrorBuilder builder]
-        withDescriptionFormat:@"Failed to find dismiss button for alert: %@", self.alertElement]
-            buildError:error];
+    [self fb_raiseActionFailedExceptionWithReason:
+     [NSString stringWithFormat:@"Failed to find dismiss button for alert: %@", alertElement]];
   }
   [dismissButton tap];
-  return YES;
 }
 
-- (BOOL)clickAlertButton:(NSString *)label error:(NSError **)error
+- (void)clickAlertButton:(NSString *)label
 {
-  if (!self.isPresent) {
-    return [self notPresentWithError:error];
+  XCUIElement *alertElement = self.alertElement;
+  id<FBXCElementSnapshot> alertSnapshot = self.alertSnapshot;
+  if (nil == alertElement || nil == alertSnapshot) {
+    [self fb_raiseNotPresentException];
   }
 
-  NSPredicate *predicate = [NSPredicate predicateWithFormat:@"label == %@", label];
-  XCUIElement *requestedButton = [[self.alertElement descendantsMatchingType:XCUIElementTypeButton]
-                                  matchingPredicate:predicate].allElementsBoundByIndex.firstObject;
+  __block id<FBXCElementSnapshot> matchedSnapshot = nil;
+  [alertSnapshot enumerateDescendantsUsingBlock:^(id<FBXCElementSnapshot> descendant) {
+    if (nil != matchedSnapshot || descendant.elementType != XCUIElementTypeButton) {
+      return;
+    }
+    NSString *btnLabel = [FBXCElementSnapshotWrapper ensureWrapped:descendant].wdLabel;
+    if (nil != btnLabel && [btnLabel isEqualToString:label]) {
+      matchedSnapshot = descendant;
+    }
+  }];
+  XCUIElement *requestedButton = nil == matchedSnapshot
+    ? nil
+    : [XCUIApplication fb_elementForSnapshot:matchedSnapshot underElement:alertElement];
   if (!requestedButton) {
-    return [[[FBErrorBuilder builder]
-             withDescriptionFormat:@"Failed to find button with label '%@' for alert: %@", label, self.alertElement]
-            buildError:error];
+    [self fb_raiseActionFailedExceptionWithReason:
+     [NSString stringWithFormat:@"Failed to find button with label '%@' for alert: %@", label, alertElement]];
   }
   [requestedButton tap];
-  return YES;
 }
 
-- (XCUIElement *)alertElement
+- (void)clickElementMatchingClassChain:(NSString *)classChain
+{
+  XCUIElement *alertElement = self.alertElement;
+  if (nil == alertElement) {
+    [self fb_raiseNotPresentException];
+  }
+
+  // For a Safari web alert, alertElement is the containing scrollView, not
+  // the alert's own div (see fb_alertElementWithSnapshot:), so a classChain
+  // query from it could also match unrelated page content. Constrain
+  // matches to descendants of alertSnapshot by uid when available.
+  NSSet<NSString *> *alertSnapshotUids = nil;
+  id<FBXCElementSnapshot> alertSnapshot = self.alertSnapshot;
+  if (nil != alertSnapshot) {
+    NSMutableSet<NSString *> *uids = [NSMutableSet set];
+    NSString *rootUid = [FBXCElementSnapshotWrapper wdUIDWithSnapshot:alertSnapshot];
+    if (nil != rootUid) {
+      [uids addObject:rootUid];
+    }
+    [alertSnapshot enumerateDescendantsUsingBlock:^(id<FBXCElementSnapshot> descendant) {
+      NSString *uid = [FBXCElementSnapshotWrapper wdUIDWithSnapshot:descendant];
+      if (nil != uid) {
+        [uids addObject:uid];
+      }
+    }];
+    alertSnapshotUids = uids;
+  }
+
+  NSArray<XCUIElement *> *matches = nil;
+  @try {
+    matches = [alertElement fb_descendantsMatchingClassChain:classChain
+                                  shouldReturnAfterFirstMatch:NO];
+  } @catch (NSException *ex) {
+    [self fb_raiseActionFailedExceptionWithReason:
+     [NSString stringWithFormat:@"Failed to match class chain selector '%@' for alert: %@. Original error: %@", classChain, alertElement, ex.reason]];
+  }
+  XCUIElement *matchedElement = nil;
+  for (XCUIElement *match in matches) {
+    if (nil == alertSnapshotUids || [alertSnapshotUids containsObject:match.fb_uid]) {
+      matchedElement = match;
+      break;
+    }
+  }
+  if (nil == matchedElement) {
+    [self fb_raiseActionFailedExceptionWithReason:
+     [NSString stringWithFormat:@"Failed to find any element matching class chain selector '%@' for alert: %@", classChain, alertElement]];
+  }
+  [matchedElement tap];
+}
+
+// Single source of truth for alert detection: checks each candidate
+// application (systemApp, then self.application if different, then the iOS
+// 18+ limited access prompt app) via targeted, predicate-filtered live
+// queries (see XCUIApplication.fb_alertElementWithSnapshot:) instead of
+// snapshotting and walking the whole application tree - the cost stays
+// proportional to the number of alert-shaped elements rather than the
+// size/depth of the app, which matters a lot for deeply nested view
+// hierarchies. Only ever invoked once per instance, by the alertElement
+// getter above, which caches both the element and (if one comes back) the
+// snapshot obtained as a side effect of resolving it.
+- (nullable XCUIElement *)alertElementFromApplication:(id<FBXCElementSnapshot> _Nullable *)snapshotOut
 {
-  if (nil == self.element) {
+  @try {
     XCUIApplication *systemApp = XCUIApplication.fb_systemApplication;
-    if ([systemApp fb_isSameAppAs:self.application]) {
-      self.element = systemApp.fb_alertElement;
-    } else {
-      self.element = systemApp.fb_alertElement ?: self.application.fb_alertElement;
+    NSMutableArray<XCUIApplication *> *candidates = [NSMutableArray arrayWithObject:systemApp];
+    if (![systemApp fb_isSameAppAs:self.application]) {
+      [candidates addObject:self.application];
     }
-    if (nil == self.element) {
-      self.element = [XCUIApplication fb_limitedAccessPromptAlertElement];
+    XCUIApplication *promptApp = XCUIApplication.fb_limitedAccessPromptApplication;
+    if (nil != promptApp) {
+      [candidates addObject:promptApp];
     }
+    for (XCUIApplication *candidate in candidates) {
+      XCUIElement *element = [candidate fb_alertElementWithSnapshot:snapshotOut];
+      if (nil != element) {
+        return element;
+      }
+    }
+  } @catch (NSException *) {
+    return nil;
   }
-  return self.element;
+  return nil;
 }
 
 @end

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentLib/Routing/FBExceptionHandler.m

@@ -28,9 +28,13 @@
     commandStatus = [FBCommandStatus invalidArgumentErrorWithMessage:exception.reason
                                                            traceback:traceback];
   } else if ([exception.name isEqualToString:FBApplicationCrashedException]
-             || [exception.name isEqualToString:FBApplicationDeadlockDetectedException]) {
+             || [exception.name isEqualToString:FBApplicationDeadlockDetectedException]
+             || [exception.name isEqualToString:FBAlertActionFailedException]) {
     commandStatus = [FBCommandStatus invalidElementStateErrorWithMessage:exception.reason
                                                                traceback:traceback];
+  } else if ([exception.name isEqualToString:FBAlertSetTextFailedException]) {
+    commandStatus = [FBCommandStatus unsupportedOperationErrorWithMessage:exception.reason
+                                                                traceback:traceback];
   } else if ([exception.name isEqualToString:FBInvalidXPathException]
              || [exception.name isEqualToString:FBClassChainQueryParseException]) {
     commandStatus = [FBCommandStatus invalidSelectorErrorWithMessage:exception.reason
@@ -47,6 +51,9 @@
   } else if ([exception.name isEqualToString:FBSessionCreationException]) {
     commandStatus = [FBCommandStatus sessionNotCreatedError:exception.reason
                                                   traceback:traceback];
+  } else if ([exception.name isEqualToString:FBAlertNotPresentException]) {
+    commandStatus = [FBCommandStatus noAlertOpenErrorWithMessage:exception.reason
+                                                       traceback:traceback];
   } else {
     commandStatus = [FBCommandStatus unknownErrorWithMessage:exception.reason
                                                    traceback:traceback];

package/WebDriverAgentLib/Routing/FBExceptions.h

@@ -57,4 +57,13 @@ extern NSString *const FBApplicationMissingException;
 /*! Exception used to notify about WDA incompatibility with the current platform version */
 extern NSString *const FBIncompatibleWdaException;
 
+/*! Exception used to notify that no alert is currently present */
+extern NSString *const FBAlertNotPresentException;
+
+/*! Exception used to notify that an alert action (e.g. finding a button to tap) could not complete, although the alert itself is present */
+extern NSString *const FBAlertActionFailedException;
+
+/*! Exception used to notify that typing text into an alert failed (e.g. no or multiple input fields) */
+extern NSString *const FBAlertSetTextFailedException;
+
 NS_ASSUME_NONNULL_END

package/WebDriverAgentLib/Routing/FBExceptions.m

@@ -22,3 +22,6 @@ NSString *const FBClassChainQueryParseException = @"FBClassChainQueryParseExcept
 NSString *const FBApplicationCrashedException = @"FBApplicationCrashedException";
 NSString *const FBApplicationMissingException = @"FBApplicationMissingException";
 NSString *const FBIncompatibleWdaException = @"FBIncompatibleWdaException";
+NSString *const FBAlertNotPresentException = @"FBAlertNotPresentException";
+NSString *const FBAlertActionFailedException = @"FBAlertActionFailedException";
+NSString *const FBAlertSetTextFailedException = @"FBAlertSetTextFailedException";