Module appium.webdriver.webdriver

Classes

class WebDriver (command_executor='http://127.0.0.1:4444/wd/hub', desired_capabilities=None, browser_profile=None, proxy=None, keep_alive=True, direct_connection=False)

Returns appium driver search conext

Create a new driver that will issue commands using the wire protocol.

:Args: - command_executor - Either a string representing URL of the remote server or a custom remote_connection.RemoteConnection object. Defaults to 'http://127.0.0.1:4444/wd/hub'. - desired_capabilities - A dictionary of capabilities to request when starting the browser session. Required parameter. - browser_profile - A selenium.webdriver.firefox.firefox_profile.FirefoxProfile object. Only used if Firefox is requested. Optional. - proxy - A selenium.webdriver.common.proxy.Proxy object. The browser session will be started with given proxy settings, if possible. Optional. - keep_alive - Whether to configure remote_connection.RemoteConnection to use HTTP keep-alive. Defaults to False. - file_detector - Pass custom file detector object during instantiation. If None, then default LocalFileDetector() will be used. - options - instance of a driver options.Options class

Expand source code

class WebDriver(
    AppiumSearchContext,
    ActionHelpers,
    Activities,
    Applications,
    Clipboard,
    Context,
    Common,
    DeviceTime,
    Display,
    ExecuteDriver,
    ExecuteMobileCommand,
    Gsm,
    HardwareActions,
    ImagesComparison,
    IME,
    Keyboard,
    Location,
    LogEvent,
    Network,
    Performance,
    Power,
    RemoteFS,
    ScreenRecord,
    Session,
    Settings,
    Sms,
    SystemBars
):

    def __init__(self, command_executor: str = 'http://127.0.0.1:4444/wd/hub',
                 desired_capabilities: Optional[Dict] = None, browser_profile: str = None, proxy: str = None, keep_alive: bool = True, direct_connection: bool = False):

        super().__init__(
            AppiumConnection(command_executor, keep_alive=keep_alive),
            desired_capabilities,
            browser_profile,
            proxy
        )

        if hasattr(self, 'command_executor'):
            self._addCommands()

        self.error_handler = MobileErrorHandler()
        self._switch_to = MobileSwitchTo(self)

        if direct_connection:
            self._update_command_executor(keep_alive=keep_alive)

        # add new method to the `find_by_*` pantheon
        By.IOS_UIAUTOMATION = MobileBy.IOS_UIAUTOMATION
        By.IOS_PREDICATE = MobileBy.IOS_PREDICATE
        By.IOS_CLASS_CHAIN = MobileBy.IOS_CLASS_CHAIN
        By.ANDROID_UIAUTOMATOR = MobileBy.ANDROID_UIAUTOMATOR
        By.ANDROID_VIEWTAG = MobileBy.ANDROID_VIEWTAG
        By.WINDOWS_UI_AUTOMATION = MobileBy.WINDOWS_UI_AUTOMATION
        By.ACCESSIBILITY_ID = MobileBy.ACCESSIBILITY_ID
        By.IMAGE = MobileBy.IMAGE
        By.CUSTOM = MobileBy.CUSTOM

    def _update_command_executor(self, keep_alive: bool) -> None:
        """Update command executor following directConnect feature"""
        direct_protocol = 'directConnectProtocol'
        direct_host = 'directConnectHost'
        direct_port = 'directConnectPort'
        direct_path = 'directConnectPath'

        if (not {direct_protocol, direct_host, direct_port, direct_path}.issubset(set(self.capabilities))):
            message = 'Direct connect capabilities from server were:\n'
            for key in [direct_protocol, direct_host, direct_port, direct_path]:
                message += '{}: \'{}\'\n'.format(key, self.capabilities.get(key, ''))
            logger.warning(message)
            return

        protocol = self.capabilities[direct_protocol]
        hostname = self.capabilities[direct_host]
        port = self.capabilities[direct_port]
        path = self.capabilities[direct_path]
        executor = f'{protocol}://{hostname}:{port}{path}'

        logger.info('Updated request endpoint to %s', executor)
        # Override command executor
        self.command_executor = RemoteConnection(executor, keep_alive=keep_alive)
        self._addCommands()

    def start_session(self, capabilities: Dict, browser_profile: Optional[str] = None) -> None:
        """Creates a new session with the desired capabilities.

        Override for Appium

        Args:
            automation_name: The name of automation engine to use.
            platform_name: The name of target platform.
            platform_version: The kind of mobile device or emulator to use
            app: The absolute local path or remote http URL to an .ipa or .apk file, or a .zip containing one of these.

        Read https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md for more details.
        """
        if not isinstance(capabilities, dict):
            raise InvalidArgumentException('Capabilities must be a dictionary')
        if browser_profile:
            if 'moz:firefoxOptions' in capabilities:
                # encoded is defined in selenium's original codes
                capabilities['moz:firefoxOptions']['profile'] = browser_profile.encoded  # type: ignore
            else:
                # encoded is defined in selenium's original codes
                capabilities.update({'firefox_profile': browser_profile.encoded})  # type: ignore

        parameters = self._merge_capabilities(capabilities)

        response = self.execute(RemoteCommand.NEW_SESSION, parameters)
        if 'sessionId' not in response:
            response = response['value']
        self.session_id = response['sessionId']
        self.capabilities = response.get('value')

        # if capabilities is none we are probably speaking to
        # a W3C endpoint
        if self.capabilities is None:
            self.capabilities = response.get('capabilities')

        # Double check to see if we have a W3C Compliant browser
        self.w3c = response.get('status') is None
        self.command_executor.w3c = self.w3c

    def _merge_capabilities(self, capabilities: Dict) -> Dict[str, Any]:
        """Manage capabilities whether W3C format or MJSONWP format
        """
        if _FORCE_MJSONWP in capabilities:
            force_mjsonwp = capabilities[_FORCE_MJSONWP]
            del capabilities[_FORCE_MJSONWP]

            if force_mjsonwp != False:
                return {'desiredCapabilities': capabilities}

        w3c_caps = _make_w3c_caps(capabilities)
        return {'capabilities': w3c_caps, 'desiredCapabilities': capabilities}

    def find_element(self, by: str = By.ID, value: Union[str, Dict] = None) -> MobileWebElement:
        """'Private' method used by the find_element_by_* methods.

        Override for Appium

        Usage:
            Use the corresponding find_element_by_* instead of this.

        Returns:
            `appium.webdriver.webelement.WebElement`

        :rtype: `MobileWebElement`
        """
        # TODO: If we need, we should enable below converter for Web context
        # if self.w3c:
        #     if by == By.ID:
        #         by = By.CSS_SELECTOR
        #         value = '[id="%s"]' % value
        #     elif by == By.TAG_NAME:
        #         by = By.CSS_SELECTOR
        #     elif by == By.CLASS_NAME:
        #         by = By.CSS_SELECTOR
        #         value = ".%s" % value
        #     elif by == By.NAME:
        #         by = By.CSS_SELECTOR
        #         value = '[name="%s"]' % value

        return self.execute(RemoteCommand.FIND_ELEMENT, {
            'using': by,
            'value': value})['value']

    def find_elements(self, by: str = By.ID, value: Union[str, Dict]
                      = None) -> Union[List[MobileWebElement], List]:
        """'Private' method used by the find_elements_by_* methods.

        Override for Appium

        Usage:
            Use the corresponding find_elements_by_* instead of this.

        Returns:
            :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`

        :rtype: list of `MobileWebElement`
        """
        # TODO: If we need, we should enable below converter for Web context
        # if self.w3c:
        #     if by == By.ID:
        #         by = By.CSS_SELECTOR
        #         value = '[id="%s"]' % value
        #     elif by == By.TAG_NAME:
        #         by = By.CSS_SELECTOR
        #     elif by == By.CLASS_NAME:
        #         by = By.CSS_SELECTOR
        #         value = ".%s" % value
        #     elif by == By.NAME:
        #         by = By.CSS_SELECTOR
        #         value = '[name="%s"]' % value

        # Return empty list if driver returns null
        # See https://github.com/SeleniumHQ/selenium/issues/4555

        return self.execute(RemoteCommand.FIND_ELEMENTS, {
            'using': by,
            'value': value})['value'] or []

    def create_web_element(self, element_id: int, w3c: bool = False) -> MobileWebElement:
        """Creates a web element with the specified element_id.

        Overrides method in Selenium WebDriver in order to always give them
        Appium WebElement

        Args:
            element_id (int): The element id to create a web element
            w3c (bool): Whether the element is W3C or MJSONWP

        Returns:
            `MobileWebElement`
        """
        return MobileWebElement(self, element_id, w3c)

    def set_value(self, element: MobileWebElement, value: str) -> T:
        """Set the value on an element in the application.

        Args:
            element (`appium.webdriver.webelement.WebElement`: the element whose value will be set
            value (str): the value to set on the element

        Returns:
            `appium.webdriver.webdriver.WebDriver`
        """
        data = {
            'id': element.id,
            'value': [value],
        }
        self.execute(Command.SET_IMMEDIATE_VALUE, data)
        return self

    # pylint: disable=protected-access

    def _addCommands(self) -> None:
        # call the overridden command binders from all mixin classes except for
        # appium.webdriver.webdriver.WebDriver and its sub-classes
        # https://github.com/appium/python-client/issues/342
        for mixin_class in filter(lambda x: not issubclass(x, WebDriver), self.__class__.__mro__):
            if hasattr(mixin_class, self._addCommands.__name__):
                getattr(mixin_class, self._addCommands.__name__, None)(self)

        self.command_executor._commands[Command.TOUCH_ACTION] = \
            ('POST', '/session/$sessionId/touch/perform')
        self.command_executor._commands[Command.MULTI_ACTION] = \
            ('POST', '/session/$sessionId/touch/multi/perform')
        self.command_executor._commands[Command.SET_IMMEDIATE_VALUE] = \
            ('POST', '/session/$sessionId/appium/element/$id/value')

        # TODO Move commands for element to webelement
        self.command_executor._commands[Command.REPLACE_KEYS] = \
            ('POST', '/session/$sessionId/appium/element/$id/replace_value')
        self.command_executor._commands[Command.CLEAR] = \
            ('POST', '/session/$sessionId/element/$id/clear')
        self.command_executor._commands[Command.LOCATION_IN_VIEW] = \
            ('GET', '/session/$sessionId/element/$id/location_in_view')

