Appium-Python-Client


NameAppium-Python-Client JSON
Version 2.7.0 PyPI version JSON
download
home_pagehttp://appium.io/
SummaryPython client for Appium
upload_time2022-09-23 06:47:28
maintainerKazuaki Matsuo, Mykola Mokhnach, Mori Atsushi
docs_urlNone
authorIsaac Murchie
requires_python
licenseApache 2.0
keywords appium selenium selenium 4 python client mobile automation
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Appium Python Client

[![PyPI version](https://badge.fury.io/py/Appium-Python-Client.svg)](https://badge.fury.io/py/Appium-Python-Client)
[![Downloads](https://pepy.tech/badge/appium-python-client)](https://pepy.tech/project/appium-python-client)

[![Build Status](https://dev.azure.com/AppiumCI/Appium%20CI/_apis/build/status/appium.python-client?branchName=master)](https://dev.azure.com/AppiumCI/Appium%20CI/_build/latest?definitionId=56&branchName=master)

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

An extension library for adding [WebDriver Protocol](https://www.w3.org/TR/webdriver/) and Appium commands to the Selenium Python language binding for use with the mobile testing framework [Appium](https://appium.io).

## Notice

Since **v1.0.0**, only Python 3.7+ is supported.

Since **v2.0.0**, the base selenium client version is v4.
The version only works in W3C WebDriver protocol format.
If you would like to use the old protocol (MJSONWP), please use v1 Appium Python client.

### Quick migration guide from v1 to v2
- Enhancement
    - Updated base Selenium Python binding version to v4
        - Removed `forceMjsonwp` since Selenium v4 and Appium Python client v2 expect only W3C WebDriver protocol
    - Methods `ActionHelpers#scroll`, `ActionHelpers#drag_and_drop`, `ActionHelpers#tap`, `ActionHelpers#swipe` and `ActionHelpers#flick` now call W3C actions as its backend
        - Please check each behavior. Their behaviors could slightly differ.
    - Added `strict_ssl` to relax SSL error such as self-signed ones
- Deprecated
    - `MultiAction` and `TouchAction` are deprecated. Please use W3C WebDriver actions.
        - e.g.
            - [appium/webdriver/extensions/action_helpers.py](appium/webdriver/extensions/action_helpers.py)
            - https://www.selenium.dev/documentation/support_packages/mouse_and_keyboard_actions_in_detail/
            - https://www.youtube.com/watch?v=oAJ7jwMNFVU
            - https://appiumpro.com/editions/30-ios-specific-touch-action-methods
            - https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api
    - `launch_app`, `close_app` and `reset` are deprecated. Please read [issues#15807](https://github.com/appium/appium/issues/15807) for more details

#### MultiAction/TouchAction to W3C actions

On UIA2, some elements can be handled with `touch` pointer action insead of the default `mouse` pointer action in the Selenium Python cleint.
For example, the below action builder is to replace the default one with the `touch` pointer action.

```python
from selenium.webdriver.common.actions import interaction
from selenium.webdriver.common.actions.action_builder import ActionBuilder

actions = ActionChains(driver)
# override as 'touch' pointer action
actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "touch"))
actions.w3c_actions.pointer_action.move_to_location(start_x, start_y)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pause(2)
actions.w3c_actions.pointer_action.move_to_location(end_x, end_y)
actions.w3c_actions.pointer_action.release()
actions.perform()
```

## Getting the Appium Python client

There are three ways to install and use the Appium Python client.

1. Install from [PyPi](https://pypi.org), as
['Appium-Python-Client'](https://pypi.org/project/Appium-Python-Client/).

    ```shell
    pip install Appium-Python-Client
    ```

    You can see the history from [here](https://pypi.org/project/Appium-Python-Client/#history)

2. Install from source, via [PyPi](https://pypi.org). From ['Appium-Python-Client'](https://pypi.org/project/Appium-Python-Client/),
download and unarchive the source tarball (Appium-Python-Client-X.X.tar.gz).

    ```shell
    tar -xvf Appium-Python-Client-X.X.tar.gz
    cd Appium-Python-Client-X.X
    python setup.py install
    ```

3. Install from source via [GitHub](https://github.com/appium/python-client).

    ```shell
    git clone git@github.com:appium/python-client.git
    cd python-client
    python setup.py install
    ```

## Usage

The Appium Python Client is fully compliant with the WebDriver Protocol
including several helpers to make mobile testing in Python easier.

To use the new functionality now, and to use the superset of functions, instead of
including the Selenium `webdriver` module in your test code, use that from
Appium instead.

```python
from appium import webdriver
```

From there much of your test code will work with no change.

As a base for the following code examples, the following sets up the [UnitTest](https://docs.python.org/3/library/unittest.html)
environment:

```python
# Android environment
from appium import webdriver
# Options are only available since client version 2.3.0
# If you use an older client then switch to desired_capabilities
# instead: https://github.com/appium/python-client/pull/720
from appium.options.android import UiAutomator2Options
from appium.webdriver.common.appiumby import AppiumBy

options = UiAutomator2Options()
options.platformVersion = '10'
options.udid = '123456789ABC'
options.app = PATH('../../../apps/test-app.apk')
# Appium1 points to http://127.0.0.1:4723/wd/hub by default 
self.driver = webdriver.Remote('http://127.0.0.1:4723', options=options)
el = self.driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='item')
el.click()
```

```python
# iOS environment
from appium import webdriver
# Options are only available since client version 2.3.0
# If you use an older client then switch to desired_capabilities
# instead: https://github.com/appium/python-client/pull/720
from appium.options.ios import XCUITestOptions
from appium.webdriver.common.appiumby import AppiumBy

options = XCUITestOptions()
options.platformVersion = '13.4'
options.udid = '123456789ABC'
options.app = PATH('../../apps/UICatalog.app.zip')
# Appium1 points to http://127.0.0.1:4723/wd/hub by default 
self.driver = webdriver.Remote('http://127.0.0.1:4723', options=options)
el = self.driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='item')
el.click()
```

## Direct Connect URLs

If your Selenium/Appium server decorates the new session capabilities response with the following keys:

- `directConnectProtocol`
- `directConnectHost`
- `directConnectPort`
- `directConnectPath`

Then python client will switch its endpoint to the one specified by the values of those keys.

```python
from appium import webdriver
# Options are only available since client version 2.3.0
# If you use an older client then switch to desired_capabilities
# instead: https://github.com/appium/python-client/pull/720
from appium.options.ios import XCUITestOptions

# load_capabilities API could be used to 
# load options mapping stored in a dictionary
options = XCUITestOptions().load_capabilities({
    'platformVersion': '13.4',
    'deviceName': 'iPhone Simulator',
    'app': PATH('../../apps/UICatalog.app.zip'),
})

self.driver = webdriver.Remote(
    # Appium1 points to http://127.0.0.1:4723/wd/hub by default 
    'http://127.0.0.1:4723', 
    options=options, 
    direct_connection=True
)
```

## Relax SSL validation

`strict_ssl` option allows you to send commands to an invalid certificate host like a self-signed one.

```python
from appium import webdriver
# Options are only available since client version 2.3.0
# If you use an older client then switch to desired_capabilities
# instead: https://github.com/appium/python-client/pull/720
from appium.options.common import AppiumOptions

options = AppiumOptions()
options.platform_name = 'mac'
options.automation_name = 'safari'
# set_capability API allows to provide any custom option
# calls to it could be chained
options.set_capability('browser_name', 'safari')

# Appium1 points to http://127.0.0.1:4723/wd/hub by default 
self.driver = webdriver.Remote('http://127.0.0.1:4723', options=options, strict_ssl=False)
```

## Documentation

- https://appium.github.io/python-client-sphinx/ is detailed documentation
- [functional tests](test/functional) also may help to see concrete examples.

## Development

- Code Style: [PEP-0008](https://www.python.org/dev/peps/pep-0008/)
  - Apply `black`, `isort` and `mypy` as pre commit hook
  - Run `make` command for development. See `make help` output for details
- Docstring style: [Google Style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
- `gitchangelog` generates `CHANGELOG.rst`

### Setup

- `pip install --user pipenv`
- `python -m pipenv lock --clear`
  - If you experience `Locking Failed! unknown locale: UTF-8` error, then refer [pypa/pipenv#187](https://github.com/pypa/pipenv/issues/187) to solve it.
- `python -m pipenv install --dev --system`
- `pre-commit install`

### Run tests

You can run all of tests running on CI via `tox` in your local.

```bash
$ tox
```

You also can run particular tests like below.

#### Unit

```bash
$ pytest test/unit
```

Run with `pytest-xdist`

```bash
$ pytest -n 2 test/unit
```

#### Functional

```bash
$ pytest test/functional/ios/search_context/find_by_ios_class_chain_tests.py
```

#### In parallel for iOS

1. Create simulators named 'iPhone X - 8100' and 'iPhone X - 8101'
2. Install test libraries via pip, `pip install pytest pytest-xdist`
3. Run tests

```bash
$ pytest -n 2 test/functional/ios/search_context/find_by_ios_class_chain_tests.py
```

## Release

Follow below steps.

```bash
$ pip install twine
$ pip install git+git://github.com/vaab/gitchangelog.git # Getting via GitHub repository is necessary for Python 3.7
# Type the new version number and 'yes' if you can publish it
# You can test the command with DRY_RUN
$ DRY_RUN=1 ./release.sh
$ ./release.sh # release
```

## License

Apache License v2



            

Raw data

            {
    "_id": null,
    "home_page": "http://appium.io/",
    "name": "Appium-Python-Client",
    "maintainer": "Kazuaki Matsuo, Mykola Mokhnach, Mori Atsushi",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "appium,selenium,selenium 4,python client,mobile automation",
    "author": "Isaac Murchie",
    "author_email": "isaac@saucelabs.com",
    "download_url": "https://files.pythonhosted.org/packages/49/f3/1794d6dee1dbaf57b7d44a21de36a56070dddb1e16b1accc21c3e563e383/Appium-Python-Client-2.7.0.tar.gz",
    "platform": null,
    "description": "# Appium Python Client\n\n[![PyPI version](https://badge.fury.io/py/Appium-Python-Client.svg)](https://badge.fury.io/py/Appium-Python-Client)\n[![Downloads](https://pepy.tech/badge/appium-python-client)](https://pepy.tech/project/appium-python-client)\n\n[![Build Status](https://dev.azure.com/AppiumCI/Appium%20CI/_apis/build/status/appium.python-client?branchName=master)](https://dev.azure.com/AppiumCI/Appium%20CI/_build/latest?definitionId=56&branchName=master)\n\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nAn extension library for adding [WebDriver Protocol](https://www.w3.org/TR/webdriver/) and Appium commands to the Selenium Python language binding for use with the mobile testing framework [Appium](https://appium.io).\n\n## Notice\n\nSince **v1.0.0**, only Python 3.7+ is supported.\n\nSince **v2.0.0**, the base selenium client version is v4.\nThe version only works in W3C WebDriver protocol format.\nIf you would like to use the old protocol (MJSONWP), please use v1 Appium Python client.\n\n### Quick migration guide from v1 to v2\n- Enhancement\n    - Updated base Selenium Python binding version to v4\n        - Removed `forceMjsonwp` since Selenium v4 and Appium Python client v2 expect only W3C WebDriver protocol\n    - Methods `ActionHelpers#scroll`, `ActionHelpers#drag_and_drop`, `ActionHelpers#tap`, `ActionHelpers#swipe` and `ActionHelpers#flick` now call W3C actions as its backend\n        - Please check each behavior. Their behaviors could slightly differ.\n    - Added `strict_ssl` to relax SSL error such as self-signed ones\n- Deprecated\n    - `MultiAction` and `TouchAction` are deprecated. Please use W3C WebDriver actions.\n        - e.g.\n            - [appium/webdriver/extensions/action_helpers.py](appium/webdriver/extensions/action_helpers.py)\n            - https://www.selenium.dev/documentation/support_packages/mouse_and_keyboard_actions_in_detail/\n            - https://www.youtube.com/watch?v=oAJ7jwMNFVU\n            - https://appiumpro.com/editions/30-ios-specific-touch-action-methods\n            - https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api\n    - `launch_app`, `close_app` and `reset` are deprecated. Please read [issues#15807](https://github.com/appium/appium/issues/15807) for more details\n\n#### MultiAction/TouchAction to W3C actions\n\nOn UIA2, some elements can be handled with `touch` pointer action insead of the default `mouse` pointer action in the Selenium Python cleint.\nFor example, the below action builder is to replace the default one with the `touch` pointer action.\n\n```python\nfrom selenium.webdriver.common.actions import interaction\nfrom selenium.webdriver.common.actions.action_builder import ActionBuilder\n\nactions = ActionChains(driver)\n# override as 'touch' pointer action\nactions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, \"touch\"))\nactions.w3c_actions.pointer_action.move_to_location(start_x, start_y)\nactions.w3c_actions.pointer_action.pointer_down()\nactions.w3c_actions.pointer_action.pause(2)\nactions.w3c_actions.pointer_action.move_to_location(end_x, end_y)\nactions.w3c_actions.pointer_action.release()\nactions.perform()\n```\n\n## Getting the Appium Python client\n\nThere are three ways to install and use the Appium Python client.\n\n1. Install from [PyPi](https://pypi.org), as\n['Appium-Python-Client'](https://pypi.org/project/Appium-Python-Client/).\n\n    ```shell\n    pip install Appium-Python-Client\n    ```\n\n    You can see the history from [here](https://pypi.org/project/Appium-Python-Client/#history)\n\n2. Install from source, via [PyPi](https://pypi.org). From ['Appium-Python-Client'](https://pypi.org/project/Appium-Python-Client/),\ndownload and unarchive the source tarball (Appium-Python-Client-X.X.tar.gz).\n\n    ```shell\n    tar -xvf Appium-Python-Client-X.X.tar.gz\n    cd Appium-Python-Client-X.X\n    python setup.py install\n    ```\n\n3. Install from source via [GitHub](https://github.com/appium/python-client).\n\n    ```shell\n    git clone git@github.com:appium/python-client.git\n    cd python-client\n    python setup.py install\n    ```\n\n## Usage\n\nThe Appium Python Client is fully compliant with the WebDriver Protocol\nincluding several helpers to make mobile testing in Python easier.\n\nTo use the new functionality now, and to use the superset of functions, instead of\nincluding the Selenium `webdriver` module in your test code, use that from\nAppium instead.\n\n```python\nfrom appium import webdriver\n```\n\nFrom there much of your test code will work with no change.\n\nAs a base for the following code examples, the following sets up the [UnitTest](https://docs.python.org/3/library/unittest.html)\nenvironment:\n\n```python\n# Android environment\nfrom appium import webdriver\n# Options are only available since client version 2.3.0\n# If you use an older client then switch to desired_capabilities\n# instead: https://github.com/appium/python-client/pull/720\nfrom appium.options.android import UiAutomator2Options\nfrom appium.webdriver.common.appiumby import AppiumBy\n\noptions = UiAutomator2Options()\noptions.platformVersion = '10'\noptions.udid = '123456789ABC'\noptions.app = PATH('../../../apps/test-app.apk')\n# Appium1 points to http://127.0.0.1:4723/wd/hub by default \nself.driver = webdriver.Remote('http://127.0.0.1:4723', options=options)\nel = self.driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='item')\nel.click()\n```\n\n```python\n# iOS environment\nfrom appium import webdriver\n# Options are only available since client version 2.3.0\n# If you use an older client then switch to desired_capabilities\n# instead: https://github.com/appium/python-client/pull/720\nfrom appium.options.ios import XCUITestOptions\nfrom appium.webdriver.common.appiumby import AppiumBy\n\noptions = XCUITestOptions()\noptions.platformVersion = '13.4'\noptions.udid = '123456789ABC'\noptions.app = PATH('../../apps/UICatalog.app.zip')\n# Appium1 points to http://127.0.0.1:4723/wd/hub by default \nself.driver = webdriver.Remote('http://127.0.0.1:4723', options=options)\nel = self.driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='item')\nel.click()\n```\n\n## Direct Connect URLs\n\nIf your Selenium/Appium server decorates the new session capabilities response with the following keys:\n\n- `directConnectProtocol`\n- `directConnectHost`\n- `directConnectPort`\n- `directConnectPath`\n\nThen python client will switch its endpoint to the one specified by the values of those keys.\n\n```python\nfrom appium import webdriver\n# Options are only available since client version 2.3.0\n# If you use an older client then switch to desired_capabilities\n# instead: https://github.com/appium/python-client/pull/720\nfrom appium.options.ios import XCUITestOptions\n\n# load_capabilities API could be used to \n# load options mapping stored in a dictionary\noptions = XCUITestOptions().load_capabilities({\n    'platformVersion': '13.4',\n    'deviceName': 'iPhone Simulator',\n    'app': PATH('../../apps/UICatalog.app.zip'),\n})\n\nself.driver = webdriver.Remote(\n    # Appium1 points to http://127.0.0.1:4723/wd/hub by default \n    'http://127.0.0.1:4723', \n    options=options, \n    direct_connection=True\n)\n```\n\n## Relax SSL validation\n\n`strict_ssl` option allows you to send commands to an invalid certificate host like a self-signed one.\n\n```python\nfrom appium import webdriver\n# Options are only available since client version 2.3.0\n# If you use an older client then switch to desired_capabilities\n# instead: https://github.com/appium/python-client/pull/720\nfrom appium.options.common import AppiumOptions\n\noptions = AppiumOptions()\noptions.platform_name = 'mac'\noptions.automation_name = 'safari'\n# set_capability API allows to provide any custom option\n# calls to it could be chained\noptions.set_capability('browser_name', 'safari')\n\n# Appium1 points to http://127.0.0.1:4723/wd/hub by default \nself.driver = webdriver.Remote('http://127.0.0.1:4723', options=options, strict_ssl=False)\n```\n\n## Documentation\n\n- https://appium.github.io/python-client-sphinx/ is detailed documentation\n- [functional tests](test/functional) also may help to see concrete examples.\n\n## Development\n\n- Code Style: [PEP-0008](https://www.python.org/dev/peps/pep-0008/)\n  - Apply `black`, `isort` and `mypy` as pre commit hook\n  - Run `make` command for development. See `make help` output for details\n- Docstring style: [Google Style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)\n- `gitchangelog` generates `CHANGELOG.rst`\n\n### Setup\n\n- `pip install --user pipenv`\n- `python -m pipenv lock --clear`\n  - If you experience `Locking Failed! unknown locale: UTF-8` error, then refer [pypa/pipenv#187](https://github.com/pypa/pipenv/issues/187) to solve it.\n- `python -m pipenv install --dev --system`\n- `pre-commit install`\n\n### Run tests\n\nYou can run all of tests running on CI via `tox` in your local.\n\n```bash\n$ tox\n```\n\nYou also can run particular tests like below.\n\n#### Unit\n\n```bash\n$ pytest test/unit\n```\n\nRun with `pytest-xdist`\n\n```bash\n$ pytest -n 2 test/unit\n```\n\n#### Functional\n\n```bash\n$ pytest test/functional/ios/search_context/find_by_ios_class_chain_tests.py\n```\n\n#### In parallel for iOS\n\n1. Create simulators named 'iPhone X - 8100' and 'iPhone X - 8101'\n2. Install test libraries via pip, `pip install pytest pytest-xdist`\n3. Run tests\n\n```bash\n$ pytest -n 2 test/functional/ios/search_context/find_by_ios_class_chain_tests.py\n```\n\n## Release\n\nFollow below steps.\n\n```bash\n$ pip install twine\n$ pip install git+git://github.com/vaab/gitchangelog.git # Getting via GitHub repository is necessary for Python 3.7\n# Type the new version number and 'yes' if you can publish it\n# You can test the command with DRY_RUN\n$ DRY_RUN=1 ./release.sh\n$ ./release.sh # release\n```\n\n## License\n\nApache License v2\n\n\n",
    "bugtrack_url": null,
    "license": "Apache 2.0",
    "summary": "Python client for Appium",
    "version": "2.7.0",
    "split_keywords": [
        "appium",
        "selenium",
        "selenium 4",
        "python client",
        "mobile automation"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "94f68504c6bf98d595ec67de9a7b7dbf",
                "sha256": "fdf9f7154dadef9d5a144d9e8f8d7f19bdfbf8149abc591f9f789a23a8976940"
            },
            "downloads": -1,
            "filename": "Appium-Python-Client-2.7.0.tar.gz",
            "has_sig": false,
            "md5_digest": "94f68504c6bf98d595ec67de9a7b7dbf",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 3358275,
            "upload_time": "2022-09-23T06:47:28",
            "upload_time_iso_8601": "2022-09-23T06:47:28.372536Z",
            "url": "https://files.pythonhosted.org/packages/49/f3/1794d6dee1dbaf57b7d44a21de36a56070dddb1e16b1accc21c3e563e383/Appium-Python-Client-2.7.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2022-09-23 06:47:28",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "appium-python-client"
}
        
Elapsed time: 0.45666s