appium-mac2-driver 4.3.6 → 4.5.0

package/WebDriverAgentMac/WebDriverAgentLib/Routing/FBSession.m

@@ -72,6 +72,11 @@ static FBSession *_activeSession = nil;
     [self.testedApplication terminate];
   }
   self.testedApplication = nil;
+  [self.elementCache reset];
+  // The recording belongs to the active session, so a stale one must not touch it
+  if (_activeSession != self) {
+    return;
+  }
   FBScreenRecordingContainer *screenRecordingContainer = FBScreenRecordingContainer.sharedInstance;
   NSUUID *videoRecordingId = screenRecordingContainer.screenRecordingPromise.identifier;
   if (nil != videoRecordingId) {
@@ -83,7 +88,6 @@ static FBSession *_activeSession = nil;
   if (nil != screenRecordingContainer.screenRecordingPromise) {
     [screenRecordingContainer reset];
   }
-  [self.elementCache reset];
   _activeSession = nil;
 }
 

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/AMScreenUtils.h

@@ -24,6 +24,10 @@ NS_ASSUME_NONNULL_BEGIN
 @property (readonly, nonatomic) BOOL isMain;
 /** The integer identifier of a screen */
 @property (readonly, nonatomic) long long identifier;
+/** The display bounds in the global coordinate space with the top-left origin (same as XCUIElement frames) */
+@property (readonly, nonatomic) CGRect bounds;
+/** Same as bounds, but without the menu bar and the Dock */
+@property (readonly, nonatomic) CGRect visibleBounds;
 
 @end
 

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/AMScreenUtils.m

@@ -18,6 +18,29 @@
 
 @implementation AMScreenProperties
 
+- (CGRect)bounds
+{
+  return CGDisplayBounds((CGDirectDisplayID)self.identifier);
+}
+
+- (CGRect)visibleBounds
+{
+  CGRect bounds = self.bounds;
+  for (NSScreen *screen in NSScreen.screens) {
+    if ([screen.deviceDescription[@"NSScreenNumber"] longLongValue] != self.identifier) {
+      continue;
+    }
+    // NSScreen uses the bottom-left origin of the primary screen, which is the first one
+    CGFloat primaryHeight = NSScreen.screens.firstObject.frame.size.height;
+    CGRect visible = screen.visibleFrame;
+    return CGRectMake(visible.origin.x,
+                      primaryHeight - CGRectGetMaxY(visible),
+                      visible.size.width,
+                      visible.size.height);
+  }
+  return bounds;
+}
+
 - (instancetype)initWithIdentifier:(long long)identifier
                             isMain:(BOOL)isMain
 {

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/AMSnapshotUtils.h

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+#import <ApplicationServices/ApplicationServices.h>
 #import <XCTest/XCTest.h>
 
 NS_ASSUME_NONNULL_BEGIN
@@ -79,6 +80,23 @@ NS_ASSUME_NONNULL_BEGIN
  */
 + (nullable NSString *)domIdentifierWithSnapshot:(nullable id)snapshot;
 
+/**
+ Creates an AX element for the given snapshot. The caller owns the result and must CFRelease it.
+
+ @param snapshot snapshot instance to create the AX element for
+ @return The AX element or NULL if this process lacks Accessibility permission or the element is unavailable
+ */
++ (nullable AXUIElementRef)createAXElementWithSnapshot:(nullable id)snapshot CF_RETURNS_RETAINED;
+
+/**
+ Creates an AX element for the XCTest accessibility element (XCAccessibilityElement).
+ The caller owns the result and must CFRelease it.
+
+ @param element XCTest accessibility element
+ @return The AX element or NULL if this process lacks Accessibility permission or the element is unavailable
+ */
++ (nullable AXUIElementRef)createAXElementWithAccessibilityElement:(nullable id)element CF_RETURNS_RETAINED;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/AMSnapshotUtils.m

@@ -114,43 +114,58 @@ static BOOL AMIsAccessibilityTrusted(void)
     : matchingElements.copy;
 }
 
