appium-webdriveragent 16.14.2 → 16.15.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [16.15.0](https://github.com/appium/WebDriverAgent/compare/v16.14.2...v16.15.0) (2026-10-12)
+
+### Features
+
+* add asAppUnderTest flag to /wda/apps/launch ([#1289](https://github.com/appium/WebDriverAgent/issues/1289)) ([f5c0688](https://github.com/appium/WebDriverAgent/commit/f5c068873ff6dcd1ce444d26246c102cc379d5bf))
+
 ## [16.14.2](https://github.com/appium/WebDriverAgent/compare/v16.14.1...v16.14.2) (2026-10-08)
 
 ### Bug Fixes

package/WebDriverAgentLib/Commands/FBSessionCommands.m

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

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentLib/Routing/FBSession.h

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

package/WebDriverAgentLib/Routing/FBSession.m

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

package/WebDriverAgentTests/IntegrationTests/FBSessionIntegrationTests.m

@@ -16,6 +16,7 @@
 #import "FBTestMacros.h"
 #import "FBUnattachedAppLauncher.h"
 #import "XCUIApplication+FBHelpers.h"
+#import "XCUIApplication+FBQuiescence.h"
 #import "XCUIApplication.h"
 
 @interface FBSession (Tests)
@@ -101,6 +102,76 @@ static NSString *const SETTINGS_BUNDLE_ID = @"com.apple.Preferences";
   FBAssertWaitTillBecomesTrue([self.session.activeApplication.bundleID isEqualToString:testedApp.bundleID]);
 }
 
+- (NSString *)startSessionWithoutApplicationUnderTest
+{
+  NSString *bundleId = (NSString *)self.testedApplication.bundleID;
+  [self.testedApplication terminate];
+  FBAssertWaitTillBecomesTrue(self.testedApplication.state == XCUIApplicationStateNotRunning);
+  self.session = [FBSession initWithApplication:nil];
+  return bundleId;
+}
+
+- (void)testApplicationCanBeLaunchedAsApplicationUnderTest
+{
+  NSString *bundleId = [self startSessionWithoutApplicationUnderTest];
+  XCUIApplication *app = [self.session launchApplicationWithBundleId:bundleId
+                                             shouldWaitForQuiescence:nil
+                                                           arguments:nil
+                                                         environment:nil
+                                              asApplicationUnderTest:YES];
+  FBAssertWaitTillBecomesTrue([self.session.activeApplication.bundleID isEqualToString:bundleId]);
+  XCTAssertEqual(app, self.session.activeApplication);
+  XCTAssertTrue(app.fb_shouldWaitForQuiescence);
+
+  XCUIApplication *settingsApp = [self.session launchApplicationWithBundleId:SETTINGS_BUNDLE_ID
+                                                     shouldWaitForQuiescence:nil
+                                                                   arguments:nil
+                                                                 environment:nil];
+  FBAssertWaitTillBecomesTrue([self.session.activeApplication.bundleID isEqualToString:SETTINGS_BUNDLE_ID]);
+  XCTAssertTrue(settingsApp.fb_shouldWaitForQuiescence);
+}
+
+- (void)testApplicationLaunchedAsApplicationUnderTestRespectsQuiescenceArgument
+{
+  NSString *bundleId = [self startSessionWithoutApplicationUnderTest];
+  XCUIApplication *app = [self.session launchApplicationWithBundleId:bundleId
+                                             shouldWaitForQuiescence:@NO
+                                                           arguments:nil
+                                                         environment:nil
+                                              asApplicationUnderTest:YES];
+  FBAssertWaitTillBecomesTrue([self.session.activeApplication.bundleID isEqualToString:bundleId]);
+  XCTAssertEqual(app, self.session.activeApplication);
+  XCTAssertFalse(app.fb_shouldWaitForQuiescence);
+}
+
+- (void)testCrashOfApplicationLaunchedAsApplicationUnderTestIsDetected
+{
+  NSString *bundleId = [self startSessionWithoutApplicationUnderTest];
+  XCUIApplication *app = [self.session launchApplicationWithBundleId:bundleId
+                                             shouldWaitForQuiescence:nil
+                                                           arguments:nil
+                                                         environment:nil
+                                              asApplicationUnderTest:YES];
+  FBAssertWaitTillBecomesTrue([self.session.activeApplication.bundleID isEqualToString:bundleId]);
+  [app terminate];
+  FBAssertWaitTillBecomesTrue(app.state == XCUIApplicationStateNotRunning);
+  XCTAssertThrowsSpecificNamed(self.session.activeApplication, NSException, FBApplicationCrashedException);
+}
+
+- (void)testApplicationIsNotLaunchedAsApplicationUnderTestByDefault
+{
+  NSString *bundleId = [self startSessionWithoutApplicationUnderTest];
+  XCUIApplication *app = [self.session launchApplicationWithBundleId:bundleId
+                                             shouldWaitForQuiescence:nil
+                                                           arguments:nil
+                                                         environment:nil];
+  FBAssertWaitTillBecomesTrue([self.session.activeApplication.bundleID isEqualToString:bundleId]);
+  XCTAssertFalse(app.fb_shouldWaitForQuiescence);
+  [app terminate];
+  FBAssertWaitTillBecomesTrue(app.state == XCUIApplicationStateNotRunning);
+  XCTAssertNoThrow(self.session.activeApplication);
+}
+
 - (void)testLaunchUnattachedApp
 {
   [FBUnattachedAppLauncher launchAppWithBundleId:SETTINGS_BUNDLE_ID];

package/package.json

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