appium-mac2-driver 4.1.1 → 4.3.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [4.3.0](https://github.com/appium/appium-mac2-driver/compare/v4.2.0...v4.3.0) (2026-08-26)
+
+### Features
+
+* port WebDriverAgentMac's HTTP server to Network.framework ([#415](https://github.com/appium/appium-mac2-driver/issues/415)) ([f4ff684](https://github.com/appium/appium-mac2-driver/commit/f4ff68477925a0839c004a280bdda447cf9a4e17))
+
+## [4.2.0](https://github.com/appium/appium-mac2-driver/compare/v4.1.1...v4.2.0) (2026-08-10)
+
+### Features
+
+* locate WKWebView web elements via predicate string and class chain ([#412](https://github.com/appium/appium-mac2-driver/issues/412)) ([42a49aa](https://github.com/appium/appium-mac2-driver/commit/42a49aa8c321a2b554facfcf330d61d4feff99ed))
+
 ## [4.1.1](https://github.com/appium/appium-mac2-driver/compare/v4.1.0...v4.1.1) (2026-08-08)
 
 ### Bug Fixes

package/WebDriverAgentMac/IntegrationTests/AMFindElementTests.m

@@ -18,10 +18,15 @@
 
 #import "AMIntegrationTestCase.h"
 #import "FBConfiguration.h"
+#import "XCUIElement+AMAttributes.h"
 #import "XCUIElement+FBFind.h"
 #import "XCUIElement+FBClassChain.h"
 
 
+static NSString *const AMWebContainerDomId = @"am-web-container";
+static NSString *const AMWebButtonDomId = @"am-dom-button";
+static NSTimeInterval const AMWebContentTimeout = 10.0;
+
 @interface AMFindElementTests : AMIntegrationTestCase
 @end
 
@@ -36,6 +41,34 @@
   });
 }
 
+- (void)tearDown
+{
+  // Other test classes assume the app is on the Buttons tab by default and do not
+  // switch to it themselves - restore it so tests that dwell on the WebView tab here
+  // do not leak that state into whichever test class happens to run next.
+  [self switchToButtonsTab];
+  [super tearDown];
+}
+
+/**
+ WebKit builds a web view's accessibility subtree lazily, so the very first lookup
+ after the page appears may need a retry before the web content shows up. Polls the
+ given lookup until it finds something or the timeout elapses.
+ */
+- (NSArray<XCUIElement *> *)am_waitForWebContentUsingBlock:(NSArray<XCUIElement *> *(^)(void))block
+{
+  NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:AMWebContentTimeout];
+  NSArray<XCUIElement *> *matches = @[];
+  do {
+    matches = block();
+    if (matches.count > 0) {
+      return matches;
+    }
+    [NSThread sleepForTimeInterval:0.5];
+  } while ([deadline timeIntervalSinceNow] > 0);
+  return matches;
+}
+
 - (void)testSingleDescendantWithIdentifier
 {
   NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingIdentifier:@"_XCUI:CloseWindow"
@@ -46,10 +79,11 @@
 
 - (void)testSingleDescendantWithIdentifierWhileDomIdFallbackIsEnabled
 {
+  [self skipUnlessAccessibilityTrusted];
+  [self switchToWebViewTab];
   FBConfiguration.sharedConfiguration.useDomIdAsAccessibilityId = YES;
   @try {
-    // The application under test hosts no web content, so the fallback must find
-    // nothing extra and native identifiers must keep resolving as usual
+    // Native identifiers must keep resolving as usual
     NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingIdentifier:@"_XCUI:CloseWindow"
                                                                    shouldReturnAfterFirstMatch:NO];
     XCTAssertEqual(matches.count, 1);
@@ -58,11 +92,28 @@
     NSArray<XCUIElement *> *noMatches = [self.testedApplication fb_descendantsMatchingIdentifier:@"there_is_no_such_dom_id"
                                                                      shouldReturnAfterFirstMatch:NO];
     XCTAssertEqual(noMatches.count, 0);
+
+    // The web button has no native accessibility identifier, only a DOM id - the
+    // fallback must resolve it
+    NSArray<XCUIElement *> *webMatches = [self am_waitForWebContentUsingBlock:^NSArray<XCUIElement *> * {
+      return [self.testedApplication fb_descendantsMatchingIdentifier:AMWebButtonDomId
+                                            shouldReturnAfterFirstMatch:NO];
+    }];
+    XCTAssertEqual(webMatches.count, 1);
+    XCTAssertEqual(webMatches.firstObject.elementType, XCUIElementTypeButton);
   } @finally {
     FBConfiguration.sharedConfiguration.useDomIdAsAccessibilityId = NO;
   }
 }
 