Ancestors

• AppiumSearchContext
• ActionHelpers
• Activities
• Applications
• Clipboard
• Context
• Common
• DeviceTime
• Display
• ExecuteDriver
• ExecuteMobileCommand
• Gsm
• HardwareActions
• ImagesComparison
• IME
• Keyboard
• Location
• LogEvent
• Network
• Performance
• Power
• RemoteFS
• ScreenRecord
• Session
• Settings
• Sms
• SystemBars
• selenium.webdriver.remote.webdriver.WebDriver
• AndroidSearchContext
• CustomSearchContext
• iOSSearchContext
• MobileSearchContext
• WindowsSearchContext
• BaseSearchContext

Methods

def create_web_element(self, element_id, w3c=False)

Creates a web element with the specified element_id.

Overrides method in Selenium WebDriver in order to always give them Appium WebElement

Args

element_id : int

The element id to create a web element

w3c : bool

Whether the element is W3C or MJSONWP

Returns

MobileWebElement

Expand source code

def create_web_element(self, element_id: int, w3c: bool = False) -> MobileWebElement:
    """Creates a web element with the specified element_id.

    Overrides method in Selenium WebDriver in order to always give them
    Appium WebElement

    Args:
        element_id (int): The element id to create a web element
        w3c (bool): Whether the element is W3C or MJSONWP

    Returns:
        `MobileWebElement`
    """
    return MobileWebElement(self, element_id, w3c)

