appium-webdriveragent 16.3.0 → 16.4.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [16.4.0](https://github.com/appium/WebDriverAgent/compare/v16.3.0...v16.4.0) (2026-08-19)
+
+### Features
+
+* Add Digital Crown rotation and hand gesture support for watchOS ([#1215](https://github.com/appium/WebDriverAgent/issues/1215)) ([5e021f8](https://github.com/appium/WebDriverAgent/commit/5e021f8d12791d126e9524763d9455ceaf04bb2f))
+
 ## [16.3.0](https://github.com/appium/WebDriverAgent/compare/v16.2.2...v16.3.0) (2026-08-18)
 
 ### Features

package/PrivateHeaders/XCTest/XCUIDevice.h

@@ -89,7 +89,6 @@
 - (void)_silentPressButton:(long long)button;
 - (void)holdHomeButtonForDuration:(double)duration;
 - (void)pressLockButton;
-- (void)rotateDigitalCrown:(double)crown velocity:(double)velocity;
 - (void)ensureSystemAppIsLoaded;
 - (void)attachLocalizableStringsData;
 - (_Bool)startHIDEventRecordingWithError:(id *)error;

package/WebDriverAgentLib/Categories/XCUIDevice+FBHelpers.h

@@ -166,6 +166,40 @@ typedef NS_ENUM(NSUInteger, FBUIInterfaceAppearance) {
  */
 - (nullable NSNumber *)fb_getAppearance;
 
+#if TARGET_OS_WATCH
+/**
+ Rotates the Digital Crown on Apple Watch. See
+ https://developer.apple.com/documentation/xcuiautomation/xcuidevice/rotatedigitalcrown(delta:velocity:)
+ and https://developer.apple.com/documentation/xcuiautomation/xcuidevice/rotatedigitalcrown(delta:)
+ Invoked dynamically (this selector was only added to the SDK in Xcode 16.3), so this compiles against
+ older Xcode versions too - it just fails at runtime with an error if the OS/SDK combination in use
+ doesn't actually implement it.
+
+ @param delta The number of full crown rotations, e.g. 1.0 is one complete turn.
+              The sign gives the direction: positive rotates up/clockwise, negative rotates down/counterclockwise.
+ @param velocity The rotation speed, in rotations per second, e.g. 1.0 completes one full
+                 rotation per second. This is the raw value behind the public XCUIGestureVelocity
+                 API, which only exposes it via named presets (.slow/.default/.fast).
+                 Pass nil to use XCTest's own default velocity instead of specifying one explicitly.
+ @param error If there is an error, upon return contains an NSError object that describes the problem.
+ @return YES if the operation succeeds, otherwise NO.
+ */
+- (BOOL)fb_rotateDigitalCrown:(double)delta velocity:(nullable NSNumber *)velocity error:(NSError **)error;
+
+/**
+ Performs a hand gesture on Apple Watch (e.g. Double Tap, Wrist Flick). See
+ https://developer.apple.com/documentation/xcuiautomation/xcuidevice/perform(handgesture:)
+ Invoked dynamically (this selector was only added to the SDK in Xcode 16.3), so this compiles against
+ older Xcode versions too - it just fails at runtime with an error if the OS/SDK combination in use
+ doesn't actually implement it.
+
+ @param gestureName One of the supported gesture names: doubleTap (watchOS 10+), flick (watchOS 26+).
+ @param error If there is an error, upon return contains an NSError object that describes the problem.
+ @return YES if the operation succeeds, otherwise NO.
+ */
+- (BOOL)fb_performHandGesture:(NSString *)gestureName error:(NSError **)error;
+#endif // TARGET_OS_WATCH
+
 #if !TARGET_OS_TV
 /**
  Allows to set a simulated geolocation coordinates.

package/WebDriverAgentLib/Categories/XCUIDevice+FBHelpers.m

@@ -86,6 +86,27 @@ NSDictionary<NSString *, NSNumber *> *fb_availableButtonNames(void) {
 }
 #endif
 
+#if TARGET_OS_WATCH
+// Raw values from XCUIDeviceHandGesture (XCUIAutomation/XCUIDeviceHandGesture.h): doubleTap = 1, flick = 2.
+// Referenced by raw integer rather than the enum constant, and invoked via NSInvocation in
+// fb_performHandGesture:error: below, since that enum/selector was only added to the SDK in Xcode 16.3
+// (flick specifically needs watchOS 12.0/26 - see the @available check below). This way the code compiles
+// against any Xcode version; unsupported gestures/selectors are only rejected at runtime.
+NSDictionary<NSString *, NSNumber *> *fb_availableHandGestureNames(void) {
+  static dispatch_once_t onceToken;
+  static NSDictionary *result;
+  dispatch_once(&onceToken, ^{
+    NSMutableDictionary *gestures = [NSMutableDictionary dictionary];
+    gestures[@"doubletap"] = @(1);
+    if (@available(watchOS 12.0, *)) {
+      gestures[@"flick"] = @(2);
+    }
+    result = [gestures copy];
+  });
+  return result;
+}
+#endif // TARGET_OS_WATCH
+
 @implementation XCUIDevice (FBHelpers)
 
 static bool fb_isLocked;
@@ -386,6 +407,57 @@ static bool fb_isLocked;
   : nil;
 }
 
+#if TARGET_OS_WATCH
+- (BOOL)fb_rotateDigitalCrown:(double)delta velocity:(nullable NSNumber *)velocity error:(NSError **)error
+{
+  SEL selector = nil == velocity
+    ? NSSelectorFromString(@"rotateDigitalCrownByDelta:")
+    : NSSelectorFromString(@"rotateDigitalCrownByDelta:withVelocity:");
+  if (nil == selector || ![self respondsToSelector:selector]) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"Digital Crown rotation is not supported by the current Xcode SDK/OS combination"]
+            buildError:error];
+  }
+  NSMethodSignature *signature = [self methodSignatureForSelector:selector];
+  NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:signature];
+  [invocation setSelector:selector];
+  [invocation setTarget:self];
+  [invocation setArgument:&delta atIndex:2];
+  if (velocity) {
+    double velocityValue = velocity.doubleValue;
+    [invocation setArgument:&velocityValue atIndex:3];
+  }
+  [invocation invoke];
+  return YES;
+}
+
+- (BOOL)fb_performHandGesture:(NSString *)gestureName error:(NSError **)error
+{
+  NSDictionary<NSString *, NSNumber *> *availableGestures = fb_availableHandGestureNames();
+  NSNumber *gestureValue = availableGestures[gestureName.lowercaseString];
+  if (!gestureValue) {
+    NSArray *sortedKeys = [availableGestures.allKeys sortedArrayUsingSelector:@selector(compare:)];
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"The hand gesture '%@' is not supported. The device under test only supports the following hand gestures: %@", gestureName, sortedKeys]
+            buildError:error];
+  }
+  SEL selector = NSSelectorFromString(@"performHandGesture:");
+  if (nil == selector || ![self respondsToSelector:selector]) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"Hand gesture automation is not supported by the current Xcode SDK/OS combination"]
+            buildError:error];
+  }
+  NSMethodSignature *signature = [self methodSignatureForSelector:selector];
+  NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:signature];
+  [invocation setSelector:selector];
+  [invocation setTarget:self];
+  NSInteger gestureRawValue = gestureValue.integerValue;
+  [invocation setArgument:&gestureRawValue atIndex:2];
+  [invocation invoke];
+  return YES;
+}
+#endif // TARGET_OS_WATCH
+
 #if !TARGET_OS_TV
 - (BOOL)fb_setSimulatedLocation:(CLLocation *)location error:(NSError **)error
 {

package/WebDriverAgentLib/Commands/FBCustomCommands.m

@@ -63,6 +63,10 @@
     [[FBRoute GET:@"/wda/batteryInfo"] respondWithTarget:self action:@selector(handleGetBatteryInfo:)],
 #endif
     [[FBRoute POST:@"/wda/pressButton"] respondWithTarget:self action:@selector(handlePressButtonCommand:)],
+#if TARGET_OS_WATCH
+    [[FBRoute POST:@"/wda/rotateDigitalCrown"] respondWithTarget:self action:@selector(handleRotateDigitalCrownCommand:)],
+    [[FBRoute POST:@"/wda/performHandGesture"] respondWithTarget:self action:@selector(handlePerformHandGestureCommand:)],
+#endif
     [[FBRoute POST:@"/wda/performAccessibilityAudit"] respondWithTarget:self action:@selector(handlePerformAccessibilityAudit:)],
     [[FBRoute POST:@"/wda/performIoHidEvent"] respondWithTarget:self action:@selector(handlePeformIOHIDEvent:)],
     [[FBRoute POST:@"/wda/expectNotification"] respondWithTarget:self action:@selector(handleExpectNotification:)],
@@ -295,6 +299,38 @@
   return FBResponseWithOK();
 }
 
+#if TARGET_OS_WATCH
++ (id<FBResponsePayload>)handleRotateDigitalCrownCommand:(FBRouteRequest *)request
+{
+  NSNumber *delta = request.arguments[@"delta"];
+  if (nil == delta) {
+    return FBResponseWithStatus([FBCommandStatus invalidArgumentErrorWithMessage:@"'delta' argument is mandatory"
+                                                                         traceback:nil]);
+  }
+  NSError *error;
+  if (![XCUIDevice.sharedDevice fb_rotateDigitalCrown:delta.doubleValue
+                                              velocity:request.arguments[@"velocity"]
+                                                 error:&error]) {
+    return FBResponseWithUnknownError(error);
+  }
+  return FBResponseWithOK();
+}
+
++ (id<FBResponsePayload>)handlePerformHandGestureCommand:(FBRouteRequest *)request
+{
+  NSString *gestureName = request.arguments[@"name"];
+  if (nil == gestureName) {
+    return FBResponseWithStatus([FBCommandStatus invalidArgumentErrorWithMessage:@"'name' argument is mandatory"
+                                                                         traceback:nil]);
+  }
+  NSError *error;
+  if (![XCUIDevice.sharedDevice fb_performHandGesture:gestureName error:&error]) {
+    return FBResponseWithUnknownError(error);
+  }
+  return FBResponseWithOK();
+}
+#endif
+
 + (id<FBResponsePayload>)handleActivateSiri:(FBRouteRequest *)request
 {
   NSError *error;

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentTests/IntegrationTests_watchOS/WDADeviceIntegrationTests.swift

@@ -47,4 +47,67 @@ final class WDADeviceIntegrationTests: WDAWatchIntegrationTestCase {
     let clearResponse = try client.delete("/session/\(sessionId!)/wda/simulatedLocation")
     XCTAssertEqual(clearResponse.statusCode, 200)
   }
+
+  /// rotateDigitalCrownByDelta:/performHandGesture: were only added to the SDK in Xcode 16.3 - WDA calls
+  /// them dynamically (NSInvocation) so it keeps building on older Xcode too, but they only actually work
+  /// when the toolchain that built this very test bundle (same build as the runner) is new enough. Checked
+  /// the same way WDA itself does, via responds(to:), rather than hardcoding an Xcode/OS version number here.
+  private var supportsDigitalCrownAndHandGesture: Bool {
+    XCUIDevice.shared.responds(to: Selector(("rotateDigitalCrownByDelta:")))
+  }
+
+  func testRotateDigitalCrown() throws {
+    let response = try client.post("/session/\(sessionId!)/wda/rotateDigitalCrown", body: [
+      "delta": 0.2,
+      "velocity": 1.0,
+    ])
+    XCTAssertEqual(response.statusCode, supportsDigitalCrownAndHandGesture ? 200 : 500)
+  }
+
+  func testRotateDigitalCrownDefaultVelocity() throws {
+    let response = try client.post("/session/\(sessionId!)/wda/rotateDigitalCrown", body: [
+      "delta": -0.2,
+    ])
+    XCTAssertEqual(response.statusCode, supportsDigitalCrownAndHandGesture ? 200 : 500)
+  }
+
+  func testRotateDigitalCrownMissingDelta() throws {
+    // Argument validation happens before the dynamic dispatch check, so this is always a 400.
+    let response = try client.post("/session/\(sessionId!)/wda/rotateDigitalCrown")
+    XCTAssertEqual(response.statusCode, 400)
+  }
+
+  func testPerformHandGestureDoubleTap() throws {
+    let response = try client.post("/session/\(sessionId!)/wda/performHandGesture", body: [
+      "name": "doubleTap",
+    ])
+    XCTAssertEqual(response.statusCode, supportsDigitalCrownAndHandGesture ? 200 : 500)
+  }
+
+  func testPerformHandGestureFlick() throws {
+    let response = try client.post("/session/\(sessionId!)/wda/performHandGesture", body: [
+      "name": "flick",
+    ])
+    // flick additionally needs watchOS 26+ (still internally versioned 12.0 pre-rename) on top of the
+    // Xcode 16.3+ toolchain floor - below that OS version it isn't even advertised as a supported name,
+    // so the server rejects it the same way it would reject any other unknown gesture name.
+    if #available(watchOS 12.0, *), supportsDigitalCrownAndHandGesture {
+      XCTAssertEqual(response.statusCode, 200)
+    } else {
+      XCTAssertEqual(response.statusCode, 500)
+    }
+  }
+
+  func testPerformHandGestureUnsupportedName() throws {
+    // Not a real gesture name in any environment, so always rejected regardless of toolchain/OS version.
+    let response = try client.post("/session/\(sessionId!)/wda/performHandGesture", body: [
+      "name": "clench",
+    ])
+    XCTAssertEqual(response.statusCode, 500)
+  }
+
+  func testPerformHandGestureMissingName() throws {
+    let response = try client.post("/session/\(sessionId!)/wda/performHandGesture")
+    XCTAssertEqual(response.statusCode, 400)
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-webdriveragent",
-  "version": "16.3.0",
+  "version": "16.4.0",
   "description": "Package bundling WebDriverAgent",
   "keywords": [
     "Appium",