appium-webdriveragent 16.12.1 → 16.12.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [16.12.2](https://github.com/appium/WebDriverAgent/compare/v16.12.1...v16.12.2) (2026-09-03)
+
+### Bug Fixes
+
+* allow pause action items to appear before any pointer movement ([#1246](https://github.com/appium/WebDriverAgent/issues/1246)) ([282478a](https://github.com/appium/WebDriverAgent/commit/282478a2e631501fd904b0675717123c779d9b84))
+
 ## [16.12.1](https://github.com/appium/WebDriverAgent/compare/v16.12.0...v16.12.1) (2026-09-01)
 
 ### Miscellaneous Chores

package/WebDriverAgentLib/Info.plist

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

package/WebDriverAgentLib/Utilities/FBW3CActionsSynthesizer.m

@@ -133,7 +133,8 @@ static NSString *const FB_KEY_ACTIONS = @"actions";
     }
     self.duration = durationObj.doubleValue;
     XCUICoordinate *position = [self positionWithError:error];
-    if (nil == position) {
+    // A pause may legally have no position yet (nil position, no error set)
+    if (nil == position && error && nil != *error) {
       return nil;
     }
     self.atPosition = position;
@@ -143,7 +144,7 @@ static NSString *const FB_KEY_ACTIONS = @"actions";
 
 - (nullable XCUICoordinate *)positionWithError:(NSError **)error
 {
-  if (nil == self.previousItem) {
+  if (nil == self.previousItem || nil == self.previousItem.atPosition) {
     NSString *errorDescription = [NSString stringWithFormat:@"The '%@' action item must be preceded by %@ item", self.actionItem, FB_ACTION_ITEM_TYPE_POINTER_MOVE];
     if (error) {
       *error = [[FBErrorBuilder.builder withDescription:errorDescription] build];
@@ -205,9 +206,19 @@ static NSString *const FB_KEY_ACTIONS = @"actions";
                                  currentItemIndex:(NSUInteger)currentItemIndex
                                             error:(NSError **)error
 {
-  if (nil != eventPath && currentItemIndex == 1) {
+  if (nil != eventPath && currentItemIndex >= 1) {
     FBW3CGestureItem *preceedingItem = [allItems objectAtIndex:currentItemIndex - 1];
-    if ([preceedingItem isKindOfClass:FBPointerMoveItem.class]) {
+    // Only skip creating a new touch if the preceding pointerMove is the one that
+    // implicitly opened this touch, i.e. nothing but (possibly zero-duration) pauses
+    // came before it. Pauses never create an event path themselves.
+    BOOL isPreceedingMoveTheFirstRealItem = YES;
+    for (NSInteger index = (NSInteger)currentItemIndex - 2; index >= 0; index--) {
+      if (![[allItems objectAtIndex:index] isKindOfClass:FBPointerPauseItem.class]) {
+        isPreceedingMoveTheFirstRealItem = NO;
+        break;
+      }
+    }
+    if ([preceedingItem isKindOfClass:FBPointerMoveItem.class] && isPreceedingMoveTheFirstRealItem) {
       return @[];
     }
   }
@@ -280,7 +291,7 @@ static NSString *const FB_KEY_ACTIONS = @"actions";
   }
   
   // origin == FB_ORIGIN_TYPE_POINTER
-  if (nil == self.previousItem) {
+  if (nil == self.previousItem || nil == self.previousItem.atPosition) {
     NSString *errorDescription = [NSString stringWithFormat:@"There is no previous item for '%@' action item, however %@ is set to '%@'", self.actionItem, FB_ACTION_ITEM_KEY_ORIGIN, FB_ORIGIN_TYPE_POINTER];
     if (error) {
       *error = [[FBErrorBuilder.builder withDescription:errorDescription] build];
@@ -320,6 +331,13 @@ static NSString *const FB_KEY_ACTIONS = @"actions";
   return FB_ACTION_ITEM_TYPE_PAUSE;
 }
 
+- (nullable XCUICoordinate *)positionWithError:(NSError **)error
+{
+  // A pause has no position of its own; proxy whatever real move preceded
+  // it, or nil (not a fabricated point) if none has run yet
+  return self.previousItem.atPosition;
+}
+
 - (NSArray<XCPointerEventPath *> *)addToEventPath:(XCPointerEventPath *)eventPath
                                          allItems:(NSArray *)allItems
                                  currentItemIndex:(NSUInteger)currentItemIndex

package/WebDriverAgentTests/IntegrationTests/FBW3CMultiTouchActionsIntegrationTests.m

@@ -120,5 +120,40 @@
   [self verifyGesture:gesture orientation:UIDeviceOrientationPortrait];
 }
 
+- (void)testTwoFingersTapWithLeadingZeroDurationPause
+{
+  // Selenium clients pad shorter action sequences with a zero-duration pause
+  // so that all pointers/devices end up with the same number of ticks
+  XCUIElement *element = self.testedApplication.buttons[FBShowAlertButtonName];
+  NSArray<NSDictionary<NSString *, id> *> *gesture =
+  @[
+    @{
+      @"type": @"pointer",
+      @"id": @"finger1",
+      @"parameters": @{@"pointerType": @"touch"},
+      @"actions": @[
+          @{@"type": @"pointerMove", @"duration": @0, @"origin": element, @"x": @0, @"y": @0},
+          @{@"type": @"pointerDown"},
+          @{@"type": @"pause", @"duration": @100},
+          @{@"type": @"pointerUp"},
+          ],
+      },
+    @{
+      @"type": @"pointer",
+      @"id": @"finger2",
+      @"parameters": @{@"pointerType": @"touch"},
+      @"actions": @[
+          @{@"type": @"pause", @"duration": @0},
+          @{@"type": @"pointerMove", @"duration": @0, @"origin": element, @"x": @0, @"y": @0},
+          @{@"type": @"pointerDown"},
+          @{@"type": @"pause", @"duration": @100},
+          @{@"type": @"pointerUp"},
+          ],
+      },
+    ];
+
+  [self verifyGesture:gesture orientation:UIDeviceOrientationPortrait];
+}
+
 @end
 

package/WebDriverAgentTests/IntegrationTests/FBW3CTouchActionsIntegrationTests.m

@@ -17,6 +17,10 @@
 #import "XCUIDevice+FBRotation.h"
 #import "FBRunLoopSpinner.h"
 #import "FBXCodeCompatibility.h"
+#import "FBW3CActionsSynthesizer.h"
+#import "XCSynthesizedEventRecord.h"
+#import "XCPointerEventPath.h"
+#import "XCPointerEvent.h"
 
 @interface FBW3CTouchActionsIntegrationTestsPart1 : FBIntegrationTestCase
 @end
@@ -185,14 +189,13 @@
         },
       ],
     
-    // Chain element where action items start with an incorrect item
+    // Chain element where pointerMove action item does not contain coordinates
     @[@{
         @"type": @"pointer",
         @"id": @"finger1",
         @"parameters": @{@"pointerType": @"touch"},
         @"actions": @[
-            @{@"type": @"pause", @"duration": @100},
-            @{@"type": @"pointerMove", @"duration": @0, @"x": @1, @"y": @1},
+            @{@"type": @"pointerMove", @"duration": @0},
             @{@"type": @"pointerDown"},
             @{@"type": @"pause", @"duration": @100},
             @{@"type": @"pointerUp"},
@@ -200,13 +203,13 @@
         },
       ],
     
-    // Chain element where pointerMove action item does not contain coordinates
+    // Chain element where pointerMove action item cannot use coordinates of the previous item
     @[@{
         @"type": @"pointer",
         @"id": @"finger1",
         @"parameters": @{@"pointerType": @"touch"},
         @"actions": @[
-            @{@"type": @"pointerMove", @"duration": @0},
+            @{@"type": @"pointerMove", @"duration": @0, @"origin": @"pointer"},
             @{@"type": @"pointerDown"},
             @{@"type": @"pause", @"duration": @100},
             @{@"type": @"pointerUp"},
@@ -214,34 +217,51 @@
         },
       ],
     
-    // Chain element where pointerMove action item cannot use coordinates of the previous item
+    // Chain element where action items contains negative duration
     @[@{
         @"type": @"pointer",
         @"id": @"finger1",
         @"parameters": @{@"pointerType": @"touch"},
         @"actions": @[
-            @{@"type": @"pointerMove", @"duration": @0, @"origin": @"pointer"},
+            @{@"type": @"pointerMove", @"duration": @0, @"x": @1, @"y": @1},
             @{@"type": @"pointerDown"},
-            @{@"type": @"pause", @"duration": @100},
+            @{@"type": @"pause", @"duration": @-100},
             @{@"type": @"pointerUp"},
             ],
         },
       ],
     
-    // Chain element where action items contains negative duration
+    // Chain element where a leading pause is followed directly by pointerDown,
+    // with no real pointerMove ever establishing a position
     @[@{
         @"type": @"pointer",
         @"id": @"finger1",
         @"parameters": @{@"pointerType": @"touch"},
         @"actions": @[
-            @{@"type": @"pointerMove", @"duration": @0, @"x": @1, @"y": @1},
+            @{@"type": @"pause", @"duration": @0},
             @{@"type": @"pointerDown"},
-            @{@"type": @"pause", @"duration": @-100},
+            @{@"type": @"pause", @"duration": @100},
             @{@"type": @"pointerUp"},
             ],
         },
       ],
-    
+
+    // Chain element where a leading pause is followed directly by a relative
+    // pointerMove, with no real preceding position to be relative to
+    @[@{
+        @"type": @"pointer",
+        @"id": @"finger1",
+        @"parameters": @{@"pointerType": @"touch"},
+        @"actions": @[
+            @{@"type": @"pause", @"duration": @0},
+            @{@"type": @"pointerMove", @"duration": @0, @"origin": @"pointer"},
+            @{@"type": @"pointerDown"},
+            @{@"type": @"pause", @"duration": @100},
+            @{@"type": @"pointerUp"},
+            ],
+        },
+      ],
+
     // Chain element where action items start with an incorrect one, because the correct one is canceled
     @[@{
         @"type": @"pointer",
@@ -299,6 +319,69 @@
   [self verifyGesture:gesture orientation:UIDeviceOrientationPortrait];
 }
 
+- (void)testLeadingZeroDurationPauseDoesNotAddExtraTouch
+{
+  // A leading pause must not defeat the down-after-move dedup logic in
+  // FBPointerDownItem and make WDA synthesize a second, separate touch-down
+  // for the same finger. Inspect the actual synthesized XCTest event stream
+  // (without dispatching it) rather than only checking the gesture's visible
+  // side effect, since a duplicate touch at the same point may still produce
+  // the same visible outcome.
+  XCUIElement *element = self.testedApplication.buttons[FBShowAlertButtonName];
+  NSDictionary<NSString *, id> *(^sequenceWithLeadingPause)(BOOL) = ^NSDictionary<NSString *, id> *(BOOL withLeadingPause) {
+    NSMutableArray<NSDictionary<NSString *, id> *> *actions = [NSMutableArray array];
+    if (withLeadingPause) {
+      [actions addObject:@{@"type": @"pause", @"duration": @0}];
+    }
+    [actions addObjectsFromArray:@[
+      @{@"type": @"pointerMove", @"duration": @0, @"origin": element, @"x": @0, @"y": @0},
+      @{@"type": @"pointerDown"},
+      @{@"type": @"pause", @"duration": @100},
+      @{@"type": @"pointerUp"},
+      ]];
+    return @{
+      @"type": @"pointer",
+      @"id": @"finger1",
+      @"parameters": @{@"pointerType": @"touch"},
+      @"actions": actions.copy,
+      };
+  };
+
+  NSError *error;
+  FBW3CActionsSynthesizer *baselineSynthesizer =
+  [[FBW3CActionsSynthesizer alloc] initWithActions:@[sequenceWithLeadingPause(NO)]
+                                     forApplication:self.testedApplication
+                                       elementCache:nil
+                                              error:&error];
+  XCTAssertNotNil(baselineSynthesizer);
+  XCSynthesizedEventRecord *baselineRecord = [baselineSynthesizer synthesizeWithError:&error];
+  XCTAssertNotNil(baselineRecord, @"%@", error);
+
+  FBW3CActionsSynthesizer *pausedSynthesizer =
+  [[FBW3CActionsSynthesizer alloc] initWithActions:@[sequenceWithLeadingPause(YES)]
+                                     forApplication:self.testedApplication
+                                       elementCache:nil
+                                              error:&error];
+  XCTAssertNotNil(pausedSynthesizer);
+  XCSynthesizedEventRecord *pausedRecord = [pausedSynthesizer synthesizeWithError:&error];
+  XCTAssertNotNil(pausedRecord, @"%@", error);
+
+  XCTAssertEqual(baselineRecord.eventPaths.count, (NSUInteger)1);
+  XCTAssertEqual(pausedRecord.eventPaths.count, baselineRecord.eventPaths.count);
+
+  XCPointerEventPath *baselinePath = baselineRecord.eventPaths.firstObject;
+  XCPointerEventPath *pausedPath = pausedRecord.eventPaths.firstObject;
+  XCTAssertEqual(pausedPath.pointerEvents.count, baselinePath.pointerEvents.count);
+  for (NSUInteger i = 0; i < baselinePath.pointerEvents.count; i++) {
+    XCPointerEvent *baselineEvent = baselinePath.pointerEvents[i];
+    XCPointerEvent *pausedEvent = pausedPath.pointerEvents[i];
+    XCTAssertEqual(pausedEvent.eventType, baselineEvent.eventType);
+    XCTAssertEqualWithAccuracy(pausedEvent.offset, baselineEvent.offset, 0.001);
+    XCTAssertEqualWithAccuracy(pausedEvent.coordinate.x, baselineEvent.coordinate.x, 0.001);
+    XCTAssertEqualWithAccuracy(pausedEvent.coordinate.y, baselineEvent.coordinate.y, 0.001);
+  }
+}
+
 - (void)testDoubleTap
 {
   NSArray<NSDictionary<NSString *, id> *> *gesture =

package/package.json

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