def find_element(self, by='id', value=None)

'Private' method used by the find_element_by_* methods.

Override for Appium

Usage

Use the corresponding find_element_by_* instead of this.

Returns

WebElement :rtype: MobileWebElement

Expand source code

def find_element(self, by: str = By.ID, value: Union[str, Dict] = None) -> MobileWebElement:
    """'Private' method used by the find_element_by_* methods.

    Override for Appium

    Usage:
        Use the corresponding find_element_by_* instead of this.

    Returns:
        `appium.webdriver.webelement.WebElement`

    :rtype: `MobileWebElement`
    """
    # TODO: If we need, we should enable below converter for Web context
    # if self.w3c:
    #     if by == By.ID:
    #         by = By.CSS_SELECTOR
    #         value = '[id="%s"]' % value
    #     elif by == By.TAG_NAME:
    #         by = By.CSS_SELECTOR
    #     elif by == By.CLASS_NAME:
    #         by = By.CSS_SELECTOR
    #         value = ".%s" % value
    #     elif by == By.NAME:
    #         by = By.CSS_SELECTOR
    #         value = '[name="%s"]' % value

    return self.execute(RemoteCommand.FIND_ELEMENT, {
        'using': by,
        'value': value})['value']

def find_elements(self, by='id', value=None)

'Private' method used by the find_elements_by_* methods.