+- (void)testSingleDescendantWithIdentifierFindsNothingForDomIdWhenFallbackIsDisabled
+{
+  [self switchToWebViewTab];
+  NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingIdentifier:AMWebButtonDomId
+                                                                 shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(matches.count, 0);
+}
+
 - (void)testSingleDescendantWithClassName
 {
   NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingClassName:@"XCUIElementTypeButton"
@@ -144,4 +195,116 @@
   XCTAssertEqualObjects([matches objectAtIndex:2].identifier, @"_XCUI:MinimizeWindow");
 }
 
+- (void)testSingleDescendantWithPredicateMatchingAmIdentifierWhileDomIdFallbackIsEnabled
+{
+  [self skipUnlessAccessibilityTrusted];
+  [self switchToWebViewTab];
+  FBConfiguration.sharedConfiguration.useDomIdAsAccessibilityId = YES;
+  @try {
+    NSPredicate *predicate = [NSPredicate predicateWithFormat:@"amIdentifier == %@ AND elementType == %lu",
+                              AMWebButtonDomId, XCUIElementTypeButton];
+    NSArray<XCUIElement *> *matches = [self am_waitForWebContentUsingBlock:^NSArray<XCUIElement *> * {
+      return [self.testedApplication fb_descendantsMatchingPredicate:predicate
+                                          shouldReturnAfterFirstMatch:NO];
+    }];
+    XCTAssertEqual(matches.count, 1);
+    XCTAssertEqual(matches.firstObject.elementType, XCUIElementTypeButton);
+  } @finally {
+    FBConfiguration.sharedConfiguration.useDomIdAsAccessibilityId = NO;
+  }
+}
+
+- (void)testSingleDescendantWithPredicateAmIdentifierAliasesNativeIdentifierWhenFallbackIsDisabled
+{
+  // amIdentifier mirrors am_identifier: with the setting off it is just the native
+  // identifier, same as the standard identifier attribute
+  NSPredicate *predicate = [NSPredicate predicateWithFormat:@"amIdentifier == %@", @"_XCUI:CloseWindow"];
+  NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingPredicate:predicate
+                                                                shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(matches.count, 1);
+}
+
+- (void)testSingleDescendantWithPredicateAmIdentifierFindsNothingForDomIdWhenFallbackIsDisabled
+{
+  [self switchToWebViewTab];
+  NSPredicate *predicate = [NSPredicate predicateWithFormat:@"amIdentifier == %@", AMWebButtonDomId];
+  NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingPredicate:predicate
+                                                                shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(matches.count, 0);
+}
+
+- (void)testSingleDescendantWithPredicateMatchingNestedAmRectKeyPath
+{
+  // A nested key path into an am_* attribute's resolved value (amRect is a
+  // {x, y, width, height} dictionary) must resolve through the same block-predicate
+  // rewrite as a bare am_* reference, not fall through to native key path resolution.
+  NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingIdentifier:@"_XCUI:CloseWindow"
+                                                                 shouldReturnAfterFirstMatch:YES];
+  XCTAssertEqual(matches.count, 1);
+  NSNumber *x = matches.firstObject.am_rect[@"x"];
+  XCTAssertNotNil(x);
+
+  NSPredicate *predicate = [NSPredicate predicateWithFormat:@"identifier == %@ AND amRect.x == %@",
+                            @"_XCUI:CloseWindow", x];
+  NSArray<XCUIElement *> *nestedMatches = [self.testedApplication fb_descendantsMatchingPredicate:predicate
+                                                                        shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(nestedMatches.count, 1);
+  XCTAssertEqualObjects(nestedMatches.firstObject.identifier, @"_XCUI:CloseWindow");
+
+  NSPredicate *nonMatchingPredicate = [NSPredicate predicateWithFormat:@"identifier == %@ AND amRect.x == %@",
+                                       @"_XCUI:CloseWindow", @(x.doubleValue + 1000)];
+  NSArray<XCUIElement *> *noMatches = [self.testedApplication fb_descendantsMatchingPredicate:nonMatchingPredicate
+                                                                    shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(noMatches.count, 0);
+}
+
+- (void)testSingleDescendantWithClassChainMatchingAmIdentifierOnLastSegmentWhileDomIdFallbackIsEnabled
+{
+  [self skipUnlessAccessibilityTrusted];
+  [self switchToWebViewTab];
+  FBConfiguration.sharedConfiguration.useDomIdAsAccessibilityId = YES;
+  @try {
+    NSString *query = [NSString stringWithFormat:@"**/XCUIElementTypeButton[`amIdentifier == '%@'`]", AMWebButtonDomId];
+    NSArray<XCUIElement *> *matches = [self am_waitForWebContentUsingBlock:^NSArray<XCUIElement *> * {
+      return [self.testedApplication fb_descendantsMatchingClassChain:query
+                                            shouldReturnAfterFirstMatch:NO];
+    }];
+    XCTAssertEqual(matches.count, 1);
+    XCTAssertEqual(matches.firstObject.elementType, XCUIElementTypeButton);
+  } @finally {
+    FBConfiguration.sharedConfiguration.useDomIdAsAccessibilityId = NO;
+  }
+}
+
+- (void)testSingleDescendantWithClassChainMatchingAmIdentifierOnAncestorSegmentWhileDomIdFallbackIsEnabled
+{
+  [self skipUnlessAccessibilityTrusted];
+  [self switchToWebViewTab];
+  FBConfiguration.sharedConfiguration.useDomIdAsAccessibilityId = YES;
+  @try {
+    // The amIdentifier predicate sits on a non-terminal (ancestor) segment here, not
+    // the last one - this works because every class chain segment's predicate is
+    // formatted through the same NSPredicate+FBFormat rewrite, regardless of position
+    NSString *query = [NSString stringWithFormat:@"**/XCUIElementTypeGroup[`amIdentifier == '%@'`]/XCUIElementTypeButton",
+                       AMWebContainerDomId];
+    NSArray<XCUIElement *> *matches = [self am_waitForWebContentUsingBlock:^NSArray<XCUIElement *> * {
+      return [self.testedApplication fb_descendantsMatchingClassChain:query
+                                            shouldReturnAfterFirstMatch:NO];
+    }];
+    XCTAssertEqual(matches.count, 1);
+    XCTAssertEqual(matches.firstObject.elementType, XCUIElementTypeButton);
+  } @finally {
+    FBConfiguration.sharedConfiguration.useDomIdAsAccessibilityId = NO;
+  }
+}
+
+- (void)testSingleDescendantWithClassChainAmIdentifierFindsNothingForDomIdWhenFallbackIsDisabled
+{
+  [self switchToWebViewTab];
+  NSString *query = [NSString stringWithFormat:@"**/XCUIElementTypeButton[`amIdentifier == '%@'`]", AMWebButtonDomId];
+  NSArray<XCUIElement *> *matches = [self.testedApplication fb_descendantsMatchingClassChain:query
+                                                                 shouldReturnAfterFirstMatch:NO];
+  XCTAssertEqual(matches.count, 0);
+}
+
 @end

package/WebDriverAgentMac/IntegrationTests/AMIntegrationTestCase.h

@@ -32,6 +32,17 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (void)switchToEditsTab;
 
+- (void)switchToWebViewTab;
+
+/**
+ Skips the current test unless this process is trusted for the Accessibility API.
+ Tests that rely on the useDomIdAsAccessibilityId fallback need this - without it,
+ WebKit DOM identifier resolution silently returns nothing, which otherwise surfaces
+ as a confusing "found 0 elements" test failure rather than a clear "grant
+ Accessibility permission and re-run" skip reason.
+ */
+- (void)skipUnlessAccessibilityTrusted;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/WebDriverAgentMac/IntegrationTests/AMIntegrationTestCase.m

@@ -16,6 +16,7 @@
 
 #import "AMIntegrationTestCase.h"
 
+#import "AMSnapshotUtils.h"
 #import "FBConfiguration.h"
 
 @interface AMIntegrationTestCase ()
@@ -53,4 +54,36 @@
   [self.testedApplication.radioButtons[@"Edits"].firstMatch click];
 }
 
