Skip to content

Pinch#

PinchGestures #

Access pinch/zoom related gestures.

Source code in src/interaction/gesture/pinch.py 
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
class PinchGestures:
    """Access pinch/zoom related gestures."""

    def __init__(self, driver: WebDriver, platform: str) -> None:
        self._driver = driver
        self._platform = platform

    def open(
        self,
        element: WebElement,
        percent: float = 0.75,
        speed: float = 1.0,
    ) -> bool:
        """
        Performs a pinch-open (zoom in) gesture on the specified element.

        This function executes a pinch gesture that spreads two fingers apart, commonly used
        for zooming in on images, maps, or other content. The implementation differs
        between Android and iOS platforms.

        Args:
            element (WebElement): The target element to perform the pinch gesture on.
            percent (float, optional): The scale factor of the pinch as a percentage (0.0-1.0).
                Higher values create a larger pinch spread.
                Defaults to 0.75.
            speed (float, optional): The velocity of the pinch gesture as a percentage.
                For Android, this is multiplied by the device's DPI to calculate the final velocity.
                For iOS, this value is used directly.
                Defaults to 1.0 (100%).

        Returns:
            bool: True if the pinch gesture was successfully executed.

        Raises:
            ZoomError: If the pinch gesture fails to execute, wrapping the underlying
                platform-specific exception.

        """
        p = PinchParameters(element, percent, speed)
        try:
            return (
                self._pinch_open_android(p.element, p.percent, p.speed)
                if self._platform == "android"
                else self._pinch_open_ios(p.element, p.percent, p.speed)
            )
        except Exception as e:
            msg = f"Failed to perform pinch open: {str(e)}"
            logger.error(msg)
            raise ZoomError(msg) from e

    def _pinch_open_android(self, element: WebElement, percent: float, speed: float) -> bool:
        """Execute Android-specific pinch-open gesture."""
        dpi = self._driver.get_display_density()
        velocity = (2500 * dpi) * speed
        return self._driver.execute_script(
            "mobile: pinchOpenGesture",
            {
                "elementId": element,
                "percent": percent,
                "speed": velocity,
            },
        )

    def _pinch_open_ios(self, element: WebElement, percent: float, speed: float) -> bool:
        """Execute iOS-specific pinch gesture."""
        return self._driver.execute_script(
            "mobile: pinch",
            {
                "elementId": element,
                "scale": percent,
                "velocity": speed,
            },
        )

    def close(
        self,
        element: WebElement,
        percent: float = 0.75,
        speed: float = 1.0,
    ) -> bool:
        """
        Performs a pinch-close (zoom out) gesture on the specified element.

        This function executes a pinch gesture that pulls two fingers inward, commonly used
        for zooming out on images, maps, or other content. The implementation differs
        between Android and iOS platforms.

        Args:
            element (WebElement): The target element to perform the pinch gesture on.
            percent (float, optional): The scale factor of the pinch as a percentage (0.0-1.0).
                Higher values create a larger pinch pull.
                On iOS a value > 1 inverts the pinch gesture, therefore the value is * 2.
                Therefore the value must be greater than 0.51.
                Defaults to 0.75.
            speed (float, optional): The velocity of the pinch gesture as a percentage.
                For Android, this is multiplied by the device's DPI to calculate the final velocity.
                For iOS, this value is used directly.
                Defaults to 1.0.

        Returns:
            bool: True if the pinch gesture was successfully executed.

        Raises:
            ZoomError: If the pinch gesture fails to execute, wrapping the underlying
                platform-specific exception.

        """
        p = PinchParameters(element, percent, speed)
        try:
            return (
                self._pinch_close_android(p.element, p.percent, p.speed)
                if self._platform == "android"
                else self._pinch_close_ios(p.element, p.percent, p.speed)
            )
        except Exception as e:
            msg = f"Failed to perform pinch close: {str(e)}"
            logger.error(msg)
            raise ZoomError(msg) from e

    def _pinch_close_android(self, element: WebElement, percent: float, speed: float) -> bool:
        """Execute Android-specific pinch-close gesture."""
        dpi = self._driver.get_display_density()
        velocity = (2500 * dpi) * speed
        return self._driver.execute_script(
            "mobile: pinchCloseGesture",
            {
                "elementId": element,
                "percent": percent,
                "speed": velocity,
            },
        )

    def _pinch_close_ios(self, element: WebElement, percent: float, speed: float) -> bool:
        """Execute iOS-specific pinch gesture."""
        if not (0.51 < percent <= 1.0):
            msg = f"Percent must be > 0.51 and <= 1.0, got {percent}"
            raise ValueError(msg)

        scale = percent * 2

        return self._driver.execute_script(
            "mobile: pinch",
            {
                "elementId": element,
                "scale": scale,
                "velocity": speed,
            },
        )

close(element, percent=0.75, speed=1.0) #

Performs a pinch-close (zoom out) gesture on the specified element.

This function executes a pinch gesture that pulls two fingers inward, commonly used for zooming out on images, maps, or other content. The implementation differs between Android and iOS platforms.

Parameters:

Name Type Description Default
element WebElement

The target element to perform the pinch gesture on.

 required
percent float

The scale factor of the pinch as a percentage (0.0-1.0). Higher values create a larger pinch pull. On iOS a value > 1 inverts the pinch gesture, therefore the value is * 2. Therefore the value must be greater than 0.51. Defaults to 0.75.

 0.75
speed float