Override for Appium

Usage

Use the corresponding find_elements_by_* instead of this.

Returns

:obj:list of :obj:WebElement :rtype: list of MobileWebElement

Expand source code

def find_elements(self, by: str = By.ID, value: Union[str, Dict]
                  = None) -> Union[List[MobileWebElement], List]:
    """'Private' method used by the find_elements_by_* methods.

    Override for Appium

    Usage:
        Use the corresponding find_elements_by_* instead of this.

    Returns:
        :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`

    :rtype: list of `MobileWebElement`
    """
    # TODO: If we need, we should enable below converter for Web context
    # if self.w3c:
    #     if by == By.ID:
    #         by = By.CSS_SELECTOR
    #         value = '[id="%s"]' % value
    #     elif by == By.TAG_NAME:
    #         by = By.CSS_SELECTOR
    #     elif by == By.CLASS_NAME:
    #         by = By.CSS_SELECTOR
    #         value = ".%s" % value
    #     elif by == By.NAME:
    #         by = By.CSS_SELECTOR
    #         value = '[name="%s"]' % value

    # Return empty list if driver returns null
    # See https://github.com/SeleniumHQ/selenium/issues/4555

    return self.execute(RemoteCommand.FIND_ELEMENTS, {
        'using': by,
        'value': value})['value'] or []

def set_value(self, element, value)

Set the value on an element in the application.

Args

