[🚀 Feature]: Consolidate Actions class features

[titusfortner]

Dependencies

• [dotnet] Allow setting a different pointer, keyboard, or wheel on input device #11513
• [java] [dotnet] Add move to location method to Actions #11509

Feature and motivation

Did a comparative analysis of Actions class functionality between languages:
https://www.selenium.dev/documentation/webdriver/actions_api/

Differences of note

• Python & Ruby can change default durations for scrolling & movement; Java & .NET can't
• Python & Ruby have a "move to Location" method, Java & .NET don't
• I just added support for Python & Ruby to specify what button to click on click and hold, release and click methods; Java & .NET don't have this
• I added support for Java to & Ruby to set an "active" pointer (e.g. use a pen with Actions instead of needing ActionBuilder) Python & .NET can't do this
• Pointer Event Properties require the Action Builder approach in Java/Python/.NET;
• Java requires using Sequences instead of having a single ActionBuilder class like Python & .NET

Proposal 1: Allow setting default pointer in Python & .NET

This saves the step of needing to define the action and add to the input and then perform.
Note: this example is Python, I haven't looked to see how difficult in .NET

pen = ActionChains(driver)\
    .set_pointer(PointerInput(POINTER_PEN, "default pen"))\
    .move_to(element)\
    .perform()

Proposal 2: Move to Location method in Java & .NET

Adds one method to Actions class
Currently no option for moving based on Viewport origin, only Element origin
The parameter could be x, y integers or a single Coordinate/Point object instance

new Actions(driver)
        .moveToLocation(100, 200)
        .perform()

Proposal 3: Allow changing of default duration in Java & .NET (tracking in #12118)

Adds one constructor to Actions class
Appium wants a default of 50ms instead of 250ms
Putting it in Actions constructor is much lower impact than adding the parameter to each method
Discuss with Appium Devs First

new Actions(driver, Duration.ofMillis(50))
        .moveByOffset(13, 15)
        .perform();

Proposal 4: Provide a better way to perform action sequences in Java

The Collections.singletonList requirement just feels clunky and unintuitive to me.
It is extra overhead, and might be worth waiting to implement until after we do #10808 since that's where we're going to want to add multiple sequences.

instead of:

((RemoteWebDriver) driver).perform(Collections.singletonList(actions));

Wrap it with this:

new ActionsBuilder(driver)
  .addSequence(actions)
  .perform();

Proposal 5: Allow PointerEvents to be used with Actions Convenience class

This would be lots more methods, and since PointerEvents are mostly not useful at this point, I don't think we should do this one

PointerInput.PointerEventProperties eventProperties = PointerInput.eventProperties()
        .setTiltX(-72)
        .setTiltY(9)
        .setTwist(86);
new Actions(driver)
        .setActivePointer(PointerInput.Kind.PEN, "default pen")
        .moveToElement(pointerArea)
        .clickAndHold()
        .moveByOffset(2, 2, eventProperties)
        .release()
        .perform();

Proposal 6: Specify Buttons

Add parameter for which button to click to clickAndHold(), release(), and click() (Java & .NET)
Adds three methods to Actions class (which is a lot, so probably we shouldn't do this one)
Note: this one is probably not worth it because the use cases are not that interesting.

new Actions(driver)
  .click(PointerInput.MouseButton.BACK)
  .perform();

[alaahong]

Just wonder if how to draw a picture based on above features? e.g. drive the Pointer to do the signature on webpage.

[titusfortner]

@alaahong You could do it with a combination of "move by offset from viewport" (or element), "click and hold," "move by offset from current pointer location," and "release," though likely it's more trouble than it's worth?

https://www.selenium.dev/documentation/webdriver/actions_api/mouse/

[titusfortner]

It was agreed in TLC meeting from Aug 17 to implement proposals 1 & 2

[titusfortner]

Ok, finally closing out this issue since we've implemented everything we said we would.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.