+- (void)switchToWebViewTab
+{
+  [self.testedApplication.radioButtons[@"WebView"].firstMatch click];
+}
+
+/**
+ Reading AXDOMIdentifier (unlike ordinary XCTest snapshotting) goes through the macOS
+ Accessibility API, which requires the process to be trusted under System Settings > Privacy &
+ Security > Accessibility. Two things make that grant easy to lose track of while iterating
+ locally in Xcode:
+
+ - Ad-hoc code signing loses the grant on every rebuild. macOS ties an Accessibility grant to
+   the binary's signing identity (its CDHash), and the default ad-hoc signature
+   (Signature=adhoc, no Team ID) gets a new CDHash on every build. The permission then appears
+   to "not stick" - it was actually granted, just to a binary that no longer exists. Assigning
+   a stable signing identity (e.g. an "Apple Development" certificate under a real Team ID) in
+   the target's Signing & Capabilities keeps the CDHash constant across rebuilds, so the grant
+   persists. This has to be done for both the WebDriverAgent app target and the
+   IntegrationTests test bundle target - granting only one leaves the other still ad-hoc signed
+   and still losing trust every build.
+ - xcodebuild build alone does not regenerate the signed XCTRunner wrapper app that actually
+   hosts and runs the tests, so a plain build after a signing change can silently run against a
+   stale runner. Use build-for-testing (or test, or Xcode's own Test action) instead.
+ */
+- (void)skipUnlessAccessibilityTrusted
+{
+  XCTSkipUnless(AMSnapshotUtils.isAccessibilityTrusted,
+               @"This process is not trusted for the Accessibility API. Grant Accessibility "
+               @"permission to it in System Settings > Privacy & Security > Accessibility "
+               @"(note: an ad-hoc-signed build's grant does not survive a rebuild), then re-run.");
+}
+
 @end

