appium-webdriveragent 11.1.7 → 11.3.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [11.3.0](https://github.com/appium/WebDriverAgent/compare/v11.2.0...v11.3.0) (2026-03-05)
+
+### Features
+
+* add 6 tvOS button values for `mobile: pressButton` ([#1116](https://github.com/appium/WebDriverAgent/issues/1116)) ([efd64ed](https://github.com/appium/WebDriverAgent/commit/efd64ede7212b322f412cd6b25eab9c8097c286d))
+
+## [11.2.0](https://github.com/appium/WebDriverAgent/compare/v11.1.7...v11.2.0) (2026-03-04)
+
+### Features
+
+* add `action` and `camera` values for `mobile: pressButton` ([#1115](https://github.com/appium/WebDriverAgent/issues/1115)) ([3df0284](https://github.com/appium/WebDriverAgent/commit/3df0284d741f8b4a36a9e12e130ecf0711b60366))
+
 ## [11.1.7](https://github.com/appium/WebDriverAgent/compare/v11.1.6...v11.1.7) (2026-03-03)
 
 ### Miscellaneous Chores

package/WebDriverAgentLib/Categories/XCUIDevice+FBHelpers.h

@@ -95,10 +95,19 @@ typedef NS_ENUM(NSUInteger, FBUIInterfaceAppearance) {
  */
 - (BOOL)fb_openUrl:(NSString *)url withApplication:(NSString *)bundleId error:(NSError **)error;
 
+/**
+ Checks if the device has a specific hardware button available.
+
+ @param buttonName The name of the button to check (e.g., "home", "volumeUp", "volumeDown", "action", "camera")
+ @return YES if the button is available on the device, otherwise NO
+ */
+- (BOOL)fb_hasButton:(NSString *)buttonName;
+
 /**
  Presses the corresponding hardware button on the device with duration.
 
- @param buttonName One of the supported button names: volumeUp (real devices only), volumeDown (real device only), home
+ @param buttonName One of the supported button names: volumeUp (real devices only), volumeDown (real device only),
+                   camera (supported iOS 16+ real devices only), action (supported iOS 16+ devices only), home
  @param duration Duration in seconds or nil.
                 This argument works only on tvOS. When this argument is nil on tvOS,
                 https://developer.apple.com/documentation/xctest/xcuiremote/1627476-pressbutton will be called.

package/WebDriverAgentLib/Categories/XCUIDevice+FBHelpers.m

@@ -26,6 +26,66 @@
 static const NSTimeInterval FBHomeButtonCoolOffTime = 1.;
 static const NSTimeInterval FBScreenLockTimeout = 5.;
 
+#if TARGET_OS_TV
+NSDictionary<NSString *, NSNumber *> *fb_availableButtonNames(void) {
+  static dispatch_once_t onceToken;
+  static NSDictionary *result;
+  dispatch_once(&onceToken, ^{
+    NSMutableDictionary *buttons = [NSMutableDictionary dictionary];
+    // https://developer.apple.com/design/human-interface-guidelines/remotes
+    buttons[@"up"] = @(XCUIRemoteButtonUp);                     // 0
+    buttons[@"down"] = @(XCUIRemoteButtonDown);                 // 1
+    buttons[@"left"] = @(XCUIRemoteButtonLeft);                 // 2
+    buttons[@"right"] = @(XCUIRemoteButtonRight);               // 3
+    buttons[@"select"] = @(XCUIRemoteButtonSelect);             // 4
+    buttons[@"menu"] = @(XCUIRemoteButtonMenu);                 // 5
+    buttons[@"playpause"] = @(XCUIRemoteButtonPlayPause);       // 6
+    buttons[@"home"] = @(XCUIRemoteButtonHome);                 // 7
+#if __clang_major__ >= 15 // Xcode 15+
+    buttons[@"pageup"] = @(XCUIRemoteButtonPageUp);             // 9
+    buttons[@"pagedown"] = @(XCUIRemoteButtonPageDown);         // 10
+    buttons[@"guide"] = @(XCUIRemoteButtonGuide);               // 11
+#endif
+#if __clang_major__ >= 17 // likely Xcode 16.3+
+    if (@available(tvOS 18.1, *)) {
+      buttons[@"fourcolors"] = @(XCUIRemoteButtonFourColors);   // 12
+      buttons[@"onetwothree"] = @(XCUIRemoteButtonOneTwoThree); // 13
+      buttons[@"tvprovider"] = @(XCUIRemoteButtonTVProvider);   // 14
+    }
+#endif
+    result = [buttons copy];
+  });
+  return result;
+}
+#else
+NSDictionary<NSString *, NSNumber *> *fb_availableButtonNames(void) {
+  static dispatch_once_t onceToken;
+  static NSDictionary *result;
+  dispatch_once(&onceToken, ^{
+    NSMutableDictionary *buttons = [NSMutableDictionary dictionary];
+    buttons[@"home"] = @(XCUIDeviceButtonHome);             // 1
+#if !TARGET_OS_SIMULATOR
+    buttons[@"volumeup"] = @(XCUIDeviceButtonVolumeUp);     // 2
+    buttons[@"volumedown"] = @(XCUIDeviceButtonVolumeDown); // 3
+#endif
+    if (@available(iOS 16.0, *)) {
+#if __clang_major__ >= 15 // likely Xcode 15+
+      if ([XCUIDevice.sharedDevice hasHardwareButton:XCUIDeviceButtonAction]) {
+        buttons[@"action"] = @(XCUIDeviceButtonAction);     // 4
+      }
+#endif
+#if (!TARGET_OS_SIMULATOR && __clang_major__ >= 16) // likely Xcode 16+
+      if ([XCUIDevice.sharedDevice hasHardwareButton:XCUIDeviceButtonCamera]) {
+        buttons[@"camera"] = @(XCUIDeviceButtonCamera);
+      }
+#endif
+    }
+    result = [buttons copy];
+  });
+  return result;
+}
+#endif
+
 @implementation XCUIDevice (FBHelpers)
 
 static bool fb_isLocked;
@@ -210,6 +270,11 @@ static bool fb_isLocked;
   }
 }
 
+- (BOOL)fb_hasButton:(NSString *)buttonName
+{
+  return fb_availableButtonNames()[buttonName.lowercaseString] != nil;
+}
+
 - (BOOL)fb_pressButton:(NSString *)buttonName
            forDuration:(nullable NSNumber *)duration
                  error:(NSError **)error
@@ -217,71 +282,23 @@ static bool fb_isLocked;
 #if !TARGET_OS_TV
   return [self fb_pressButton:buttonName error:error];
 #else
-  NSMutableArray<NSString *> *supportedButtonNames = [NSMutableArray array];
-  NSInteger remoteButton = -1; // no remote button
-  if ([buttonName.lowercaseString isEqualToString:@"home"]) {
-    //  XCUIRemoteButtonHome        = 7
-    remoteButton = XCUIRemoteButtonHome;
-  }
-  [supportedButtonNames addObject:@"home"];
-
-  // https://developer.apple.com/design/human-interface-guidelines/tvos/remote-and-controllers/remote/
-  if ([buttonName.lowercaseString isEqualToString:@"up"]) {
-    //  XCUIRemoteButtonUp          = 0,
-    remoteButton = XCUIRemoteButtonUp;
-  }
-  [supportedButtonNames addObject:@"up"];
 
-  if ([buttonName.lowercaseString isEqualToString:@"down"]) {
-    //  XCUIRemoteButtonDown        = 1,
-    remoteButton = XCUIRemoteButtonDown;
-  }
-  [supportedButtonNames addObject:@"down"];
-
-  if ([buttonName.lowercaseString isEqualToString:@"left"]) {
-    //  XCUIRemoteButtonLeft        = 2,
-    remoteButton = XCUIRemoteButtonLeft;
-  }
-  [supportedButtonNames addObject:@"left"];
-
-  if ([buttonName.lowercaseString isEqualToString:@"right"]) {
-    //  XCUIRemoteButtonRight       = 3,
-    remoteButton = XCUIRemoteButtonRight;
-  }
-  [supportedButtonNames addObject:@"right"];
-
-  if ([buttonName.lowercaseString isEqualToString:@"menu"]) {
-    //  XCUIRemoteButtonMenu        = 5,
-    remoteButton = XCUIRemoteButtonMenu;
-  }
-  [supportedButtonNames addObject:@"menu"];
-
-  if ([buttonName.lowercaseString isEqualToString:@"playpause"]) {
-    //  XCUIRemoteButtonPlayPause   = 6,
-    remoteButton = XCUIRemoteButtonPlayPause;
-  }
-  [supportedButtonNames addObject:@"playpause"];
-
-  if ([buttonName.lowercaseString isEqualToString:@"select"]) {
-    //  XCUIRemoteButtonSelect      = 4,
-    remoteButton = XCUIRemoteButtonSelect;
-  }
-  [supportedButtonNames addObject:@"select"];
-
-  if (remoteButton == -1) {
+  NSDictionary<NSString *, NSNumber *> *availableButtons = fb_availableButtonNames();
+  NSNumber *buttonValue = availableButtons[buttonName.lowercaseString];
+  
+  if (!buttonValue) {
+    NSArray *sortedKeys = [availableButtons.allKeys sortedArrayUsingSelector:@selector(compare:)];
     return [[[FBErrorBuilder builder]
-             withDescriptionFormat:@"The button '%@' is unknown. Only the following button names are supported: %@", buttonName, supportedButtonNames]
+             withDescriptionFormat:@"The button '%@' is not supported. The device under test only supports the following buttons: %@", buttonName, sortedKeys]
             buildError:error];
   }
-
   if (duration) {
-    // https://developer.apple.com/documentation/xctest/xcuiremote/1627475-pressbutton
-    [[XCUIRemote sharedRemote] pressButton:remoteButton forDuration:duration.doubleValue];
+    // https://developer.apple.com/documentation/xcuiautomation/xcuiremote/press(_:forduration:)
+    [[XCUIRemote sharedRemote] pressButton:(XCUIRemoteButton)[buttonValue unsignedIntegerValue] forDuration:duration.doubleValue];
   } else {
-    // https://developer.apple.com/documentation/xctest/xcuiremote/1627476-pressbutton
-    [[XCUIRemote sharedRemote] pressButton:remoteButton];
+    // https://developer.apple.com/documentation/xcuiautomation/xcuiremote/press(_:)
+    [[XCUIRemote sharedRemote] pressButton:(XCUIRemoteButton)[buttonValue unsignedIntegerValue]];
   }
-
   return YES;
 #endif
 }
@@ -290,29 +307,16 @@ static bool fb_isLocked;
 - (BOOL)fb_pressButton:(NSString *)buttonName
                  error:(NSError **)error
 {
-  NSMutableArray<NSString *> *supportedButtonNames = [NSMutableArray array];
-  XCUIDeviceButton dstButton = 0;
-  if ([buttonName.lowercaseString isEqualToString:@"home"]) {
-    dstButton = XCUIDeviceButtonHome;
-  }
-  [supportedButtonNames addObject:@"home"];
-#if !TARGET_OS_SIMULATOR
-  if ([buttonName.lowercaseString isEqualToString:@"volumeup"]) {
-    dstButton = XCUIDeviceButtonVolumeUp;
-  }
-  if ([buttonName.lowercaseString isEqualToString:@"volumedown"]) {
-    dstButton = XCUIDeviceButtonVolumeDown;
-  }
-  [supportedButtonNames addObject:@"volumeUp"];
-  [supportedButtonNames addObject:@"volumeDown"];
-#endif
-
-  if (dstButton == 0) {
+  NSDictionary<NSString *, NSNumber *> *availableButtons = fb_availableButtonNames();
+  NSNumber *buttonValue = availableButtons[buttonName.lowercaseString];
+  
+  if (!buttonValue) {
+    NSArray *sortedKeys = [availableButtons.allKeys sortedArrayUsingSelector:@selector(compare:)];
     return [[[FBErrorBuilder builder]
-             withDescriptionFormat:@"The button '%@' is unknown. Only the following button names are supported: %@", buttonName, supportedButtonNames]
+             withDescriptionFormat:@"The button '%@' is not supported. The device under test only supports the following buttons: %@", buttonName, sortedKeys]
             buildError:error];
   }
-  [self pressButton:dstButton];
+  [self pressButton:(XCUIDeviceButton)[buttonValue unsignedIntegerValue]];
   return YES;
 }
 #endif

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentTests/IntegrationTests/XCUIDeviceHelperTests.m

@@ -186,6 +186,22 @@
   XCTAssertNil(error);
 }
 
+- (void)testPressingDeviceSpecificButton
+{
+  NSError *error;
+  BOOL hasActionButton = [XCUIDevice.sharedDevice fb_hasButton:@"action"];
+  BOOL didPressButton = [XCUIDevice.sharedDevice fb_pressButton:@"action"
+                                                     forDuration:nil
+                                                           error:&error];
+  if (hasActionButton) {
+    XCTAssertTrue(didPressButton);
+    XCTAssertNil(error);
+  } else {
+    XCTAssertFalse(didPressButton);
+    XCTAssertNotNil(error);
+  }
+}
+
 - (void)testPressingSupportedButtonNumber
 {
   NSError *error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-webdriveragent",
-  "version": "11.1.7",
+  "version": "11.3.0",
   "description": "Package bundling WebDriverAgent",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",