appium-mac2-driver 4.3.6 → 4.5.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [4.5.0](https://github.com/appium/appium-mac2-driver/compare/v4.4.0...v4.5.0) (2026-10-19)
+
+### Features
+
+* add window listing and adjustment extension methods ([#428](https://github.com/appium/appium-mac2-driver/issues/428)) ([42759b6](https://github.com/appium/appium-mac2-driver/commit/42759b603ade35832369b22f790ebe083bff2f3d))
+
+## [4.4.0](https://github.com/appium/appium-mac2-driver/compare/v4.3.6...v4.4.0) (2026-10-11)
+
+### Features
+
+* enforce a single session, a new session replaces the previous one ([#426](https://github.com/appium/appium-mac2-driver/issues/426)) ([fb10372](https://github.com/appium/appium-mac2-driver/commit/fb10372c16d861fb7ff9463b345ba6fcb3f67387))
+
 ## [4.3.6](https://github.com/appium/appium-mac2-driver/compare/v4.3.5...v4.3.6) (2026-10-02)
 
 ### Bug Fixes

package/WebDriverAgentMac/IntegrationTests/AMSessionTests.m

@@ -43,6 +43,20 @@ static NSString *const SETTINGS_BUNDLE_ID = @"com.apple.systempreferences";
   [super tearDown];
 }
 
+- (void)testNewSessionOverridesThePreviousOne
+{
+  NSString *oldId = self.session.identifier;
+  FBSession *newSession = [FBSession initWithApplication:nil];
+  XCTAssertNotEqualObjects(oldId, newSession.identifier);
+  XCTAssertEqual(FBSession.activeSession, newSession);
+  XCTAssertNil([FBSession sessionWithIdentifier:oldId]);
+  // Killing the stale session must not drop the active one
+  [self.session kill];
+  XCTAssertEqual(FBSession.activeSession, newSession);
+  [newSession kill];
+  XCTAssertNil(FBSession.activeSession);
+}
+
 - (void)testSettingsAppCanBeOpenedInScopeOfTheCurrentSession
 {
   [self.session launchApplicationWithBundleId:SETTINGS_BUNDLE_ID

package/WebDriverAgentMac/IntegrationTests/AMWindowTests.m

@@ -0,0 +1,427 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <XCTest/XCTest.h>
+
+#import "AMIntegrationTestCase.h"
+#import "AMScreenUtils.h"
+#import "AMSnapshotUtils.h"
+#import "AMWindowUtils.h"
+#import "AMXCTAccessibility.h"
+#import "FBTestMacros.h"
+
+static const CGFloat AM_GEOMETRY_ACCURACY = 1.0;
+
+/**
+ The windows are inspected and changed through the XCTest accessibility interface, which does not
+ need the Accessibility permission, except for the window geometry. AMWindowAccessibilityApiTests
+ runs the same tests using the Accessibility API only.
+ */
+@interface AMWindowTests : AMIntegrationTestCase
+- (BOOL)usesUnprivilegedRoutes;
+@end
+
+@implementation AMWindowTests
+
+- (BOOL)usesUnprivilegedRoutes
+{
+  return YES;
+}
+
+- (void)setUp
+{
+  [super setUp];
+  AMWindowUtils.usesUnprivilegedRoutes = [self usesUnprivilegedRoutes];
+  [self launchApplication];
+}
+
+- (void)tearDown
+{
+  // Leave the window in a regular state for the other tests
+  NSDictionary *normal = @{@"state": AMWindowStateNormal};
+  [AMWindowUtils adjustMinimizedWindowOfApplication:self.testedApplication withArguments:normal error:nil];
+  XCUIElement *window = [AMWindowUtils mainWindowOfApplication:self.testedApplication];
+  if (nil != window) {
+    [AMWindowUtils adjustWindow:window inApplication:self.testedApplication withArguments:normal error:nil];
+  }
+  AMWindowUtils.usesUnprivilegedRoutes = YES;
+  [super tearDown];
+}
+
+// Changing states needs the XCTest accessibility interface, or the Accessibility permission if it is not used
+- (void)skipUnlessStateRoutesAvailable
+{
+  if ([self usesUnprivilegedRoutes]) {
+    XCTSkipUnless(AMXCTAccessibility.isAvailable, @"The XCTest accessibility interface is not available");
+  } else {
+    [self skipUnlessAccessibilityTrusted];
+  }
+}
+
+#pragma mark - Helpers
+
+- (XCUIElement *)mainWindow
+{
+  XCUIElement *window = [AMWindowUtils mainWindowOfApplication:self.testedApplication];
+  XCTAssertNotNil(window);
+  return window;
+}
+
+- (AMScreenProperties *)mainDisplay
+{
+  for (AMScreenProperties *screen in AMListScreens()) {
+    if (screen.isMain) {
+      return screen;
+    }
+  }
+  XCTFail(@"No main display is reported");
+  return nil;
+}
+
+- (NSDictionary<NSString *, id> *)adjustWindow:(XCUIElement *)window arguments:(NSDictionary<NSString *, id> *)arguments
+{
+  NSError *error = nil;
+  NSDictionary *result = [AMWindowUtils adjustWindow:window inApplication:self.testedApplication withArguments:arguments error:&error];
+  XCTAssertNotNil(result, @"The call has failed: %@", error);
+  return result;
+}
+
+- (NSDictionary<NSString *, id> *)adjustMainWindowWithArguments:(NSDictionary<NSString *, id> *)arguments
+{
+  return [self adjustWindow:[self mainWindow] arguments:arguments];
+}
+
+- (void)assertInvalidArgumentWithMessage:(NSString *)fragment forArguments:(NSDictionary<NSString *, id> *)arguments
+{
+  [self assertInvalidArgumentWithMessage:fragment forArguments:arguments window:[self mainWindow]];
+}
+
+- (void)assertInvalidArgumentWithMessage:(NSString *)fragment
+                            forArguments:(NSDictionary<NSString *, id> *)arguments
+                                  window:(XCUIElement *)window
+{
+  NSError *error = nil;
+  XCTAssertNil([AMWindowUtils adjustWindow:window inApplication:self.testedApplication withArguments:arguments error:&error]);
+  XCTAssertEqualObjects(error.domain, AMWindowErrorDomain);
+  XCTAssertEqual(error.code, AMWindowErrorInvalidArgument);
+  XCTAssertTrue([error.localizedDescription containsString:fragment], @"Unexpected message: %@", error.localizedDescription);
+}
+
+- (CGRect)rectFromInfo:(NSDictionary<NSString *, id> *)info
+{
+  NSDictionary<NSString *, NSNumber *> *rect = info[@"rect"];
+  return CGRectMake(rect[@"x"].doubleValue, rect[@"y"].doubleValue, rect[@"width"].doubleValue, rect[@"height"].doubleValue);
+}
+
+- (void)assertRect:(CGRect)actual equalsRect:(CGRect)expected
+{
+  XCTAssertEqualWithAccuracy(actual.origin.x, expected.origin.x, AM_GEOMETRY_ACCURACY);
+  XCTAssertEqualWithAccuracy(actual.origin.y, expected.origin.y, AM_GEOMETRY_ACCURACY);
+  XCTAssertEqualWithAccuracy(actual.size.width, expected.size.width, AM_GEOMETRY_ACCURACY);
+  XCTAssertEqualWithAccuracy(actual.size.height, expected.size.height, AM_GEOMETRY_ACCURACY);
+}
+
+- (void)assertRect:(CGRect)rect isWithinRect:(CGRect)container
+{
+  XCTAssertTrue(CGRectContainsRect(CGRectInset(container, -AM_GEOMETRY_ACCURACY, -AM_GEOMETRY_ACCURACY), rect),
+                @"%@ is not within %@", NSStringFromRect(rect), NSStringFromRect(container));
+}
+
+#pragma mark - Displays
+
+- (void)testDisplaysReportTheirBounds
+{
+  AMScreenProperties *display = [self mainDisplay];
+  XCTAssertTrue(display.bounds.size.width > 0 && display.bounds.size.height > 0);
+  // The main display is the origin of the global coordinate space
+  XCTAssertEqualWithAccuracy(display.bounds.origin.x, 0, AM_GEOMETRY_ACCURACY);
+  XCTAssertEqualWithAccuracy(display.bounds.origin.y, 0, AM_GEOMETRY_ACCURACY);
+  // The menu bar and the Dock are excluded
+  [self assertRect:display.visibleBounds isWithinRect:display.bounds];
+}
+
+#pragma mark - Listing
+
+- (void)testWindowsAreListed
+{
+  NSArray<XCUIElement *> *windows = [AMWindowUtils windowsOfApplication:self.testedApplication];
+  XCTAssertTrue(windows.count > 0);
+  NSDictionary *info = [AMWindowUtils infoForWindow:windows.firstObject];
+  XCTAssertNotNil(info[@"title"]);
+  CGRect rect = [self rectFromInfo:info];
+  XCTAssertTrue(rect.size.width > 0 && rect.size.height > 0);
+  XCTAssertEqualObjects(info[@"displayId"], @([self mainDisplay].identifier));
+}
+
+- (void)testWindowTraitsAreListed
+{
+  [self skipUnlessStateRoutesAvailable];
+
+  NSDictionary *info = [AMWindowUtils infoForWindow:[self mainWindow]];
+  for (NSString *trait in @[@"isMain", @"isFocused", @"isMinimized", @"isFullscreen"]) {
+    XCTAssertTrue([info[trait] isKindOfClass:NSNumber.class], @"'%@' must be a boolean: %@", trait, info);
+  }
+  XCTAssertTrue([info[@"isMain"] boolValue]);
+  XCTAssertFalse([info[@"isMinimized"] boolValue]);
+  XCTAssertFalse([info[@"isFullscreen"] boolValue]);
+  // These can only be asked through the Accessibility API
+  if (AMSnapshotUtils.isAccessibilityTrusted) {
+    XCTAssertTrue([info[@"isMovable"] boolValue]);
+    XCTAssertTrue([info[@"isResizable"] boolValue]);
+  } else {
+    XCTAssertEqualObjects(info[@"isMovable"], NSNull.null);
+    XCTAssertEqualObjects(info[@"isResizable"], NSNull.null);
+  }
+}
+
+#pragma mark - Argument validation
+
+- (void)testAdjustingRequiresAtLeastOneArgument
+{
+  [self assertInvalidArgumentWithMessage:@"At least one of" forArguments:@{}];
+  [self assertInvalidArgumentWithMessage:@"At least one of" forArguments:@{@"windowId": @"foo"}];
+}
+
+- (void)testAdjustingRejectsUnknownState
+{
+  [self assertInvalidArgumentWithMessage:@"'state' must be one of" forArguments:@{@"state": @"foo"}];
+}
+
+- (void)testAdjustingRejectsInvalidGeometry
+{
+  [self assertInvalidArgumentWithMessage:@"'width'" forArguments:@{@"width": @0}];
+  [self assertInvalidArgumentWithMessage:@"'height'" forArguments:@{@"height": @(-10)}];
+  [self assertInvalidArgumentWithMessage:@"'x'" forArguments:@{@"x": @"foo"}];
+}
+
+- (void)testAdjustingRejectsStateCombinedWithGeometry
+{
+  [self assertInvalidArgumentWithMessage:@"cannot be combined"
+                            forArguments:@{@"state": AMWindowStateMinimized, @"x": @10}];
+  [self assertInvalidArgumentWithMessage:@"cannot be combined"
+                            forArguments:@{@"state": AMWindowStateFullscreen, @"displayId": @([self mainDisplay].identifier)}];
+  [self assertInvalidArgumentWithMessage:@"cannot be combined"
+                            forArguments:@{@"state": AMWindowStateMaximized, @"width": @500}];
+}
+
+- (void)testAdjustingRejectsUnknownDisplay
+{
+  [self assertInvalidArgumentWithMessage:@"is unknown" forArguments:@{@"displayId": @999999}];
+}
+
+- (void)testAdjustingRejectsMalformedDisplayId
+{
+  [self assertInvalidArgumentWithMessage:@"'displayId' must be a number" forArguments:@{@"displayId": @{}}];
+  [self assertInvalidArgumentWithMessage:@"'displayId' must be a number" forArguments:@{@"displayId": @"foo"}];
+}
+
+- (void)testAdjustingRejectsNonWindowElements
+{
+  XCUIElement *button = self.testedApplication.buttons.firstMatch;
+  XCTAssertTrue([button waitForExistenceWithTimeout:5.0]);
+  [self assertInvalidArgumentWithMessage:@"is not a window" forArguments:@{@"x": @10} window:button];
+}
+
+#pragma mark - Adjusting (requires the Accessibility permission)
+
+- (void)testWindowCanBeResizedAndMoved
+{
+  [self skipUnlessAccessibilityTrusted];
+
+  XCUIElement *window = [self mainWindow];
+  CGRect original = [self rectFromInfo:[AMWindowUtils infoForWindow:window]];
+  CGRect expected = CGRectMake(original.origin.x + 30, original.origin.y + 30,
+                               original.size.width + 20, original.size.height + 20);
+  NSDictionary *result = [self adjustWindow:window arguments:@{
+    @"x": @(expected.origin.x),
+    @"y": @(expected.origin.y),
+    @"width": @(expected.size.width),
+    @"height": @(expected.size.height),
+  }];
+  [self assertRect:[self rectFromInfo:result] equalsRect:expected];
+  // The change is observable from the outside
+  [self assertRect:[self rectFromInfo:[AMWindowUtils infoForWindow:window]] equalsRect:expected];
+  [self assertRect:window.frame equalsRect:expected];
+}
+
+- (void)testOmittedGeometryIsKept
+{
+  [self skipUnlessAccessibilityTrusted];
+
+  XCUIElement *window = [self mainWindow];
+  CGRect original = [self rectFromInfo:[AMWindowUtils infoForWindow:window]];
+  NSDictionary *result = [self adjustWindow:window arguments:@{@"width": @(original.size.width + 20)}];
+  [self assertRect:[self rectFromInfo:result]
+        equalsRect:CGRectMake(original.origin.x, original.origin.y, original.size.width + 20, original.size.height)];
+}
+
+- (void)testWindowCanBeMovedToDisplay
+{
+  [self skipUnlessAccessibilityTrusted];
+
+  AMScreenProperties *display = [self mainDisplay];
+  NSDictionary *result = [self adjustMainWindowWithArguments:@{
+    @"displayId": @(display.identifier),
+    @"x": @80,
+    @"y": @120,
+  }];
+  CGRect rect = [self rectFromInfo:result];
+  // Coordinates are relative to the display
+  XCTAssertEqualWithAccuracy(rect.origin.x, display.bounds.origin.x + 80, AM_GEOMETRY_ACCURACY);
+  XCTAssertEqualWithAccuracy(rect.origin.y, display.bounds.origin.y + 120, AM_GEOMETRY_ACCURACY);
+  XCTAssertEqualObjects(result[@"displayId"], @(display.identifier));
+}
+
+- (void)testWindowIsKeptWithinDisplay
+{
+  [self skipUnlessAccessibilityTrusted];
+
+  AMScreenProperties *display = [self mainDisplay];
+  NSDictionary *result = [self adjustMainWindowWithArguments:@{
+    @"displayId": @(display.identifier),
+    @"x": @(display.bounds.size.width * 10),
+    @"y": @(display.bounds.size.height * 10),
+  }];
+  [self assertRect:[self rectFromInfo:result] isWithinRect:display.bounds];
+}
+
+- (void)testWindowCanBeMaximized
+{
+  [self skipUnlessAccessibilityTrusted];
+
+  AMScreenProperties *display = [self mainDisplay];
+  CGRect original = [self rectFromInfo:[AMWindowUtils infoForWindow:[self mainWindow]]];
+  CGRect rect = [self rectFromInfo:[self adjustMainWindowWithArguments:@{@"state": AMWindowStateMaximized}]];
+  XCTAssertTrue(rect.size.width * rect.size.height >= original.size.width * original.size.height,
+                @"%@ must not be smaller than %@", NSStringFromRect(rect), NSStringFromRect(original));
+  // Fills the display, except the menu bar and the Dock
+  [self assertRect:rect isWithinRect:display.bounds];
+  XCTAssertTrue(rect.size.width >= display.visibleBounds.size.width - AM_GEOMETRY_ACCURACY);
+
+  // Maximizing is idempotent
+  NSDictionary *repeated = [self adjustMainWindowWithArguments:@{@"state": AMWindowStateMaximized}];
+  [self assertRect:[self rectFromInfo:repeated] equalsRect:rect];
+}
+
+- (void)testWindowCanBeMinimizedAndRestored
+{
+  [self skipUnlessStateRoutesAvailable];
+
+  XCUIApplication *application = self.testedApplication;
+  CGRect original = [self rectFromInfo:[AMWindowUtils infoForWindow:[self mainWindow]]];
+  NSDictionary *minimized = [self adjustMainWindowWithArguments:@{@"state": AMWindowStateMinimized}];
+  XCTAssertEqualObjects(minimized[@"isMinimized"], @YES);
+  FBAssertWaitTillBecomesTrue(1 == [AMWindowUtils minimizedWindowsCountOfApplication:application]);
+
+  // Minimized windows are not a part of the element hierarchy
+  NSError *error = nil;
+  NSDictionary *restored = [AMWindowUtils adjustMinimizedWindowOfApplication:application
+                                                               withArguments:@{@"state": AMWindowStateNormal}
+                                                                       error:&error];
+  XCTAssertNotNil(restored, @"The call has failed: %@", error);
+  XCTAssertEqualObjects(restored[@"isMinimized"], @NO);
+  [self assertRect:[self rectFromInfo:restored] equalsRect:original];
+  FBAssertWaitTillBecomesTrue(0 == [AMWindowUtils minimizedWindowsCountOfApplication:application]);
+  FBAssertWaitTillBecomesTrue(nil != [AMWindowUtils mainWindowOfApplication:application]);
+}
+
+- (void)testMinimizedWindowIsRestoredByGeometryChange
+{
+  [self skipUnlessAccessibilityTrusted];
+
+  XCUIApplication *application = self.testedApplication;
+  CGRect original = [self rectFromInfo:[AMWindowUtils infoForWindow:[self mainWindow]]];
+  [self adjustMainWindowWithArguments:@{@"state": AMWindowStateMinimized}];
+  FBAssertWaitTillBecomesTrue(1 == [AMWindowUtils minimizedWindowsCountOfApplication:application]);
+
+  NSError *error = nil;
+  NSDictionary *result = [AMWindowUtils adjustMinimizedWindowOfApplication:application
+                                                             withArguments:@{@"width": @(original.size.width + 10)}
+                                                                     error:&error];
+  XCTAssertNotNil(result, @"The call has failed: %@", error);
+  XCTAssertEqualObjects(result[@"isMinimized"], @NO);
+  XCTAssertEqualWithAccuracy([self rectFromInfo:result].size.width, original.size.width + 10, AM_GEOMETRY_ACCURACY);
+}
+
+- (void)testRestoringRequiresMinimizedWindow
+{
+  [self skipUnlessStateRoutesAvailable];
+
+  NSError *error = nil;
+  XCTAssertNil([AMWindowUtils adjustMinimizedWindowOfApplication:self.testedApplication
+                                                   withArguments:@{@"state": AMWindowStateNormal}
+                                                           error:&error]);
+  XCTAssertEqual(error.code, AMWindowErrorNotFound);
+}
+
+- (void)testGeometryRequiresAccessibilityPermission
+{
+  XCTSkipIf(AMSnapshotUtils.isAccessibilityTrusted, @"The process is trusted for the Accessibility API");
+
+  NSError *error = nil;
+  XCTAssertNil([AMWindowUtils adjustWindow:[self mainWindow]
+                             inApplication:self.testedApplication
+                             withArguments:@{@"width": @600}
+                                     error:&error]);
+  XCTAssertEqual(error.code, AMWindowErrorFailure);
+  XCTAssertTrue([error.localizedDescription containsString:@"Accessibility"], @"%@", error.localizedDescription);
+}
+
+- (void)testWindowCanEnterAndLeaveFullscreen
+{
+  [self skipUnlessStateRoutesAvailable];
+
+  XCUIElement *window = [self mainWindow];
+  NSDictionary *fullscreen = [self adjustWindow:window arguments:@{@"state": AMWindowStateFullscreen}];
+  XCTAssertEqualObjects(fullscreen[@"isFullscreen"], @YES);
+
+  NSDictionary *restored = [self adjustWindow:window arguments:@{@"state": AMWindowStateNormal}];
+  XCTAssertEqualObjects(restored[@"isFullscreen"], @NO);
+}
+
+- (void)testFullscreenWindowCanBeMinimized
+{
+  [self skipUnlessStateRoutesAvailable];
+
+  XCUIApplication *application = self.testedApplication;
+  XCUIElement *window = [self mainWindow];
+  NSDictionary *fullscreen = [self adjustWindow:window arguments:@{@"state": AMWindowStateFullscreen}];
+  XCTAssertEqualObjects(fullscreen[@"isFullscreen"], @YES);
+
+  NSDictionary *minimized = [self adjustWindow:window arguments:@{@"state": AMWindowStateMinimized}];
+  XCTAssertEqualObjects(minimized[@"isMinimized"], @YES);
+  XCTAssertEqualObjects(minimized[@"isFullscreen"], @NO);
+
+  NSError *error = nil;
+  XCTAssertNotNil([AMWindowUtils adjustMinimizedWindowOfApplication:application
+                                                      withArguments:@{@"state": AMWindowStateNormal}
+                                                              error:&error], @"The call has failed: %@", error);
+  FBAssertWaitTillBecomesTrue(nil != [AMWindowUtils mainWindowOfApplication:application]);
+}
+
+@end
+
+@interface AMWindowAccessibilityApiTests : AMWindowTests
+@end
+
+@implementation AMWindowAccessibilityApiTests
+
+- (BOOL)usesUnprivilegedRoutes
+{
+  return NO;
+}
+
+@end

package/WebDriverAgentMac/WebDriverAgentLib/Commands/AMWindowCommands.m

@@ -9,6 +9,8 @@
 
 #import "AMWindowCommands.h"
 
+#import "AMWindowUtils.h"
+#import "FBElementCache.h"
 #import "FBRoute.h"
 #import "FBRouteRequest.h"
 #import "FBSession.h"
@@ -23,6 +25,8 @@
     [[FBRoute POST:@"/window/maximize"] respondWithTarget:self action:@selector(handleMaximizeWindow:)],
     [[FBRoute POST:@"/window/fullscreen"] respondWithTarget:self action:@selector(handleFullscreenWindow:)],
     [[FBRoute POST:@"/window/minimize"] respondWithTarget:self action:@selector(handleMinimizeWindow:)],
+    [[FBRoute GET:@"/wda/windows"] respondWithTarget:self action:@selector(handleListWindows:)],
+    [[FBRoute POST:@"/wda/window/adjust"] respondWithTarget:self action:@selector(handleAdjustWindow:)],
   ];
 }
 
@@ -49,6 +53,65 @@
                            errorMessage:[NSString stringWithFormat:@"%@ window cannot be minimized because the corresponding button is not available", request.session.currentApplication.description]];
 }
 
++ (id<FBResponsePayload>)handleListWindows:(FBRouteRequest *)request
+{
+  FBElementCache *cache = request.session.elementCache;
+  NSMutableArray *result = [NSMutableArray array];
+  for (XCUIElement *window in [AMWindowUtils windowsOfApplication:request.session.currentApplication]) {
+    NSDictionary *info = [AMWindowUtils infoForWindow:window];
+    if (nil != info) {
+      [result addObject:[self info:info withWindowId:[cache storeElement:window]]];
+    }
+  }
+  return FBResponseWithObject(result.copy);
+}
+
++ (id<FBResponsePayload>)handleAdjustWindow:(FBRouteRequest *)request
+{
+  FBElementCache *cache = request.session.elementCache;
+  XCUIApplication *application = request.session.currentApplication;
+  id rawWindowId = request.arguments[@"windowId"];
+  if (nil != rawWindowId && ![rawWindowId isKindOfClass:NSNull.class] && ![rawWindowId isKindOfClass:NSString.class]) {
+    return FBResponseWithStatus([FBCommandStatus invalidArgumentErrorWithMessage:
+                                 [NSString stringWithFormat:@"'windowId' must be a string, got '%@'", rawWindowId]
+                                                                        traceback:nil]);
+  }
+  NSString *windowId = [rawWindowId isKindOfClass:NSString.class] ? rawWindowId : nil;
+  XCUIElement *window = nil != windowId
+    ? [cache elementForUUID:windowId]
+    : [AMWindowUtils mainWindowOfApplication:application];
+  NSError *error = nil;
+  NSDictionary *info = nil;
+  if (nil != window) {
+    info = [AMWindowUtils adjustWindow:window inApplication:application withArguments:request.arguments error:&error];
+  } else if (nil == windowId) {
+    // There are no visible windows, so a minimized one could be restored
+    info = [AMWindowUtils adjustMinimizedWindowOfApplication:application withArguments:request.arguments error:&error];
+  }
+  NSString *resultWindowId = nil != info && nil != window ? (windowId ?: [cache storeElement:window]) : nil;
+  if (nil == info) {
+    NSString *message = error.localizedDescription;
+    switch (error.code) {
+      case AMWindowErrorInvalidArgument:
+        return FBResponseWithStatus([FBCommandStatus invalidArgumentErrorWithMessage:message traceback:nil]);
+      case AMWindowErrorNotFound:
+        return FBResponseWithStatus([FBCommandStatus noSuchWindowErrorWithMessage:message traceback:nil]);
+      default:
+        return FBResponseWithStatus([FBCommandStatus unknownErrorWithMessage:message traceback:nil]);
+    }
+  }
+  return FBResponseWithObject([self info:info withWindowId:resultWindowId]);
+}
+
+#pragma mark - Helpers
+
++ (NSDictionary<NSString *, id> *)info:(NSDictionary<NSString *, id> *)info withWindowId:(nullable NSString *)windowId
+{
+  NSMutableDictionary *result = [info mutableCopy];
+  result[@"windowId"] = windowId ?: NSNull.null;
+  return result.copy;
+}
+
 + (id<FBResponsePayload>)performClickWithButtonId:(NSString *)buttonId
                                           request:(FBRouteRequest *)request
                                      errorMessage:(NSString *)errorMessage

package/WebDriverAgentMac/WebDriverAgentLib/Commands/FBDebugCommands.m

@@ -9,6 +9,7 @@
 
 #import "FBDebugCommands.h"
 
+#import "AMGeometryUtils.h"
 #import "AMScreenUtils.h"
 #import "FBRouteRequest.h"
 #import "FBSession.h"
@@ -65,6 +66,7 @@ static NSString *const SOURCE_FORMAT_DESCRIPTION = @"description";
     result[[NSString stringWithFormat:@"%lld", screenInfo.identifier]] = @{
       @"id": @(screenInfo.identifier),
       @"isMain": @(screenInfo.isMain),
+      @"rect": AMCGRectToDict(screenInfo.bounds),
     };
   }
   return FBResponseWithObject(result.copy);

package/WebDriverAgentMac/WebDriverAgentLib/Commands/FBSessionCommands.m

@@ -99,9 +99,15 @@ const static NSString *CAPABILITIES_KEY = @"capabilities";
   NSString *appPath = requirements[AM_APP_PATH_CAPABILITY];
   NSString *deepLink = requirements[AM_INITIAL_DEEPLINK_URL_CAPABILITY];
   BOOL noReset = [requirements[AM_NO_RESET_CAPABILITY] boolValue];
-  FBSession *session;
+
+  // XCTest is single-threaded, so there can only be one session. A new one always
+  // takes over, and the previous one must be gone before any app gets touched.
+  [FBSession.activeSession kill];
+
+  XCUIApplication *app = nil;
+  BOOL didLaunchApp = NO;
   if (nil == bundleID && nil == appPath && nil == deepLink) {
-    session = [FBSession initWithApplication:nil];
+    // no app to manage
   } else if (nil != deepLink) {
     NSURL *url = [NSURL URLWithString:deepLink];
     NSError *error;
@@ -113,13 +119,12 @@ const static NSString *CAPABILITIES_KEY = @"capabilities";
                                                                 traceback:nil]);
     }
     if (nil != bundleID) {
-      session = [FBSession initWithApplication:[[XCUIApplication alloc] initWithBundleIdentifier:bundleID]];
+      app = [[XCUIApplication alloc] initWithBundleIdentifier:bundleID];
     }
   } else {
-    XCUIApplication *app = nil != appPath 
+    app = nil != appPath
       ? [[XCUIApplication alloc] initWithURL:[NSURL fileURLWithPath:appPath]]
       : [[XCUIApplication alloc] initWithBundleIdentifier:bundleID];
-    session = [FBSession initWithApplication:app];
     if (noReset && app.state > XCUIApplicationStateNotRunning) {
       [app activate];
     } else {
@@ -140,6 +145,7 @@ const static NSString *CAPABILITIES_KEY = @"capabilities";
       }
       app.launchEnvironment = [launchEnv copy];
       [app launch];
+      didLaunchApp = YES;
       if (app.state <= XCUIApplicationStateNotRunning) {
         NSString *message = [NSString stringWithFormat:@"Failed to launch '%@' application", appPath ?: bundleID];
         return FBResponseWithStatus([FBCommandStatus sessionNotCreatedError:message
@@ -149,6 +155,10 @@ const static NSString *CAPABILITIES_KEY = @"capabilities";
     if (nil != bundleID && nil != appPath) {
       NSString *realBundleID = app.am_bundleID;
       if (![realBundleID isEqualToString:bundleID]) {
+        // no session owns the app, so don't leave it behind
+        if (didLaunchApp) {
+          [app terminate];
+        }
         NSString *message = [NSString stringWithFormat:@"The bundle identifier %@ of the '%@' does not match to the one provided in capabilities: %@", 
                              realBundleID, appPath, bundleID];
         return FBResponseWithStatus([FBCommandStatus sessionNotCreatedError:message
@@ -156,6 +166,8 @@ const static NSString *CAPABILITIES_KEY = @"capabilities";
       }
     }
   }
+  // The session is only registered once startup has fully succeeded
+  FBSession *session = [FBSession initWithApplication:app];
   if (nil != requirements[AM_SKIP_APP_KILL_CAPABILITY]) {
     session.skipAppTermination = [requirements[AM_SKIP_APP_KILL_CAPABILITY] boolValue];
   } else if (nil == bundleID) {

package/WebDriverAgentMac/WebDriverAgentLib/Routing/FBCommandStatus.h

@@ -37,6 +37,9 @@ NS_ASSUME_NONNULL_BEGIN
 + (instancetype)noSuchElementErrorWithMessage:(nullable NSString *)message
                                     traceback:(nullable NSString *)traceback;
 
++ (instancetype)noSuchWindowErrorWithMessage:(nullable NSString *)message
+                                   traceback:(nullable NSString *)traceback;
+
 + (instancetype)invalidElementStateErrorWithMessage:(nullable NSString *)message
                                           traceback:(nullable NSString *)traceback;
 

package/WebDriverAgentMac/WebDriverAgentLib/Routing/FBCommandStatus.m

@@ -21,6 +21,10 @@ static NSString *const FB_NO_SUCH_ELEMENT_ERROR = @"no such element";
 static const HTTPStatusCode FB_NO_SUCH_ELEMENT_ERROR_CODE = kHTTPStatusCodeNotFound;
 static NSString *const FB_NO_SUCH_ELEMENT_MSG = @"An element could not be located on the page using the given search parameters";
 
+static NSString *const FB_NO_SUCH_WINDOW_ERROR = @"no such window";
+static const HTTPStatusCode FB_NO_SUCH_WINDOW_ERROR_CODE = kHTTPStatusCodeNotFound;
+static NSString *const FB_NO_SUCH_WINDOW_MSG = @"A window could not be found. It might have been closed";
+
 static NSString *const FB_INVALID_ELEMENT_STATE_ERROR = @"invalid element state";
 static const HTTPStatusCode FB_INVALID_ELEMENT_STATE_ERROR_CODE = kHTTPStatusCodeBadRequest;
 static NSString *const FB_INVALID_ELEMENT_STATE_MSG = @"An element command could not be completed because the element is in an invalid state (e.g. attempting to click a disabled element)";
@@ -155,6 +159,15 @@ static NSString *const FB_NO_SUCH_DRIVER_MSG = @"A session is either terminated
                                       traceback:traceback];
 }
 
++ (instancetype)noSuchWindowErrorWithMessage:(NSString *)message
+                                   traceback:(NSString *)traceback
+{
+  return [[FBCommandStatus alloc] initWithError:FB_NO_SUCH_WINDOW_ERROR
+                                     statusCode:FB_NO_SUCH_WINDOW_ERROR_CODE
+                                        message:message ?: FB_NO_SUCH_WINDOW_MSG
+                                      traceback:traceback];
+}
+
 + (instancetype)invalidElementStateErrorWithMessage:(NSString *)message
                                           traceback:(NSString *)traceback
 {