-+ (nullable NSString *)domIdentifierWithSnapshot:(nullable id)snapshot
++ (nullable AXUIElementRef)createAXElementWithSnapshot:(nullable id)snapshot
 {
-  if (nil == snapshot || !AMIsAccessibilityTrusted()) {
-    return nil;
+  if (nil == snapshot) {
+    return NULL;
+  }
+  @try {
+    return [self createAXElementWithAccessibilityElement:[snapshot valueForKey:@"_accessibilityElement"]];
+  } @catch (NSException *e) {
+    // Only the private _accessibilityElement key path may throw here
+    [FBLogger logFmt:@"Cannot create an AX element from a snapshot. Original error: %@", e.reason];
+    return NULL;
+  }
+}
+
++ (nullable AXUIElementRef)createAXElementWithAccessibilityElement:(nullable id)element
+{
+  if (nil == element || !AMIsAccessibilityTrusted()) {
+    return NULL;
   }
   AMCreateWithRemoteTokenFn createRef = AMRemoteTokenFn();
   if (NULL == createRef) {
-    return nil;
+    return NULL;
   }
-
   @try {
-    NSData *token = [[snapshot valueForKey:@"_accessibilityElement"] valueForKey:@"_token"];
-    if (![token isKindOfClass:NSData.class]) {
-      return nil;
-    }
-    AXUIElementRef ref = createRef((__bridge CFDataRef)token);
-    if (NULL == ref) {
-      return nil;
-    }
-    CFTypeRef value = NULL;
-    AXError err = AXUIElementCopyAttributeValue(ref,
-                                                (__bridge CFStringRef)AM_DOM_IDENTIFIER_ATTRIBUTE,
-                                                &value);
-    CFRelease(ref);
-    if (kAXErrorSuccess != err || NULL == value) {
-      return nil;
-    }
-    NSString *result = [(__bridge id)value isKindOfClass:NSString.class]
-      ? [(__bridge NSString *)value copy]
-      : nil;
-    CFRelease(value);
-    return result.length > 0 ? result : nil;
+    NSData *token = [element valueForKey:@"_token"];
+    return [token isKindOfClass:NSData.class] ? createRef((__bridge CFDataRef)token) : NULL;
   } @catch (NSException *e) {
-    // Only the private _accessibilityElement._token key path may throw here
-    [FBLogger logFmt:@"Cannot retrieve the DOM identifier of a snapshot. Original error: %@", e.reason];
+    // Only the private _token key path may throw here
+    [FBLogger logFmt:@"Cannot create an AX element from an accessibility element. Original error: %@", e.reason];
+    return NULL;
+  }
+}
+
++ (nullable NSString *)domIdentifierWithSnapshot:(nullable id)snapshot
+{
+  AXUIElementRef ref = [self createAXElementWithSnapshot:snapshot];
+  if (NULL == ref) {
+    return nil;
+  }
+  CFTypeRef value = NULL;
+  AXError err = AXUIElementCopyAttributeValue(ref,
+                                              (__bridge CFStringRef)AM_DOM_IDENTIFIER_ATTRIBUTE,
+                                              &value);
+  CFRelease(ref);
+  if (kAXErrorSuccess != err || NULL == value) {
     return nil;
   }
+  NSString *result = [(__bridge id)value isKindOfClass:NSString.class]
+    ? [(__bridge NSString *)value copy]
+    : nil;
+  CFRelease(value);
+  return result.length > 0 ? result : nil;
 }
 
 @end

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/AMWindowUtils.h

@@ -0,0 +1,111 @@
+/*
+ * 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>
+
+NS_ASSUME_NONNULL_BEGIN
+
+extern NSString *const AMWindowErrorDomain;
+
+typedef NS_ENUM(NSInteger, AMWindowErrorCode) {
+  /** One of the arguments is invalid */
+  AMWindowErrorInvalidArgument = 1,
+  /** The window could not be changed, for example because the Accessibility permission is missing */
+  AMWindowErrorFailure,
+  /** The window does not exist anymore or there is no such window */
+  AMWindowErrorNotFound,
+};
+
+extern NSString *const AMWindowStateNormal;
+extern NSString *const AMWindowStateMinimized;
+extern NSString *const AMWindowStateMaximized;
+extern NSString *const AMWindowStateFullscreen;
+
+/**
+ Inspects and changes application windows. Does not depend on the HTTP layer or sessions.
+
+ Whenever possible, windows are inspected and changed through the accessibility interface of XCTest,
+ which does not need the Accessibility permission: the window attributes, the minimized windows,
+ minimizing, entering and leaving the fullscreen mode and restoring minimized windows.
+ If this is not possible, the Accessibility API is used, which requires the process to be trusted.
+ Moving and resizing windows always needs the Accessibility permission.
+ */
+@interface AMWindowUtils : NSObject
+
+/**
+ Whether the XCTest accessibility interface is used (YES by default). If it is turned off, only
+ the Accessibility API is used. Intended for tests.
+ */
+@property (class, nonatomic) BOOL usesUnprivilegedRoutes;
+
+/**
+ @returns Windows of the given application
+ */
++ (NSArray<XCUIElement *> *)windowsOfApplication:(XCUIApplication *)application;
+
+/**
+ @returns The window flagged as main, then the focused one, then the first one. Nil if there are no windows
+ */
++ (nullable XCUIElement *)mainWindowOfApplication:(XCUIApplication *)application;
+
+/**
+ Describes the window. The result contains:
+ title, rect (global coordinates), displayId (the display with the biggest part of the window)
+ and the isMain, isFocused, isMinimized, isFullscreen, isMovable, isResizable traits.
+ isMovable and isResizable are NSNull if the Accessibility permission is not granted,
+ and all the traits are NSNull if the window cannot be read at all.
+
+ @returns The window info or nil if the element does not exist anymore
+ */
++ (nullable NSDictionary<NSString *, id> *)infoForWindow:(XCUIElement *)window;
+
+/**
+ Changes the state and/or geometry of the window.
+
+ @param window the window element
+ @param application the application that owns the window
+ @param arguments any of: state (normal, minimized, maximized, fullscreen), x, y, width, height
+ and displayId. Coordinates are global, or relative to the display if displayId is set.
+ minimized and fullscreen states cannot be combined with the geometry, and maximized can only be
+ combined with displayId. The geometry (including maximized) needs the Accessibility permission.
+ @param error AMWindowErrorInvalidArgument, AMWindowErrorFailure or AMWindowErrorNotFound
+ (the element does not exist anymore, for example because the window has been minimized)
+ @returns The updated window info in the infoForWindow: format or nil in case of failure
+ */
++ (nullable NSDictionary<NSString *, id> *)adjustWindow:(XCUIElement *)window
+                                          inApplication:(XCUIApplication *)application
+                                          withArguments:(NSDictionary<NSString *, id> *)arguments
+                                                  error:(NSError **)error;
+
+/**
+ Same as adjustWindow:inApplication:withArguments:error: for the first minimized window of the application.
+ Minimized windows cannot be addressed by elements, because they are not a part of the element hierarchy.
+
+ @returns The updated window info or nil in case of failure. AMWindowErrorNotFound is returned
+ if there are no minimized windows
+ */
++ (nullable NSDictionary<NSString *, id> *)adjustMinimizedWindowOfApplication:(XCUIApplication *)application
+                                                                withArguments:(NSDictionary<NSString *, id> *)arguments
+                                                                        error:(NSError **)error;
+
+/**
+ @returns The number of minimized windows of the application
+ */
++ (NSUInteger)minimizedWindowsCountOfApplication:(XCUIApplication *)application;
+
+@end
+
+NS_ASSUME_NONNULL_END