element (WebElement: the element whose value will be set

value : str

the value to set on the element

Returns

WebDriver

Expand source code

def set_value(self, element: MobileWebElement, value: str) -> T:
    """Set the value on an element in the application.

    Args:
        element (`appium.webdriver.webelement.WebElement`: the element whose value will be set
        value (str): the value to set on the element

    Returns:
        `appium.webdriver.webdriver.WebDriver`
    """
    data = {
        'id': element.id,
        'value': [value],
    }
    self.execute(Command.SET_IMMEDIATE_VALUE, data)
    return self

def start_session(self, capabilities, browser_profile=None)

Creates a new session with the desired capabilities.

Override for Appium

Args

automation_name

The name of automation engine to use.

platform_name

The name of target platform.

platform_version

The kind of mobile device or emulator to use

app

The absolute local path or remote http URL to an .ipa or .apk file, or a .zip containing one of these.

Read https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md for more details.

Expand source code

def start_session(self, capabilities: Dict, browser_profile: Optional[str] = None) -> None:
    """Creates a new session with the desired capabilities.

    Override for Appium

    Args:
        automation_name: The name of automation engine to use.
        platform_name: The name of target platform.
        platform_version: The kind of mobile device or emulator to use
        app: The absolute local path or remote http URL to an .ipa or .apk file, or a .zip containing one of these.

    Read https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md for more details.
    """
    if not isinstance(capabilities, dict):
        raise InvalidArgumentException('Capabilities must be a dictionary')
    if browser_profile:
        if 'moz:firefoxOptions' in capabilities:
            # encoded is defined in selenium's original codes
            capabilities['moz:firefoxOptions']['profile'] = browser_profile.encoded  # type: ignore
        else:
            # encoded is defined in selenium's original codes
            capabilities.update({'firefox_profile': browser_profile.encoded})  # type: ignore

    parameters = self._merge_capabilities(capabilities)

    response = self.execute(RemoteCommand.NEW_SESSION, parameters)
    if 'sessionId' not in response:
        response = response['value']
    self.session_id = response['sessionId']
    self.capabilities = response.get('value')

    # if capabilities is none we are probably speaking to
    # a W3C endpoint
    if self.capabilities is None:
        self.capabilities = response.get('capabilities')

    # Double check to see if we have a W3C Compliant browser
    self.w3c = response.get('status') is None
    self.command_executor.w3c = self.w3c

Inherited members

• AppiumSearchContext:
  • find_element_by_accessibility_id
  • find_element_by_android_data_matcher
  • find_element_by_android_uiautomator
  • find_element_by_android_viewtag
  • find_element_by_custom
  • find_element_by_image
  • find_element_by_ios_class_chain
  • find_element_by_ios_predicate
  • find_element_by_ios_uiautomation
  • find_element_by_windows_uiautomation
  • find_elements_by_accessibility_id
  • find_elements_by_android_data_matcher
  • find_elements_by_android_uiautomator
  • find_elements_by_android_viewtag
  • find_elements_by_custom
  • find_elements_by_image
  • find_elements_by_ios_class_chain
  • find_elements_by_ios_predicate
  • find_elements_by_ios_uiautomation
  • find_elements_by_windows_uiautomation
• ActionHelpers:
  • drag_and_drop
  • flick
  • scroll
  • swipe
  • tap
• Activities:
  • current_activity
  • start_activity
  • wait_activity
• Applications:
  • activate_app
  • app_strings
  • background_app
  • close_app
  • install_app
  • is_app_installed
  • launch_app
  • query_app_state
  • remove_app
  • reset
  • terminate_app
• Clipboard:
  • get_clipboard
  • get_clipboard_text
  • set_clipboard
  • set_clipboard_text
• Context:
  • context
  • contexts
  • current_context
• Common:
  • current_package
  • end_test_coverage
  • open_notifications
• DeviceTime:
  • device_time
  • get_device_time
• Display:
  • get_display_density
• ExecuteDriver:
  • execute_driver
• ExecuteMobileCommand:
  • battery_info
  • press_button
• Gsm:
  • make_gsm_call
  • set_gsm_signal
  • set_gsm_voice
• HardwareActions:
  • finger_print
  • is_locked
  • lock
  • shake
  • toggle_touch_id_enrollment
  • touch_id
  • unlock
• ImagesComparison:
  • find_image_occurrence
  • get_images_similarity
  • match_images_features
• IME:
  • activate_ime_engine
  • active_ime_engine
  • available_ime_engines
  • deactivate_ime_engine
  • is_ime_active
• Keyboard:
  • hide_keyboard
  • is_keyboard_shown
  • keyevent
  • long_press_keycode
  • press_keycode
• Location:
  • location
  • set_location
  • toggle_location_services
• LogEvent:
  • get_events
  • log_event
• Network:
  • network_connection
  • set_network_connection
  • set_network_speed
  • toggle_wifi
• Performance:
  • get_performance_data
  • get_performance_data_types
• Power:
  • AC_OFF
  • AC_ON
  • set_power_ac
  • set_power_capacity
• RemoteFS:
  • pull_file
  • pull_folder
  • push_file
• ScreenRecord:
  • start_recording_screen
  • stop_recording_screen
• Session:
  • all_sessions
  • events
  • session
• Settings:
  • get_settings
  • update_settings
• Sms:
  • send_sms
• SystemBars:
  • get_system_bars