package/WebDriverAgentMac/IntegrationTests/AMW3CActionsTests.m

@@ -18,6 +18,7 @@
 
 #import "AMIntegrationTestCase.h"
 #import "XCUIApplication+FBW3CActions.h"
+#import "XCUIElement+AMEditable.h"
 
 
 @interface AMW3CActionsTests : AMIntegrationTestCase
@@ -49,15 +50,6 @@
     },
     ],
 
-    // Chain element with empty 'actions'
-    @[@{
-        @"type": @"pointer",
-        @"id": @"finger1",
-        @"parameters": @{@"pointerType": @"mouse"},
-        @"actions": @[],
-    },
-    ],
-
     // Chain element without type
     @[@{
         @"id": @"finger1",
@@ -343,6 +335,9 @@
   [self switchToEditsTab];
   XCUIElement *edit = self.testedApplication.textFields.firstMatch;
   [edit click];
+  NSError *clearError;
+  XCTAssertTrue([edit am_clearTextWithError:&clearError]);
+  XCTAssertNil(clearError);
 
   NSArray<NSDictionary<NSString *, id> *> *gesture =
   @[@{
@@ -375,6 +370,9 @@
   [self switchToEditsTab];
   XCUIElement *edit = self.testedApplication.textFields.firstMatch;
   [edit click];
+  NSError *clearError;
+  XCTAssertTrue([edit am_clearTextWithError:&clearError]);
+  XCTAssertNil(clearError);
 
   NSArray<NSDictionary<NSString *, id> *> *gesture =
   @[@{

package/WebDriverAgentMac/WebDriverAgent/Base.lproj/Main.storyboard

@@ -685,7 +685,7 @@
         <scene sceneID="R2V-B0-nI4">
             <objects>
                 <windowController id="B8D-0N-5wS" sceneMemberID="viewController">
-                    <window key="window" title="Window" allowsToolTipsWhenApplicationIsInactive="NO" autorecalculatesKeyViewLoop="NO" releasedWhenClosed="NO" visibleAtLaunch="NO" animationBehavior="default" id="IQv-IB-iLA">
+                    <window key="window" title="Window" allowsToolTipsWhenApplicationIsInactive="NO" autorecalculatesKeyViewLoop="NO" releasedWhenClosed="NO" visibleAtLaunch="NO" animationBehavior="default" restorable="NO" id="IQv-IB-iLA">
                         <windowStyleMask key="styleMask" titled="YES" closable="YES" miniaturizable="YES" resizable="YES"/>
                         <windowPositionMask key="initialPositionMask" leftStrut="YES" rightStrut="YES" topStrut="YES" bottomStrut="YES"/>
                         <rect key="contentRect" x="196" y="240" width="480" height="270"/>
@@ -709,6 +709,7 @@
                     <tabViewItems>
                         <tabViewItem identifier="" id="Mia-WI-iEB"/>
                         <tabViewItem identifier="" id="sIZ-jZ-jj9"/>
+                        <tabViewItem identifier="" id="Nlk-3F-Wcb"/>
                     </tabViewItems>
                     <tabView key="tabView" type="noTabsNoBorder" id="Rch-4v-RJW">
                         <rect key="frame" x="0.0" y="0.0" width="450" height="300"/>
@@ -722,6 +723,7 @@
                         <outlet property="tabView" destination="Rch-4v-RJW" id="1XV-Um-WgP"/>
                         <segue destination="Pkx-be-7b9" kind="relationship" relationship="tabItems" id="IJQ-4v-ZpO"/>
                         <segue destination="bnY-XE-5sK" kind="relationship" relationship="tabItems" id="MtI-PF-Enx"/>
+                        <segue destination="Qzv-6y-WKw" kind="relationship" relationship="tabItems" id="Pma-8s-CkV"/>
                     </connections>
                 </tabViewController>
                 <customObject id="iEe-Sq-WC0" userLabel="First Responder" customClass="NSResponder" sceneMemberID="firstResponder"/>
@@ -832,5 +834,18 @@
             </objects>
             <point key="canvasLocation" x="545" y="-408"/>
         </scene>
+        <!--WebView-->
+        <scene sceneID="tGx-1M-hRz">
+            <objects>
+                <viewController title="WebView" id="Qzv-6y-WKw" customClass="WebViewController" sceneMemberID="viewController">
+                    <view key="view" id="Fbv-Y8-Enh">
+                        <rect key="frame" x="0.0" y="0.0" width="450" height="300"/>
+                        <autoresizingMask key="autoresizingMask"/>
+                    </view>
+                </viewController>
+                <customObject id="Xdm-hz-1Yc" userLabel="First Responder" customClass="NSResponder" sceneMemberID="firstResponder"/>
+            </objects>
+            <point key="canvasLocation" x="1075" y="-408"/>
+        </scene>
     </scenes>
 </document>

package/WebDriverAgentMac/WebDriverAgent/WebViewController.h

@@ -0,0 +1,21 @@
+/*
+ * 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 <Cocoa/Cocoa.h>
+
+@interface WebViewController : NSViewController
+
+@end

package/WebDriverAgentMac/WebDriverAgent/WebViewController.m

@@ -0,0 +1,49 @@
+/*
+ * 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 "WebViewController.h"
+
+#import <WebKit/WebKit.h>
+
+/*
+ None of these elements set a native accessibility identifier, so WebKit leaves their
+ standard AXIdentifier empty and only exposes their DOM `id` through AXDOMIdentifier -
+ this mirrors real-world web content and is what useDomIdAsAccessibilityId is meant to
+ fall back onto.
+ */
+static NSString *const AMWebViewHTML =
+@"<!DOCTYPE html><html><head><meta charset=\"utf-8\"></head><body>"
+@"<div id=\"am-web-container\" role=\"group\">"
+@"<button id=\"am-dom-button\">Web Button</button>"
+@"<span id=\"am-dom-text\">Web Text</span>"
+@"</div>"
+@"</body></html>";
+
+@implementation WebViewController
+
+- (void)loadView
+{
+  self.view = [[WKWebView alloc] initWithFrame:NSMakeRect(0, 0, 450, 300)];
+}
+
+- (void)viewDidLoad
+{
+  [super viewDidLoad];
+
+  [(WKWebView *)self.view loadHTMLString:AMWebViewHTML baseURL:nil];
+}
+
+@end

package/WebDriverAgentMac/WebDriverAgentLib/Categories/NSPredicate+FBFormat.m

@@ -10,6 +10,7 @@
 #import "NSPredicate+FBFormat.h"
 
 #import "NSExpression+FBFormat.h"
+#import "XCUIElement+AMAttributes.h"
 
 @implementation NSPredicate (FBFormat)
 
@@ -33,9 +34,88 @@
   return original;
 }
 
+/**
+ Whether the given expression is a key path referencing one of the am_* predicate
+ attributes (AM_IDENTIFIER_ATTRIBUTE_NAME and friends, see XCUIElement+AMAttributes),
+ either directly (`amRect`) or through a nested key path into its resolved value
+ (`amRect.x`).
+
+ @return The referenced am_* attribute name, or nil if it isn't one
+ */
++ (nullable NSString *)fb_amAttributeNameForExpression:(NSExpression *)expression
+{
+  if (NSKeyPathExpressionType != expression.expressionType) {
+    return nil;
+  }
+  NSString *keyPath = expression.keyPath;
+  NSUInteger dotPos = [keyPath rangeOfString:@"."].location;
+  NSString *attributeName = NSNotFound == dotPos ? keyPath : [keyPath substringToIndex:dotPos];
+  return [[XCUIElement am_predicateAttributeNames] containsObject:attributeName] ? attributeName : nil;
+}
+
+/**
+ Rebuilds a comparison predicate that references an am_* attribute on one side into a
+ block predicate that resolves that attribute directly off the snapshot node being
+ matched and compares it with the same operator/options as the original. Block
+ predicates are evaluated per-node by matchingPredicate:/containingPredicate: (this is
+ how the accessibility id DOM fallback already resolves elements), unlike plain
+ comparison predicates whose key path resolution WebKit content does not reliably
+ observe. A nested key path into the attribute's resolved value (e.g. `amRect.x`) is
+ resolved with a plain valueForKeyPath: lookup after the attribute value itself is
+ resolved.
+
+ @param cp the original comparison predicate, known to reference an am_* attribute
+ @param amAttributeName the am_* attribute name referenced
+ @param amAttributeOnLeft whether it is the left or the right expression
+ @return an equivalent block-based predicate
+ */
++ (NSPredicate *)fb_amAttributePredicateForComparison:(NSComparisonPredicate *)cp
+                                       amAttributeName:(NSString *)amAttributeName
+                                      amAttributeOnLeft:(BOOL)amAttributeOnLeft
+{
+  NSExpression *amAttributeExpression = amAttributeOnLeft ? cp.leftExpression : cp.rightExpression;
+  NSExpression *otherExpression = amAttributeOnLeft ? cp.rightExpression : cp.leftExpression;
+  NSString *amKeyPath = amAttributeExpression.keyPath;
+  NSUInteger dotPos = [amKeyPath rangeOfString:@"."].location;
+  NSString *amValueKeyPathSuffix = NSNotFound == dotPos ? nil : [amKeyPath substringFromIndex:(dotPos + 1)];
+  NSComparisonPredicateModifier modifier = cp.comparisonPredicateModifier;
+  NSPredicateOperatorType operatorType = cp.predicateOperatorType;
+  NSComparisonPredicateOptions options = cp.options;
+  return [NSPredicate predicateWithBlock:^BOOL(id snapshot, NSDictionary *bindings) {
+    id amValue = [XCUIElement am_valueForPredicateAttributeName:amAttributeName target:snapshot];
+    if (amValueKeyPathSuffix.length > 0) {
+      amValue = [amValue valueForKeyPath:amValueKeyPathSuffix];
+    }
+    amValue = amValue ?: @"";
+    NSMutableDictionary *context = bindings ? [bindings mutableCopy] : [NSMutableDictionary dictionary];
+    id otherValue = [otherExpression expressionValueWithObject:snapshot context:context];
+    NSExpression *amExpression = [NSExpression expressionForConstantValue:amValue];
+    NSExpression *otherConstantExpression = [NSExpression expressionForConstantValue:otherValue];
+    NSComparisonPredicate *rewritten = amAttributeOnLeft
+      ? [NSComparisonPredicate predicateWithLeftExpression:amExpression
+                                            rightExpression:otherConstantExpression
+                                                   modifier:modifier
+                                                       type:operatorType
+                                                    options:options]
+      : [NSComparisonPredicate predicateWithLeftExpression:otherConstantExpression
+                                            rightExpression:amExpression
+                                                   modifier:modifier
+                                                       type:operatorType
+                                                    options:options];
+    return [rewritten evaluateWithObject:nil];
+  }];
+}
+
 + (instancetype)fb_formatSearchPredicate:(NSPredicate *)input
 {
   return [self.class fb_predicateWithPredicate:input comparisonModifier:^NSPredicate *(NSComparisonPredicate *cp) {
+    NSString *leftAmAttribute = [self.class fb_amAttributeNameForExpression:cp.leftExpression];
+    NSString *rightAmAttribute = [self.class fb_amAttributeNameForExpression:cp.rightExpression];
+    if (nil != leftAmAttribute || nil != rightAmAttribute) {
+      return [self.class fb_amAttributePredicateForComparison:cp
+                                                amAttributeName:leftAmAttribute ?: rightAmAttribute
+                                              amAttributeOnLeft:nil != leftAmAttribute];
+    }
     NSExpression *left = [NSExpression fb_wdExpressionWithExpression:[cp leftExpression]];
     NSExpression *right = [NSExpression fb_wdExpressionWithExpression:[cp rightExpression]];
     return [NSComparisonPredicate predicateWithLeftExpression:left

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

@@ -18,6 +18,17 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*!
+ Predicate string / class chain keypath names for the am_* attributes below. These are
+ non-standard, Mac2-driver-specific attributes, in addition to the standard
+ XCUIElementAttributes ones.
+ */
+extern NSString *const AM_IDENTIFIER_ATTRIBUTE_NAME;
+extern NSString *const AM_RECT_ATTRIBUTE_NAME;
+extern NSString *const AM_TEXT_ATTRIBUTE_NAME;
+extern NSString *const AM_TYPE_ATTRIBUTE_NAME;
+extern NSString *const AM_HAS_KEYBOARD_INPUT_FOCUS_ATTRIBUTE_NAME;
+
 @interface XCUIElement (AMAttributes)
 
 /**
@@ -58,7 +69,24 @@ NS_ASSUME_NONNULL_BEGIN
 
  @return The identifier. Could be an empty string
  */
-- (NSString *)am_wdIdentifier;
+- (NSString *)am_identifier;
+
+/**
+ The full set of am_* predicate attribute names (AM_IDENTIFIER_ATTRIBUTE_NAME and
+ friends) usable in predicate string / class chain locators.
+ */
++ (NSArray<NSString *> *)am_predicateAttributeNames;
+
+/**
+ Resolves the value of an am_* predicate attribute name directly against a target,
+ which may be a live XCUIElement or a raw id<XCUIElementSnapshot> - the latter keeps
+ per-node predicate evaluation cheap by not needing to resolve a live element first.
+
+ @param name one of AM_IDENTIFIER_ATTRIBUTE_NAME and friends
+ @param target the XCUIElement or id<XCUIElementSnapshot> to resolve the value against
+ @return The resolved value, or nil if name is not a known am_* attribute name
+ */
++ (nullable id)am_valueForPredicateAttributeName:(NSString *)name target:(id)target;
 
 @end