The velocity of the pinch gesture as a percentage. For Android, this is multiplied by the device's DPI to calculate the final velocity. For iOS, this value is used directly. Defaults to 1.0.

 1.0

Returns:

Name Type Description
bool bool

True if the pinch gesture was successfully executed.

Raises:

Type Description
ZoomError

If the pinch gesture fails to execute, wrapping the underlying platform-specific exception.
Source code in src/interaction/gesture/pinch.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def close(
    self,
    element: WebElement,
    percent: float = 0.75,
    speed: float = 1.0,
) -> bool:
    """
    Performs a pinch-close (zoom out) gesture on the specified element.

    This function executes a pinch gesture that pulls two fingers inward, commonly used
    for zooming out on images, maps, or other content. The implementation differs
    between Android and iOS platforms.

    Args:
        element (WebElement): The target element to perform the pinch gesture on.
        percent (float, optional): The scale factor of the pinch as a percentage (0.0-1.0).
            Higher values create a larger pinch pull.
            On iOS a value > 1 inverts the pinch gesture, therefore the value is * 2.
            Therefore the value must be greater than 0.51.
            Defaults to 0.75.
        speed (float, optional): The velocity of the pinch gesture as a percentage.
            For Android, this is multiplied by the device's DPI to calculate the final velocity.
            For iOS, this value is used directly.
            Defaults to 1.0.

    Returns:
        bool: True if the pinch gesture was successfully executed.

    Raises:
        ZoomError: If the pinch gesture fails to execute, wrapping the underlying
            platform-specific exception.

    """
    p = PinchParameters(element, percent, speed)
    try:
        return (
            self._pinch_close_android(p.element, p.percent, p.speed)
            if self._platform == "android"
            else self._pinch_close_ios(p.element, p.percent, p.speed)
        )
    except Exception as e:
        msg = f"Failed to perform pinch close: {str(e)}"
        logger.error(msg)
        raise ZoomError(msg) from e

open(element, percent=0.75, speed=1.0) #

Performs a pinch-open (zoom in) gesture on the specified element.

This function executes a pinch gesture that spreads two fingers apart, commonly used for zooming in on images, maps, or other content. The implementation differs between Android and iOS platforms.

Parameters:

Name Type Description Default
element WebElement

The target element to perform the pinch gesture on.

 required
percent float

The scale factor of the pinch as a percentage (0.0-1.0). Higher values create a larger pinch spread. Defaults to 0.75.

 0.75
speed float

The velocity of the pinch gesture as a percentage. For Android, this is multiplied by the device's DPI to calculate the final velocity. For iOS, this value is used directly. Defaults to 1.0 (100%).

 1.0

Returns:

Name Type Description
bool bool

True if the pinch gesture was successfully executed.

Raises:

Type Description
ZoomError

If the pinch gesture fails to execute, wrapping the underlying platform-specific exception.
Source code in src/interaction/gesture/pinch.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def open(
    self,
    element: WebElement,
    percent: float = 0.75,
    speed: float = 1.0,
) -> bool:
    """
    Performs a pinch-open (zoom in) gesture on the specified element.

    This function executes a pinch gesture that spreads two fingers apart, commonly used
    for zooming in on images, maps, or other content. The implementation differs
    between Android and iOS platforms.

    Args:
        element (WebElement): The target element to perform the pinch gesture on.
        percent (float, optional): The scale factor of the pinch as a percentage (0.0-1.0).
            Higher values create a larger pinch spread.
            Defaults to 0.75.
        speed (float, optional): The velocity of the pinch gesture as a percentage.
            For Android, this is multiplied by the device's DPI to calculate the final velocity.
            For iOS, this value is used directly.
            Defaults to 1.0 (100%).

    Returns:
        bool: True if the pinch gesture was successfully executed.

    Raises:
        ZoomError: If the pinch gesture fails to execute, wrapping the underlying
            platform-specific exception.

    """
    p = PinchParameters(element, percent, speed)
    try:
        return (
            self._pinch_open_android(p.element, p.percent, p.speed)
            if self._platform == "android"
            else self._pinch_open_ios(p.element, p.percent, p.speed)
        )
    except Exception as e:
        msg = f"Failed to perform pinch open: {str(e)}"
        logger.error(msg)
        raise ZoomError(msg) from e

PinchParameters dataclass #

Encapsulates the parameters needed to perform pinch gestures.

Source code in src/interaction/gesture/pinch.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@dataclass
class PinchParameters:
    """Encapsulates the parameters needed to perform pinch gestures."""

    element: WebElement
    _percent: float = field(default=0.75, repr=False)
    _speed: float = field(default=1.0, repr=False)

    @property
    def percent(self) -> float:
        """Get the scale factor for the pinch gesture."""
        return self._percent

    @percent.setter
    def percent(self, value: float) -> None:
        if not 0.0 <= value <= 1.0:
            msg = f"Percent must be between 0.0 and 1.0, got {value}"
            raise ValueError(msg)
        self._percent = value

    @property
    def speed(self) -> float:
        """Get the velocity factor for the pinch gesture."""
        return self._speed

    @speed.setter
    def speed(self, value: float) -> None:
        if not 0.0 <= value <= 10.0:
            msg = f"Speed must be between 0.0 and 10.0, got {value}"
            raise ValueError(msg)
        self._speed = value

    def __post_init__(self):
        self.percent = self._percent
        self.speed = self._speed

percent: float property writable #

Get the scale factor for the pinch gesture.

speed: float property writable #

Get the velocity factor for the pinch gesture.