@devicelab/maestro-runner-darwin-arm64 1.1.27 → 1.1.28

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBResponseJSONPayload.m

@@ -43,9 +43,8 @@
   NSData *jsonData = [NSJSONSerialization dataWithJSONObject:self.dictionary
                                                      options:NSJSONWritingPrettyPrinted
                                                        error:&error];
-  NSCAssert(jsonData, @"Valid JSON must be responded, error of %@", error);
-  if (nil == [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding]) {
-    [FBLogger log:@"The incoming data cannot be encoded to UTF-8 JSON. Applying lossy conversion as a workaround."];
+  if (nil == jsonData || nil == [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding]) {
+    [FBLogger log:@"JSON serialization failed or produced non-UTF-8 data. Applying lossy conversion as a workaround."];
     jsonData = [NSJSONSerialization dataWithJSONObject:[self.dictionary fb_utf8SafeDictionary]
                                                options:NSJSONWritingPrettyPrinted
                                                  error:&error];

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBResponsePayload.m

@@ -120,7 +120,7 @@ inline NSDictionary *FBDictionaryResponseWithElement(XCUIElement *element, BOOL
 
     NSMutableDictionary *result = compactResult.mutableCopy;
     FBXCElementSnapshotWrapper *wrappedSnapshot = [FBXCElementSnapshotWrapper ensureWrapped:snapshot];
-    NSArray *fields = [FBConfiguration.elementResponseAttributes componentsSeparatedByString:@","];
+    NSArray *fields = [FBConfiguration.sharedInstance.elementResponseAttributes componentsSeparatedByString:@","];
     for (NSString *field in fields) {
       // 'name' here is the w3c-approved identifier for what we mean by 'type'
       if ([field isEqualToString:@"name"] || [field isEqualToString:@"type"]) {

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBRoute.h

@@ -27,6 +27,9 @@ typedef __nonnull id<FBResponsePayload> (^FBRouteSyncHandler)(FBRouteRequest *re
 /*! Route's path */
 @property (nonatomic, copy, readonly) NSString *path;
 
+/*! Whether this route bypasses the shared route queue - see -standalone */
+@property (nonatomic, assign, readonly) BOOL isStandalone;
+
 /**
  Convenience constructor for GET route with given pathPattern
  */
@@ -67,6 +70,12 @@ typedef __nonnull id<FBResponsePayload> (^FBRouteSyncHandler)(FBRouteRequest *re
  */
 - (instancetype)withoutSession;
 
+/**
+ Chain-able constructor for a route that bypasses the shared route queue - see FBHTTPServer.h's
+ -handleMethod:withPath:standalone:block: for what that changes about how/when the handler runs.
+ */
+- (instancetype)standalone;
+
 /**
  Dispatches response for request
  */

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBRoute.m

@@ -18,6 +18,7 @@
 
 @interface FBRoute ()
 @property (nonatomic, assign, readwrite) BOOL requiresSession;
+@property (nonatomic, assign, readwrite) BOOL isStandalone;
 @property (nonatomic, copy, readwrite) NSString *verb;
 @property (nonatomic, copy, readwrite) NSString *path;
 
@@ -126,10 +127,17 @@ static NSString *const FBRouteSessionPrefix = @"/session/:sessionID";
   return self;
 }
 
+- (instancetype)standalone
+{
+  self.isStandalone = YES;
+  return self;
+}
+
 - (instancetype)respondWithBlock:(FBRouteSyncHandler)handler
 {
   FBRoute_Sync *route = [FBRoute_Sync withVerb:self.verb path:self.path requiresSession:self.requiresSession];
   route.handler = handler;
+  route.isStandalone = self.isStandalone;
   return route;
 }
 
@@ -138,6 +146,7 @@ static NSString *const FBRouteSessionPrefix = @"/session/:sessionID";
   FBRoute_TargetAction *route = [FBRoute_TargetAction withVerb:self.verb path:self.path requiresSession:self.requiresSession];
   route.target = target;
   route.action = action;
+  route.isStandalone = self.isStandalone;
   return route;
 }
 

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBScreenRecordingContainer.h

@@ -44,6 +44,15 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (void)reset;
 
+/**
+ Resets the container, but only if it still keeps the given promise. The comparison and the
+ reset are performed atomically, so a promise stored concurrently is never dropped.
+
+ @param screenRecordingPromise the promise the caller expects to be still active
+ @return YES if the container has been reset
+ */
+- (BOOL)resetIfPromiseIs:(FBScreenRecordingPromise *)screenRecordingPromise;
+
 /**
  Transforms the container content to a dictionary.
 

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBScreenRecordingContainer.m

@@ -36,23 +36,39 @@
                                 fps:(NSUInteger)fps
                               codec:(long long)codec;
 {
-  self.fps = fps;
-  self.codec = codec;
-  self.screenRecordingPromise = screenRecordingPromise;
-  self.startedAt = @([NSDate.date timeIntervalSince1970]);
+  @synchronized (self) {
+    self.fps = fps;
+    self.codec = codec;
+    self.screenRecordingPromise = screenRecordingPromise;
+    self.startedAt = @([NSDate.date timeIntervalSince1970]);
+  }
 }
 
 - (void)reset;
 {
-  self.fps = 0;
-  self.codec = 0;
-  if (nil != self.screenRecordingPromise) {
-    [XCTContext runActivityNamed:@"Video Cleanup" block:^(id<XCTActivity> activity){
-      [activity addAttachment:(XCTAttachment *)self.screenRecordingPromise.nativePromise];
-    }];
-    self.screenRecordingPromise = nil;
+  @synchronized (self) {
+    self.fps = 0;
+    self.codec = 0;
+    if (nil != self.screenRecordingPromise) {
+      [XCTContext runActivityNamed:@"Video Cleanup" block:^(id<XCTActivity> activity){
+        [activity addAttachment:(XCTAttachment *)self.screenRecordingPromise.nativePromise];
+      }];
+      self.screenRecordingPromise = nil;
+    }
+    self.startedAt = nil;
+  }
+}
+
+- (BOOL)resetIfPromiseIs:(FBScreenRecordingPromise *)screenRecordingPromise
+{
+  // @synchronized is recursive, so -reset may take the very same lock again below.
+  @synchronized (self) {
+    if (self.screenRecordingPromise != screenRecordingPromise) {
+      return NO;
+    }
+    [self reset];
+    return YES;
   }
-  self.startedAt = nil;
 }
 
 - (nullable NSDictionary *)toDictionary

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBScreenRecordingRequest.m

@@ -46,7 +46,7 @@
   [videoEncodingInitInvocation setSelector:videoEncodingConstructorSelector];
   long long codec = self.codec;
   [videoEncodingInitInvocation setArgument:&codec atIndex:2];
-  double frameRate = self.fps;
+  double frameRate = (double)self.fps;
   [videoEncodingInitInvocation setArgument:&frameRate atIndex:3];
   [videoEncodingInitInvocation invokeWithTarget:videoEncodingAllocated];
   id __unsafe_unretained result;

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBSession.h

@@ -16,6 +16,12 @@ NS_ASSUME_NONNULL_BEGIN
 /** Bundle identifier of Mobile Safari browser */
 extern NSString* const FB_SAFARI_BUNDLE_ID;
 
+/**
+ Posted (synchronously, on whatever thread calls -kill) once a session has been torn down. The
+ notification's object is the FBSession instance that was killed - see -identifier.
+ */
+extern NSString* const FBSessionWasKilledNotification;
+
 /**
  Class that represents testing session
  */
@@ -44,6 +50,16 @@ extern NSString* const FB_SAFARI_BUNDLE_ID;
 
 + (nullable instancetype)activeSession;
 
+/**
+ Kills the active session, if any, and blocks until its teardown - including one already started
+ by a concurrent caller - is fully finished. Call this before preparing/launching a replacement
+ application, so it can't race a still-in-progress termination of the outgoing one.
+
+ @throws FBSessionCreationException if the outgoing application's termination is still in flight
+ after the wait, since a replacement must never start while that termination can still land.
+ */
++ (void)killActiveSessionAndWaitForTeardown;
+
 /**
  Fetches session for given identifier.
  If identifier doesn't match activeSession identifier, will return nil.

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Routing/FBSession.m

@@ -24,7 +24,6 @@
 #import "FBXCTestDaemonsProxy.h"
 #import "XCUIApplication+FBQuiescence.h"
 #import "XCUIElement.h"
-#import "XCUIElement+FBClassChain.h"
 
 /*!
  The intial value for the default application property.
@@ -35,12 +34,23 @@ NSString *const FBDefaultApplicationAuto = @"auto";
 
 NSString *const FB_SAFARI_BUNDLE_ID = @"com.apple.mobilesafari";
 
+// FBXCAXClientProxy's shared accessibility channel can be stuck servicing another request.
+static const NSTimeInterval FB_IS_SYSTEM_APP_CHECK_TIMEOUT_SEC = 5.;
+// -terminate hard-asserts off the main thread, which may itself be busy - see -fb_terminate...:.
+static const NSTimeInterval FB_APP_TERMINATE_TIMEOUT_SEC = 5.;
+// How long a -kill caller that lost the race below waits for the winner's teardown to finish.
+static const NSTimeInterval FB_KILL_WAIT_TIMEOUT_SEC = 35.;
+NSString *const FBSessionWasKilledNotification = @"FBSessionWasKilledNotification";
+
 @interface FBSession ()
 @property (nullable, nonatomic) XCUIApplication *testedApplication;
 @property (nonatomic) BOOL isTestedApplicationExpectedToRun;
 @property (nonatomic) BOOL shouldAppsWaitForQuiescence;
 @property (nonatomic, nullable) FBAlertsMonitor *alertsMonitor;
 @property (nonatomic, readwrite) NSMutableDictionary<NSNumber *, NSMutableDictionary<NSString *, NSNumber *> *> *elementsVisibilityCache;
+
+- (BOOL)fb_isTestedApplicationSameAsSystemAppWithTimeout:(NSTimeInterval)timeout;
+- (void)fb_terminateTestedApplicationWithTimeout:(NSTimeInterval)timeout generation:(NSUInteger)generation;
 @end
 
 @interface FBSession (FBAlertsMonitorDelegate)
@@ -53,17 +63,13 @@ NSString *const FB_SAFARI_BUNDLE_ID = @"com.apple.mobilesafari";
 
 - (void)didDetectAlert:(FBAlert *)alert
 {
-  NSString *autoClickAlertSelector = FBConfiguration.autoClickAlertSelector;
+  NSString *autoClickAlertSelector = FBConfiguration.sharedInstance.autoClickAlertSelector;
   if ([autoClickAlertSelector length] > 0) {
     @try {
-      NSArray<XCUIElement*> *matches = [alert.alertElement fb_descendantsMatchingClassChain:autoClickAlertSelector
-                                                                shouldReturnAfterFirstMatch:YES];
-      if (matches.count > 0) {
-          [[matches objectAtIndex:0] tap];
-      }
+      [alert clickElementMatchingClassChain:autoClickAlertSelector];
     } @catch (NSException *e) {
       [FBLogger logFmt:@"Could not click at the alert element '%@'. Original error: %@",
-       autoClickAlertSelector, e.description];
+        autoClickAlertSelector, e.reason];
     }
     // This setting has priority over other settings if enabled
     return;
@@ -73,14 +79,17 @@ NSString *const FB_SAFARI_BUNDLE_ID = @"com.apple.mobilesafari";
     return;
   }
 
-  NSError *error;
   if ([self.defaultAlertAction isEqualToString:@"accept"]) {
-    if (![alert acceptWithError:&error]) {
-      [FBLogger logFmt:@"Cannot accept the alert. Original error: %@", error.description];
+    @try {
+      [alert accept];
+    } @catch (NSException *e) {
+      [FBLogger logFmt:@"Cannot accept the alert. Original error: %@", e.reason];
     }
   } else if ([self.defaultAlertAction isEqualToString:@"dismiss"]) {
-    if (![alert dismissWithError:&error]) {
-      [FBLogger logFmt:@"Cannot dismiss the alert. Original error: %@", error.description];
+    @try {
+      [alert dismiss];
+    } @catch (NSException *e) {
+      [FBLogger logFmt:@"Cannot dismiss the alert. Original error: %@", e.reason];
     }
   } else {
     [FBLogger logFmt:@"'%@' default alert action is unsupported", self.defaultAlertAction];
@@ -91,19 +100,126 @@ NSString *const FB_SAFARI_BUNDLE_ID = @"com.apple.mobilesafari";
 
 @implementation FBSession
 
+// Guarded, together with the two counters below, by +teardownCondition.
 static FBSession *_activeSession = nil;
+// Class-level, not per-instance: a caller that finds _activeSession already nil (a concurrent
+// -kill beat it there) still needs to know whether that -kill's teardown is done, since it cleared
+// the pointer before running it. See +waitForActiveTeardownWithTimeout:.
+// A count, not a flag: the bounded wait below lets teardowns overlap, so one of them finishing
+// must not wake waiters while another still runs.
+static NSUInteger _activeTeardownCount = 0;
+// Bumped once a caller owns the device, before it launches anything; a teardown still running past
+// the bounded wait re-checks it before touching process-wide state.
+static NSUInteger _sessionGeneration = 0;
+// Teardowns that have claimed the current generation and are committed to terminating the app.
+// The generation bump waits for these to drain, so a claim and a bump can never interleave.
+static NSUInteger _committedTerminationCount = 0;
+
++ (NSCondition *)teardownCondition
+{
+  static NSCondition *condition;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    condition = [NSCondition new];
+  });
+  return condition;
+}
+
+// Waits (bounded) for every -kill teardown currently in progress to finish.
++ (void)waitForActiveTeardownWithTimeout:(NSTimeInterval)timeout
+{
+  NSCondition *condition = self.teardownCondition;
+  [condition lock];
+  NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:timeout];
+  while (_activeTeardownCount > 0 && [condition waitUntilDate:deadline]) {
+  }
+  [condition unlock];
+}
 
 + (instancetype)activeSession
 {
-  return _activeSession;
+  NSCondition *condition = self.teardownCondition;
+  [condition lock];
+  FBSession *session = _activeSession;
+  [condition unlock];
+  return session;
 }
 
-+ (void)markSessionActive:(FBSession *)session
++ (void)killActiveSessionAndWaitForTeardown
 {
-  if (_activeSession) {
-    [_activeSession kill];
+  FBSession *session = self.activeSession;
+  if (nil != session) {
+    // Runs the real teardown synchronously if this call wins the race in -kill, or waits for
+    // whoever did to finish if it lost - either way, blocks until torn down.
+    [session kill];
+  } else {
+    // _activeSession is already nil, but a concurrent -kill (e.g. from DELETE /session) may still
+    // be mid-teardown - wait for it, so we don't launch a replacement app too early.
+    [self waitForActiveTeardownWithTimeout:FB_KILL_WAIT_TIMEOUT_SEC];
+  }
+  // Claimed before the caller launches its replacement app: if the bounded wait expired with a
+  // teardown still running, that teardown must be stale by the time the new app exists.
+  NSCondition *condition = self.teardownCondition;
+  [condition lock];
+  // A committed -terminate cannot be revoked, so the next generation must never be handed out
+  // while one is in flight - give up on the new session instead of racing it.
+  NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:FB_APP_TERMINATE_TIMEOUT_SEC];
+  while (_committedTerminationCount > 0 && [condition waitUntilDate:deadline]) {
+  }
+  BOOL isTerminationPending = _committedTerminationCount > 0;
+  if (!isTerminationPending) {
+    _sessionGeneration++;
+  }
+  [condition unlock];
+  if (isTerminationPending) {
+    NSString *reason = [NSString stringWithFormat:@"The termination of a previous session's application is still in progress after %@ seconds. Please retry the session creation later", @(FB_APP_TERMINATE_TIMEOUT_SEC)];
+    @throw [NSException exceptionWithName:FBSessionCreationException reason:reason userInfo:nil];
   }
+}
+
++ (void)markSessionActive:(FBSession *)session
+{
+  [self killActiveSessionAndWaitForTeardown];
+  NSCondition *condition = self.teardownCondition;
+  [condition lock];
   _activeSession = session;
+  [condition unlock];
+}
+
+// Validates and claims `generation` in one critical section, so no replacement can be handed the
+// next generation until the matching +endTermination. NO means this teardown is already stale.
++ (BOOL)beginTerminationForGeneration:(NSUInteger)generation
+{
+  NSCondition *condition = self.teardownCondition;
+  [condition lock];
+  BOOL isCurrent = generation == _sessionGeneration;
+  if (isCurrent) {
+    _committedTerminationCount++;
+  }
+  [condition unlock];
+  return isCurrent;
+}
+
++ (void)endTermination
+{
+  NSCondition *condition = self.teardownCondition;
+  [condition lock];
+  _committedTerminationCount--;
+  [condition broadcast];
+  [condition unlock];
+}
+
+// Read in the same critical section that validates the generation: a replacement would have bumped
+// the generation before storing anything, so a promise captured here can never be its.
++ (FBScreenRecordingPromise *)activeScreenRecordingForGeneration:(NSUInteger)generation
+{
+  NSCondition *condition = self.teardownCondition;
+  [condition lock];
+  FBScreenRecordingPromise *promise = generation == _sessionGeneration
+    ? FBScreenRecordingContainer.sharedInstance.screenRecordingPromise
+    : nil;
+  [condition unlock];
+  return promise;
 }
 
 + (instancetype)sessionWithIdentifier:(NSString *)identifier
@@ -111,10 +227,9 @@ static FBSession *_activeSession = nil;
   if (!identifier) {
     return nil;
   }
-  if (![identifier isEqualToString:_activeSession.identifier]) {
-    return nil;
-  }
-  return _activeSession;
+  // A single snapshot: reading the global twice could validate one session and return another.
+  FBSession *session = self.activeSession;
+  return [identifier isEqualToString:session.identifier] ? session : nil;
 }
 
 + (instancetype)initWithApplication:(XCUIApplication *)application
@@ -171,33 +286,65 @@ static FBSession *_activeSession = nil;
 
 - (void)kill
 {
-  if (nil == _activeSession) {
+  // DELETE /session and session creation can now run concurrently, so a session already
+  // superseded by a newer one can still reach here via a stale reference. Check-and-clear must be
+  // atomic, else a belated -kill could null out the new session's pointer instead of its own.
+  NSCondition *teardownCondition = self.class.teardownCondition;
+  BOOL wasActive;
+  NSUInteger generation;
+  [teardownCondition lock];
+  wasActive = (self == _activeSession);
+  // Captured so the teardown steps below can tell whether a replacement has claimed the device.
+  generation = _sessionGeneration;
+  if (wasActive) {
+    _activeSession = nil;
+    // Registered in the same critical section as the clear above, else a concurrent session
+    // creation could observe neither an active session nor a teardown and skip its wait.
+    _activeTeardownCount++;
+  }
+  [teardownCondition unlock];
+  if (!wasActive) {
+    // Someone else is already tearing this session down - wait for that to finish (bounded), so
+    // we don't act as if it's gone (e.g. launch a new app) while its -terminate is still in flight.
+    [self.class waitForActiveTeardownWithTimeout:FB_KILL_WAIT_TIMEOUT_SEC];
     return;
   }
 
-  [self disableAlertsMonitor];
+  @try {
+    // Posted before teardown so pending HTTP requests for this session can stop waiting sooner.
+    [NSNotificationCenter.defaultCenter postNotificationName:FBSessionWasKilledNotification object:self];
 
-  FBScreenRecordingPromise *activeScreenRecording = FBScreenRecordingContainer.sharedInstance.screenRecordingPromise;
-  if (nil != activeScreenRecording) {
-    NSError *error;
-    if (![FBXCTestDaemonsProxy stopScreenRecordingWithUUID:activeScreenRecording.identifier error:&error]) {
-      [FBLogger logFmt:@"%@", error];
+    [self disableAlertsMonitor];
+
+    // The container is process-wide, so only act on a promise captured while this teardown still
+    // owned the generation - nil here means it is stale and must leave the recording alone.
+    FBScreenRecordingPromise *activeScreenRecording = [self.class activeScreenRecordingForGeneration:generation];
+    if (nil != activeScreenRecording) {
+      NSError *error;
+      if (![FBXCTestDaemonsProxy stopScreenRecordingWithUUID:activeScreenRecording.identifier error:&error]) {
+        [FBLogger logFmt:@"%@", error];
+      }
+      // Identity, not generation: the stop above may outlast a replacement storing its own promise.
+      // Compare-and-reset, so that replacement's store cannot land between the check and the reset.
+      [FBScreenRecordingContainer.sharedInstance resetIfPromiseIs:activeScreenRecording];
     }
-    [FBScreenRecordingContainer.sharedInstance reset];
-  }
 
-  if (nil != self.testedApplication
-      && FBConfiguration.shouldTerminateApp
-      && self.testedApplication.running
-      && ![self.testedApplication fb_isSameAppAs:XCUIApplication.fb_systemApplication]) {
-    @try {
-      [self.testedApplication terminate];
-    } @catch (NSException *e) {
-      [FBLogger logFmt:@"%@", e.description];
+    if (nil != self.testedApplication
+        && FBConfiguration.sharedInstance.shouldTerminateApp
+        && self.testedApplication.running
+        && ![self fb_isTestedApplicationSameAsSystemAppWithTimeout:FB_IS_SYSTEM_APP_CHECK_TIMEOUT_SEC]) {
+      // Blocks until the app is either actually terminated or durably given up on (never left
+      // pending) - see -fb_terminateTestedApplicationWithTimeout:generation: - so it's safe to
+      // report this teardown as finished as soon as this returns.
+      [self fb_terminateTestedApplicationWithTimeout:FB_APP_TERMINATE_TIMEOUT_SEC generation:generation];
     }
+  } @finally {
+    [teardownCondition lock];
+    _activeTeardownCount--;
+    // Unconditional: waiters re-check the count, so a wake-up mid-teardown just puts them back.
+    [teardownCondition broadcast];
+    [teardownCondition unlock];
   }
-
-  _activeSession = nil;
 }
 
 - (XCUIApplication *)activeApplication
@@ -213,13 +360,13 @@ static FBSession *_activeSession = nil;
     XCUIApplicationState testedAppState = self.testedApplication.state;
     if (testedAppState >= XCUIApplicationStateRunningForeground) {
       NSPredicate *searchPredicate = [NSPredicate predicateWithFormat:@"%K == %@ OR %K IN {%@, %@}",
-                                      @"elementType", @(XCUIElementTypeAlert), 
+                                      @"elementType", @(XCUIElementTypeAlert),
                                       // To look for `SBTransientOverlayWindow` elements. See https://github.com/appium/WebDriverAgent/pull/946
                                       @"identifier", @"SBTransientOverlayWindow",
                                       // To look for 'criticalAlertSetting' elements https://developer.apple.com/documentation/usernotifications/unnotificationsettings/criticalalertsetting
                                       // See https://github.com/appium/appium/issues/20835
                                       @"NotificationShortLookView"];
-      if ([FBConfiguration shouldRespectSystemAlerts]
+      if (FBConfiguration.sharedInstance.shouldRespectSystemAlerts
           && [[XCUIApplication.fb_systemApplication descendantsMatchingType:XCUIElementTypeAny]
               matchingPredicate:searchPredicate].count > 0) {
         return XCUIApplication.fb_systemApplication;
@@ -292,4 +439,67 @@ static FBSession *_activeSession = nil;
     : [[XCUIApplication alloc] initWithBundleIdentifier:bundleIdentifier];
 }
 
+// Has no async variant and can block on the shared accessibility channel. Run off-thread and give
+// up after `timeout`, assuming the tested app IS the system app - safer, since it means skipping
+// termination rather than risking terminating springboard.
+- (BOOL)fb_isTestedApplicationSameAsSystemAppWithTimeout:(NSTimeInterval)timeout
+{
+  __block XCUIApplication *systemApp = nil;
+  __block NSException *caughtException = nil;
+  dispatch_semaphore_t sem = dispatch_semaphore_create(0);
+  dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+    // Undocumented private API; guard in case it hard-asserts off-main like -terminate does on
+    // some Xcode/iOS version - uncaught, that would crash the whole process.
+    @try {
+      systemApp = XCUIApplication.fb_systemApplication;
+    } @catch (NSException *e) {
+      caughtException = e;
+    }
+    dispatch_semaphore_signal(sem);
+  });
+  int64_t timeoutNs = (int64_t)(timeout * NSEC_PER_SEC);
+  if (0 != dispatch_semaphore_wait(sem, dispatch_time(DISPATCH_TIME_NOW, timeoutNs)) || nil != caughtException) {
+    [FBLogger logFmt:@"Could not determine the system application within %@ seconds%@; assuming '%@' might be it and skipping its termination", @(timeout), nil == caughtException ? @"" : [NSString stringWithFormat:@" (%@)", caughtException.description], self.testedApplication.bundleID];
+    return YES;
+  }
+  return [self.testedApplication fb_isSameAppAs:systemApp];
+}
+
+// -terminate hard-asserts off-main, but -kill can now run on a background queue. Dispatching to
+// main and waiting indefinitely could hang just as long as main is stuck, so give up after
+// `timeout` - but a "given up on" call must never still terminate whatever's running by the time
+// main gets to it (e.g. a replacement session's app), so cancellation and the actual terminate
+// call share a lock: whichever gets there first - the dispatched block, or the timeout - wins.
+- (void)fb_terminateTestedApplicationWithTimeout:(NSTimeInterval)timeout generation:(NSUInteger)generation
+{
+  XCUIApplication *application = self.testedApplication;
+  NSObject *lock = [NSObject new];
+  __block BOOL isAllowedToTerminate = YES;
+  dispatch_semaphore_t sem = dispatch_semaphore_create(0);
+  dispatch_async(dispatch_get_main_queue(), ^{
+    @synchronized (lock) {
+      // Re-checked here, not before dispatching: this block can sit on a busy main queue past the
+      // teardown wait, and a replacement usually runs the same bundle ID as the app to terminate.
+      // The claim is held across -terminate, so no replacement can take the next generation mid-call.
+      if (isAllowedToTerminate && [self.class beginTerminationForGeneration:generation]) {
+        @try {
+          [application terminate];
+        } @catch (NSException *e) {
+          [FBLogger logFmt:@"%@", e.description];
+        } @finally {
+          [self.class endTermination];
+        }
+      }
+    }
+    dispatch_semaphore_signal(sem);
+  });
+  int64_t timeoutNs = (int64_t)(timeout * NSEC_PER_SEC);
+  if (0 != dispatch_semaphore_wait(sem, dispatch_time(DISPATCH_TIME_NOW, timeoutNs))) {
+    @synchronized (lock) {
+      isAllowedToTerminate = NO;
+    }
+    [FBLogger logFmt:@"Could not terminate '%@' within %@ seconds; giving up on it rather than risk terminating a possible replacement session's app later", application.bundleID, @(timeout)];
+  }
+}
+
 @end