[Epic] Standardizing Position Parameters Across APIs

[asafkorem]

Motivation

In recent discussions, we have identified inconsistencies in how position parameters are utilized across various APIs (thanks to @d4vidi). Some use element-space coordinates while others use normalized points (values in the [0,1] range).

List of methods and inconsistencies

Method	Current Parameter Approach	Documentation Link
tap	Absolute points for all parameters	Link
longPress	Absolute points for all parameters	GitHub issue (WIP)
longPressAndDrag	Normalized points for all parameters	Link
swipe	Normalized points for all parameters (including offset)	Link
scroll	Normalized points starting points; absolute points for offset	Link
scrollTo	Normalized points for all parameters	Link
getAttributes	Android: pixels for all attributes	Link

This inconsistency is confusing and necessitates a reevaluation. Establishing a standard is not straightforward, as there are scenarios where an element might expand its size on different screens (using normalized coordinates), whereas other elements, such as child elements, maintain their absolute size and position (e.g., 15 points from the left).

Suggested Approach

To address this issue, we have decided to unify and standardize the position parameters across all our APIs. The main approach is to support both absolute (e.g., tap({x: number, y: number}) in points) and relative (e.g., tap({normalizedX: number, normalizedY: number}) or percentages in string format, such as tap({x: '53%', y: '50%'})). This flexibility will enable users to choose the most suitable method for their specific use case.

I generally prefer to allow both number and string with percentages on the {x: string | number, y: string | number} params (as suggested by @noomorph), since it can enable more flexibility and allow mixed types (e.g. {x: 150, y: '50%'}.

TODOs

Preview Give feedback

1. [Standard Position Params] Decide on a standardization + deprecation (if-needed) approach.
2. [Standard Position Params] Standardize tap position parameters.
3. [Standard Position Params] Standardize longPress position parameters.
4. [Standard Position Params] Standardize longPressAndDrag position parameters.
5. [Standard Position Params] Standardize swipe position parameters.
6. [Standard Position Params] Standardize scroll position parameters.
7. [Standard Position Params] Standardize scrollTo position parameters.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
If you believe the issue is still relevant, please test on the latest Detox and report back.

Thank you for your contributions!

For more information on bots in this repository, read this discussion.

[asafkorem]

not stale