0
# WebDriver Core
1
2
Core WebDriver functionality providing the foundation for all mobile automation operations. The WebDriver class extends Selenium's Remote WebDriver with Appium-specific capabilities and mobile element handling.
3
4
## Capabilities
5
6
### WebDriver Class
7
8
Main WebDriver class that extends Selenium's Remote WebDriver with Appium-specific functionality and extension support.
9
10
```python {.api}
11
class WebDriver:
12
def __init__(self, command_executor: str, extensions: list = None,
13
options = None, client_config = None):
14
"""
15
Initialize WebDriver with Appium capabilities.
16
17
Args:
18
command_executor (str): URL of Appium server endpoint
19
extensions (list, optional): List of extension classes to add
20
options: Platform-specific options object (UiAutomator2Options, XCUITestOptions, etc.)
21
client_config: Client configuration for connection settings
22
"""
23
24
def start_session(self, capabilities: dict, browser_profile = None):
25
"""
26
Start a new WebDriver session with specified capabilities.
27
28
Args:
29
capabilities (dict): Session capabilities dictionary
30
browser_profile: Browser profile configuration (optional)
31
"""
32
33
def get_status(self) -> dict:
34
"""
35
Get the status of the Appium server.
36
37
Returns:
38
dict: Server status information including build info and supported platforms
39
"""
40
41
def create_web_element(self, element_id: str):
42
"""
43
Create a MobileWebElement from element ID.
44
45
Args:
46
element_id (str): Element identifier returned by find operations
47
48
Returns:
49
WebElement: Mobile-enabled WebElement instance
50
"""
51
52
def delete_extensions(self):
53
"""Remove all added extensions from the WebDriver instance."""
54
55
def assert_extension_exists(self, ext_name: str):
56
"""
57
Verify that a named extension is available.
58
59
Args:
60
ext_name (str): Name of extension to verify
61
62
Raises:
63
Exception: If extension is not available
64
"""
65
66
def mark_extension_absence(self, ext_name: str):
67
"""
68
Mark an extension as absent to avoid repeated checks.
69
70
Args:
71
ext_name (str): Name of extension to mark as absent
72
"""
73
74
@property
75
def orientation(self) -> str:
76
"""
77
Get or set device orientation.
78
79
Returns:
80
str: Current orientation ('LANDSCAPE' or 'PORTRAIT')
81
"""
82
83
@orientation.setter
84
def orientation(self, value: str):
85
"""
86
Set device orientation.
87
88
Args:
89
value (str): Orientation to set ('LANDSCAPE' or 'PORTRAIT')
90
"""
91
92
@property
93
def switch_to(self):
94
"""
95
Access mobile-specific switching functionality.
96
97
Returns:
98
MobileSwitchTo: Switch context manager for mobile contexts
99
"""
100
```
101
102
### WebElement Class
103
104
Mobile WebElement extending Selenium's WebElement with mobile-specific methods and enhanced functionality.
105
106
```python {.api}
107
class WebElement:
108
def get_attribute(self, name: str):
109
"""
110
Get element attribute value.
111
112
Args:
113
name (str): Attribute name
114
115
Returns:
116
str or dict: Attribute value, returns dict for complex attributes
117
"""
118
119
def is_displayed(self) -> bool:
120
"""
121
Check if element is visible on screen.
122
123
Returns:
124
bool: True if element is displayed, False otherwise
125
"""
126
127
def clear(self):
128
"""
129
Clear element text content.
130
131
Returns:
132
WebElement: Self for method chaining
133
"""
134
135
def send_keys(self, *value):
136
"""
137
Send text input to element.
138
139
Args:
140
*value: Text values to send
141
142
Returns:
143
WebElement: Self for method chaining
144
"""
145
146
@property
147
def location_in_view(self) -> dict:
148
"""
149
Get element location relative to the current view.
150
151
Returns:
152
dict: Location coordinates {'x': int, 'y': int}
153
"""
154
```
155
156
### Extension Base Class
157
158
Base class for creating custom WebDriver extensions with command registration and execution.
159
160
```python {.api}
161
class ExtensionBase:
162
def method_name(self) -> str:
163
"""
164
Abstract method to return the extension's method name.
165
166
Returns:
167
str: Method name that will be added to WebDriver
168
"""
169
170
def add_command(self) -> dict:
171
"""
172
Abstract method to define HTTP method and URL for the extension.
173
174
Returns:
175
dict: Command definition with 'method' and 'url' keys
176
"""
177
178
def execute(self, parameters: dict = None):
179
"""
180
Execute the extension command with given parameters.
181
182
Args:
183
parameters (dict, optional): Command parameters
184
185
Returns:
186
Any: Command execution result
187
"""
188
```
189
190
### Exception Classes
191
192
Common exceptions that may be raised during WebDriver operations.
193
194
```python {.api}
195
class NoSuchContextException(Exception):
196
"""Raised when attempting to switch to a context that doesn't exist."""
197
pass
198
199
# Standard Selenium exceptions also apply
200
from selenium.common.exceptions import (
201
NoSuchElementException,
202
TimeoutException,
203
WebDriverException,
204
InvalidArgumentException,
205
ElementNotInteractableException
206
)
207
```
208
209
## Usage Examples
210
211
### Basic WebDriver Setup
212
213
```python
214
from appium import webdriver
215
from appium.options.android import UiAutomator2Options
216
217
# Configure options
218
options = UiAutomator2Options()
219
options.platform_name = "Android"
220
options.device_name = "Android Emulator"
221
options.app = "/path/to/app.apk"
222
223
# Start session
224
driver = webdriver.Remote("http://localhost:4723", options=options)
225
226
# Verify server status
227
status = driver.get_status()
228
print(f"Appium version: {status['build']['version']}")
229
230
# Find and interact with elements
231
element = driver.find_element("id", "button1")
232
element.click()
233
234
# Clean up
235
driver.quit()
236
```
237
238
### Creating Custom Extensions
239
240
```python
241
from appium.webdriver.webdriver import ExtensionBase
242
243
class CustomExtension(ExtensionBase):
244
def method_name(self):
245
return "custom_action"
246
247
def add_command(self):
248
return {
249
'method': 'POST',
250
'url': '/session/$sessionId/custom/action'
251
}
252
253
def execute(self, parameters=None):
254
return self.driver.execute('custom_action', parameters)
255
256
# Add extension to WebDriver
257
driver = webdriver.Remote("http://localhost:4723", options=options,
258
extensions=[CustomExtension])
259
260
# Use custom extension
261
result = driver.custom_action({'param': 'value'})
262
```
263
264
## Types
265
266
```python {.api}
267
from typing import Union, List, Dict
268
269
# Connection and configuration types
270
ClientConfig = Union[dict, object]
271
Capabilities = dict
272
CommandExecutor = str
273
ExtensionList = List[ExtensionBase]
274
275
# Element and location types
276
ElementId = str
277
Coordinates = Dict[str, int]
278
AttributeValue = Union[str, dict, None]
279
280
# Orientation constants
281
DeviceOrientation = str # 'LANDSCAPE' or 'PORTRAIT'
282
283
# Client configuration
284
AppiumClientConfig = object # Configuration for connection settings
285
286
# Switch context types
287
MobileSwitchTo = object # Mobile context switching manager
288
```