appium-mac2-driver 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [3.2.0](https://github.com/appium/appium-mac2-driver/compare/v3.1.0...v3.2.0) (2025-11-11)
+
+
+### Features
+
+* Add a setting that allows to fetch full element text ([#347](https://github.com/appium/appium-mac2-driver/issues/347)) ([a8b9e7e](https://github.com/appium/appium-mac2-driver/commit/a8b9e7ee1c0b576c04eaafb8af0d8649330ffc3b))
+
 ## [3.1.0](https://github.com/appium/appium-mac2-driver/compare/v3.0.1...v3.1.0) (2025-10-01)
 
 

package/README.md

@@ -849,6 +849,7 @@ Name | Type | Description
 --- | --- | ---
 boundElementsByIndex | boolean | Whether to use elements binding by index (`true`) or by accessibility identifier (the default setting, `false`). It makes sense to switch the binding strategy to workaround stale element reference errors containing `Identity Binding` text in their descriptions. See the corresponding [Stack Overflow discussion](https://stackoverflow.com/questions/49307513/meaning-of-allelementsboundbyaccessibilityelement) to know more details on the difference between these two binding strategies.
 useDefaultUiInterruptionsHandling | boolean | Whether to use the default XCTest UI interruptions handling (`true`, the default setting) or to disable it for the [Application Under Test](#application-under-test-concept) (`false`). It makes sense to disable the default handler if it is necessary to validate the interrupting element's presence in your test or do some other actions on it rather than just closing the view implicitly. Check [this WWDC presentation](https://developer.apple.com/videos/play/wwdc2020/10220/) from Apple to get more details on the UI interruptions handling.
+fetchFullText | boolean | Whether to use custom snapshotting mechanism to fetch full element's text payload instead of the first 512 chars. By default, this setting is set to false, which makes the driver to use the standard XCTest's snapshotting mechanism. It's fast, but may also cut long textual payloads of various UI element's in order to optimize internal UI hierarchy snapshotting performance. If the performance is less important for you that the ability to validate full element's text then consider enabling this setting while calling [Get Element Text](https://www.w3.org/TR/webdriver1/#dfn-get-element-text) API.
 
 
 ## Scripts

package/WebDriverAgentMac/IntegrationTests/AMEditElementTests.m

@@ -38,8 +38,7 @@
 
 - (void)testSendingTextIntoNonFocusedEdit
 {
-  NSPredicate *predicate = [NSPredicate predicateWithFormat:@"placeholderValue.length == 0"];
-  XCUIElement *edit = [self.testedApplication.textFields matchingPredicate:predicate].firstMatch;
+  XCUIElement *edit = self.testedApplication.textFields.firstMatch;
   NSString *text = @"yolo😎";
   [edit am_setValue:text];
   XCTAssertTrue(edit.am_hasKeyboardInputFocus);
@@ -50,8 +49,7 @@
 
 - (void)testSendingTextIntoNonFocusedEditWithPlaceholderText
 {
-  NSPredicate *predicate = [NSPredicate predicateWithFormat:@"placeholderValue.length > 0"];
-  XCUIElement *edit = [self.testedApplication.textFields matchingPredicate:predicate].firstMatch;
+  XCUIElement *edit = self.testedApplication.textFields.firstMatch;
   NSString *text = @"yolo😎";
   [edit am_setValue:text];
   XCTAssertTrue(edit.am_hasKeyboardInputFocus);

package/WebDriverAgentMac/WebDriverAgentLib/Categories/XCUIElement+AMAttributes.h

@@ -34,9 +34,11 @@ NS_ASSUME_NONNULL_BEGIN
 - (NSDictionary<NSString *, NSNumber *> *)am_rect;
 
 /**
- Element text
+ Element text. If no text is found then an empty string is returned.
+
+ @throws Error if `fetchFullText` setting is enabled and there was an error while fetching the snapshot
  */
-- (nullable NSString *)am_text;
+- (NSString *)am_text;
 
 /**
  Element type represented as string

package/WebDriverAgentMac/WebDriverAgentLib/Categories/XCUIElement+AMAttributes.m

@@ -17,10 +17,12 @@
 #import "XCUIElement+AMAttributes.h"
 
 #import "AMGeometryUtils.h"
+#import "FBConfiguration.h"
 #import "FBElementTypeTransformer.h"
 #import "FBElementUtils.h"
 #import "FBExceptions.h"
 #import "FBMacros.h"
+#import "XCUIElementQuery+AMHelpers.h"
 
 @implementation XCUIElement (AMAttributes)
 
@@ -64,23 +66,20 @@
 
 - (NSString *)am_text
 {
-  NSString *value = [FBElementUtils stringValueWithValue:self.value];
-  if (nil != value && value.length > 0) {
-    return value;
+  if (!FBConfiguration.sharedConfiguration.fetchFullText) {
+    return [self am_textWithSource:self];
   }
-  NSString *label = self.label;
-  if (nil != label && label.length > 0) {
-    return label;
-  }
-  NSString *placeholderValue = self.placeholderValue;
-  if (nil != placeholderValue && placeholderValue.length > 0) {
-    return placeholderValue;
-  }
-  NSString *title = self.title;
-  if (nil != title && title.length > 0) {
-    return title;
+
+  NSError *error;
+  XCUIElementQuery *query = [self valueForKey:@"query"];
+  id<XCUIElementAttributes> snapshot = [query am_uniqueSnapshotWithError:&error];
+  if (nil != snapshot) {
+    return [self am_textWithSource:snapshot];
   }
-  return @"";
+
+  NSString *reason = [NSString stringWithFormat:@"Cannot extract the full text of '%@' element. Original error: %@",
+    self.description, error.description];
+  @throw [NSException exceptionWithName:FBInvalidElementStateException reason:reason userInfo:@{}];
 }
 
 - (NSString *)am_type
@@ -94,4 +93,20 @@
   return [predicate evaluateWithObject:self];
 }
 
+- (NSString *)am_textWithSource:(id<XCUIElementAttributes>)source
+{
+  NSArray<NSString *> *candidates = @[
+    [FBElementUtils stringValueWithValue:source.value],
+    source.label,
+    source.placeholderValue,
+    source.title
+  ];
+  for (NSString *text in candidates) {
+    if (nil != text && text.length > 0) {
+      return text;
+    }
+  }
+  return @"";
+}
+
 @end

package/WebDriverAgentMac/WebDriverAgentLib/Categories/XCUIElementQuery+AMHelpers.h

@@ -34,6 +34,14 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (NSArray<XCUIElement *> *)am_allMatches;
 
+/**
+ Returns single unique matching snapshot for the given query
+
+ @param error The error instance if there was a failure while retrieveing the snapshot
+ @returns The unqiue snapshot or nil if the element is stale
+ */
+- (nullable id<XCUIElementSnapshot>)am_uniqueSnapshotWithError:(NSError **)error;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/WebDriverAgentMac/WebDriverAgentLib/Categories/XCUIElementQuery+AMHelpers.m

@@ -32,4 +32,21 @@
     : self.allElementsBoundByAccessibilityElement;
 }
 
+- (id<XCUIElementSnapshot>)am_uniqueSnapshotWithError:(NSError **)error
+{
+  SEL selector = NSSelectorFromString(@"uniqueMatchingSnapshotWithError:");
+  NSMethodSignature *signature = [self methodSignatureForSelector:selector];
+  NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:signature];
+  invocation.target = self;
+  invocation.selector = selector;
+
+  [invocation setArgument:&error atIndex:2]; // index 0 = self, 1 = _cmd, 2 = first real argument
+
+  [invocation invoke];
+
+  __unsafe_unretained id returnValue = nil;
+  [invocation getReturnValue:&returnValue];
+  return returnValue;
+}
+
 @end

package/WebDriverAgentMac/WebDriverAgentLib/Commands/FBSessionCommands.m

@@ -237,6 +237,7 @@ const static NSString *CAPABILITIES_KEY = @"capabilities";
     @{
       AM_BOUND_ELEMENTS_BY_INDEX_SETTING: @(FBSession.activeSession.boundElementsByIndex),
       AM_USE_DEFAULT_UI_INTERRUPTIONS_HANDLING_SETTING: @(!application.am_doesNotHandleUIInterruptions),
+      AM_FETCH_FULL_TEXT: @(FBConfiguration.sharedConfiguration.fetchFullText),
     }
   );
 }
@@ -252,6 +253,9 @@ const static NSString *CAPABILITIES_KEY = @"capabilities";
     XCUIApplication *application = FBSession.activeSession.currentApplication;
     application.am_doesNotHandleUIInterruptions = ![[settings objectForKey:AM_USE_DEFAULT_UI_INTERRUPTIONS_HANDLING_SETTING] boolValue];
   }
+  if (nil != [settings objectForKey:AM_FETCH_FULL_TEXT]) {
+    FBConfiguration.sharedConfiguration.fetchFullText = [settings objectForKey:AM_FETCH_FULL_TEXT];
+  }
 
   return [self handleGetSettings:request];
 }

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/AMSettings.h

@@ -25,4 +25,7 @@ extern NSString* const AM_BOUND_ELEMENTS_BY_INDEX_SETTING;
  See https://developer.apple.com/videos/play/wwdc2020/10220/ for more details  */
 extern NSString* const AM_USE_DEFAULT_UI_INTERRUPTIONS_HANDLING_SETTING;
 
+/*! Whether to use custom snapshotting mechanism to fetch full element's text payload instead of the first 512 chars  */
+extern NSString* const AM_FETCH_FULL_TEXT;
+
 NS_ASSUME_NONNULL_END

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/AMSettings.m

@@ -17,5 +17,5 @@
 #import "AMSettings.h"
 
 NSString* const AM_BOUND_ELEMENTS_BY_INDEX_SETTING = @"boundElementsByIndex";
-
 NSString* const AM_USE_DEFAULT_UI_INTERRUPTIONS_HANDLING_SETTING = @"useDefaultUiInterruptionsHandling";
+NSString* const AM_FETCH_FULL_TEXT = @"fetchFullText";

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/FBConfiguration.h

@@ -30,6 +30,9 @@ NS_ASSUME_NONNULL_BEGIN
 /*! Enables XCTest automated screen recordings taking in Xcode 15+ */
 @property BOOL automaticScreenRecordings;
 
+/*! Whether to use custom snapshotting mechanism to fetch full element's text payload instead of the first 512 chars  */
+@property BOOL fetchFullText;
+
 /**
  The range of ports that the HTTP Server should attempt to bind on launch
  */

package/WebDriverAgentMac/WebDriverAgentLib/Utilities/FBConfiguration.m

@@ -11,6 +11,7 @@
 
 static NSUInteger const DefaultStartingPort = 10100;
 static NSUInteger const DefaultPortRange = 100;
+static BOOL FBFetchFullText = NO;
 
 @implementation FBConfiguration
 
@@ -75,6 +76,16 @@ static FBConfiguration *instance;
                                           forKey:@"DisableDiagnosticScreenRecordings"];
 }
 
+- (BOOL)fetchFullText
+{
+  return FBFetchFullText;
+}
+
+- (void)setFetchFullText:(BOOL)fetchFullText
+{
+  FBFetchFullText = fetchFullText;
+}
+
 - (NSRange)bindingPortRange
 {
   // 'WebDriverAgent --port 8080' can be passed via the arguments to the process