# Robot Framework - Appium Extensions (Android)
Custom keywords extending [Robot Framework’s AppiumLibrary](https://github.com/serhatbolsu/robotframework-appiumlibrary), optimized for **mobile automation on Android**.
This library enhances the native AppiumLibrary with new gestures, UI utilities, and validation features designed for **QA teams automating Android applications**.
It aims to serve as an open-source reference for improving test reliability, coverage, and maintainability in mobile test automation.
[](https://pypi.org/project/robotframework-appium-extensions/)
[](LICENSE)
[](https://www.python.org/downloads/)
---
## Available Keywords
- Gestures:
- Scroll Inside
- Scroll To Element
- Swipe Element
- Perform Long Press
- Perform Pinch
- Perform Zoom
- Touch utilities:
- Click Elements
- Tap At Percentage
- Tap Element At Coordinates
- Visibility & Lookup:
- Compare Screenshots
- Get Visible Elements On Screen
- Wait Multiple Elements
- System/App:
- Change Theme
- Get Readable Network Status
- Terminate Application Extension
Individual documentation are in keyword docstrings.
---
## Technology Stack
- **Python 3.9+**
- **Robot Framework 4.0+**
- **Appium Server 2.0**
- **UiAutomator2 driver (Android)**
- **Appium-Python-Client 5.1.1+**
- **Selenium W3C Actions**
- **OpenCV + scikit-image + NumPy** (for visual comparison)
- **ADB + Android SDK tools**
---
## Prerequisites and Requirements
- Android device or emulator connected with ADB
- Dependencies listed in `requirements.txt`
- Appium Server running (`appium` or `appium --allow-cors`)
```bash
npm install -g appium
```
- UiAutomator2 driver installed (`appium driver install uiautomator2`)
```bash
appium driver install uiautomator2
```
---
## Installation
You can install the package directly from **PyPI** (recommended):
```bash
pip install robotframework-appium-extensions
```
Or, if you prefer to work with the latest development version:
```bash
git clone https://github.com/<....>.git
cd robotframework-appium-extensions
pip install .
```
---
## How To Run Tests
Run any .robot test suite using Robot Framework’s CLI:
```bash
robot -d results tests/robot/perform_zoom.robot
```
- `-d results` saves logs, reports, and screenshots in a dedicated folder.
- You can adapt paths for your test files or custom resources.
---
## Emulator / Device Setup
To successfully run the automated tests included in this repository, ensure that the test environment (emulator or physical device) meets the following conditions:
- Use an **Android device or emulator** running **Android 11 or higher**.
- Before executing the test suites, **verify which applications are required** by the selected tests and ensure they are **properly installed** on the device.
> For example: some suites may require system apps such as Calculator, Google Maps, or Play Store.
- Using a **Google APIs emulator image** is recommended, as minimal system images may lack these default apps.
---
## Usage Example
```robot
*** Settings ***
Library AppiumLibrary
Library robotframework_appium_extensions.keywords.PerformPinch
*** Test Cases ***
Pinch Example
Open Application http://localhost:4723 platformName=Android automationName=UiAutomator2
Perform Pinch locator=id=map_view scale=0.6
```
---
## Known Limitations
- Platform: tested on Android 7.0+; iOS not supported.
- Multi-touch gestures: Android 9+ recommended for reliable Pinch/Zoom (W3C Actions).
- Device fragmentation: differences between manufacturers (Samsung/Xiaomi, etc.) may affect gesture behavior.
- Dynamic elements: fast-moving/animated elements may require explicit waits.
- Power saving mode: can cause inconsistencies; disable during tests.
- Performance: image comparison may be slow on high-resolution screens.
---
## Troubleshooting
- Device not detected: run adb devices → enable USB Debugging; restart ADB (`adb kill-server && adb start-server`).
- Appium session not starting: ensure Appium 2.x is running and uiautomator2 driver installed (`appium driver install uiautomator2`).
- Element not found: validate selectors in Appium Inspector; prefer `id/accessibility_id`; use explicit waits.
- Inconsistent gestures: increase `duration/steps`; add pauses (`pause_before/pause_after`); prefer Android 9+.
- Slow/timeouts: use a good-quality USB cable; disable Android animations; increase timeouts; close background apps.
- ADB errors: ensure `adb` is in your PATH; restart ADB; reconnect the device; check permissions.
---
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
- Code style
- Commit messages
- Tests and documentation
- PR process
---
## License
Licensed under Apache 2.0 [LICENSE](LICENSE)
---
### Acknowledgments
This open-source repository was developed within the scope of the **Technology Residency Program**,
executed by **CEPEDI**, coordinated by **SOFTEX**, and supported by the **Ministry of Science, Technology and Innovation (MCTI)**.
The development challenge addressed in this repository was proposed by **Positivo Tecnologia**,
a partner company of the program, as part of its collaboration with the Technology Residency initiative.
We acknowledge and thank all the institutions involved for their support in the execution and dissemination of this open-source project.
Raw data
{
"_id": null,
"home_page": null,
"name": "robotframework-appium-extensions",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Diogo Dorea <diogodorea@gmail.com>, Eduardo Takeshi <wattksh@gmail.com>, Fabio Nilo <fabionilosoares@gmail.com>, Gabriel Cerqueira <gcacarvalho.cic@uesc.br>, Geovane Gl\u00f3ria <geovaneglorialima@gmail.com>, Henio Pedro <henioslv@gmail.com>, Marya Fernandes <marya_matos@hotmail.com>, Thalles Cardoso <thallescard@gmail.com>",
"keywords": "robotframework, appium, mobile, automation, android, testing",
"author": "Equipe de QA - CEPEDI / RESTIC36",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4e/f8/6ea3a3314f2f8fe86a0c064b147a988a4c473f64ef0dc49e94b4ea415103/robotframework_appium_extensions-1.0.0.tar.gz",
"platform": null,
"description": "# Robot Framework - Appium Extensions (Android)\n\nCustom keywords extending [Robot Framework\u2019s AppiumLibrary](https://github.com/serhatbolsu/robotframework-appiumlibrary), optimized for **mobile automation on Android**.\n\nThis library enhances the native AppiumLibrary with new gestures, UI utilities, and validation features designed for **QA teams automating Android applications**. \nIt aims to serve as an open-source reference for improving test reliability, coverage, and maintainability in mobile test automation.\n\n[](https://pypi.org/project/robotframework-appium-extensions/)\n[](LICENSE)\n[](https://www.python.org/downloads/)\n\n---\n\n## Available Keywords\n\n- Gestures:\n - Scroll Inside\n - Scroll To Element\n - Swipe Element\n - Perform Long Press\n - Perform Pinch\n - Perform Zoom\n\n- Touch utilities:\n - Click Elements\n - Tap At Percentage\n - Tap Element At Coordinates\n\n- Visibility & Lookup:\n - Compare Screenshots\n - Get Visible Elements On Screen\n - Wait Multiple Elements\n\n- System/App:\n - Change Theme\n - Get Readable Network Status\n - Terminate Application Extension\n\nIndividual documentation are in keyword docstrings.\n\n---\n\n## Technology Stack\n\n- **Python 3.9+**\n- **Robot Framework 4.0+**\n- **Appium Server 2.0**\n- **UiAutomator2 driver (Android)**\n- **Appium-Python-Client 5.1.1+**\n- **Selenium W3C Actions**\n- **OpenCV + scikit-image + NumPy** (for visual comparison)\n- **ADB + Android SDK tools**\n\n---\n\n## Prerequisites and Requirements\n\n- Android device or emulator connected with ADB\n- Dependencies listed in `requirements.txt`\n- Appium Server running (`appium` or `appium --allow-cors`)\n ```bash\n npm install -g appium\n ```\n- UiAutomator2 driver installed (`appium driver install uiautomator2`)\n ```bash\n appium driver install uiautomator2\n ```\n\n---\n\n## Installation\n\nYou can install the package directly from **PyPI** (recommended):\n```bash\npip install robotframework-appium-extensions\n```\n\nOr, if you prefer to work with the latest development version:\n```bash\ngit clone https://github.com/<....>.git\ncd robotframework-appium-extensions\npip install .\n```\n\n---\n\n## How To Run Tests\n\nRun any .robot test suite using Robot Framework\u2019s CLI:\n```bash\nrobot -d results tests/robot/perform_zoom.robot\n```\n- `-d results` saves logs, reports, and screenshots in a dedicated folder.\n- You can adapt paths for your test files or custom resources.\n\n---\n\n## Emulator / Device Setup\n\nTo successfully run the automated tests included in this repository, ensure that the test environment (emulator or physical device) meets the following conditions:\n- Use an **Android device or emulator** running **Android 11 or higher**. \n- Before executing the test suites, **verify which applications are required** by the selected tests and ensure they are **properly installed** on the device. \n > For example: some suites may require system apps such as Calculator, Google Maps, or Play Store.\n- Using a **Google APIs emulator image** is recommended, as minimal system images may lack these default apps.\n\n---\n\n## Usage Example\n\n```robot\n*** Settings ***\nLibrary AppiumLibrary\nLibrary robotframework_appium_extensions.keywords.PerformPinch\n\n*** Test Cases ***\nPinch Example\n Open Application http://localhost:4723 platformName=Android automationName=UiAutomator2\n Perform Pinch locator=id=map_view scale=0.6\n```\n\n---\n\n## Known Limitations\n\n- Platform: tested on Android 7.0+; iOS not supported.\n- Multi-touch gestures: Android 9+ recommended for reliable Pinch/Zoom (W3C Actions).\n- Device fragmentation: differences between manufacturers (Samsung/Xiaomi, etc.) may affect gesture behavior.\n- Dynamic elements: fast-moving/animated elements may require explicit waits.\n- Power saving mode: can cause inconsistencies; disable during tests.\n- Performance: image comparison may be slow on high-resolution screens.\n\n---\n\n## Troubleshooting\n\n- Device not detected: run adb devices \u2192 enable USB Debugging; restart ADB (`adb kill-server && adb start-server`).\n- Appium session not starting: ensure Appium 2.x is running and uiautomator2 driver installed (`appium driver install uiautomator2`).\n- Element not found: validate selectors in Appium Inspector; prefer `id/accessibility_id`; use explicit waits.\n- Inconsistent gestures: increase `duration/steps`; add pauses (`pause_before/pause_after`); prefer Android 9+.\n- Slow/timeouts: use a good-quality USB cable; disable Android animations; increase timeouts; close background apps.\n- ADB errors: ensure `adb` is in your PATH; restart ADB; reconnect the device; check permissions.\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:\n\n- Code style\n- Commit messages\n- Tests and documentation\n- PR process\n\n---\n\n## License\n\nLicensed under Apache 2.0 [LICENSE](LICENSE)\n\n---\n\n### Acknowledgments\n\nThis open-source repository was developed within the scope of the **Technology Residency Program**, \nexecuted by **CEPEDI**, coordinated by **SOFTEX**, and supported by the **Ministry of Science, Technology and Innovation (MCTI)**.\n\nThe development challenge addressed in this repository was proposed by **Positivo Tecnologia**, \na partner company of the program, as part of its collaboration with the Technology Residency initiative.\n\nWe acknowledge and thank all the institutions involved for their support in the execution and dissemination of this open-source project.\n",
"bugtrack_url": null,
"license": null,
"summary": "Additional keywords for Robot Framework's AppiumLibrary. Developed within the Technology Residency Program executed by CEPEDI, coordinated by SOFTEX, and supported by MCTI, with the participation of Positivo Tecnologia as the partner company that proposed the development challenge.",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/restic36/robotframework-appium-extensions/blob/develop/docs/CHANGELOG.md",
"Documentation": "https://github.com/restic36/robotframework-appium-extensions/blob/develop/README.md",
"Homepage": "https://github.com/restic36/robotframework-appium-extensions"
},
"split_keywords": [
"robotframework",
" appium",
" mobile",
" automation",
" android",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "43fb03b8d4c968e60e7c01693341af214aa282154302140f7dfa31ae6ce68d34",
"md5": "06dfdf504d20224f9a3861b43f8d5e3d",
"sha256": "80c4ef59ff2eb54be347e81cb8521c7011d1c7f547ef2bec1119307eb7bdf2e6"
},
"downloads": -1,
"filename": "robotframework_appium_extensions-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06dfdf504d20224f9a3861b43f8d5e3d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 47469,
"upload_time": "2025-10-30T15:43:25",
"upload_time_iso_8601": "2025-10-30T15:43:25.928791Z",
"url": "https://files.pythonhosted.org/packages/43/fb/03b8d4c968e60e7c01693341af214aa282154302140f7dfa31ae6ce68d34/robotframework_appium_extensions-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4ef86ea3a3314f2f8fe86a0c064b147a988a4c473f64ef0dc49e94b4ea415103",
"md5": "969410fafac4129bdc046dec781c8c16",
"sha256": "15417e5a371798df33e31138b64dbf38fb50735eb8c0dd678cd29ebf27fdf287"
},
"downloads": -1,
"filename": "robotframework_appium_extensions-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "969410fafac4129bdc046dec781c8c16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 38103,
"upload_time": "2025-10-30T15:43:27",
"upload_time_iso_8601": "2025-10-30T15:43:27.633349Z",
"url": "https://files.pythonhosted.org/packages/4e/f8/6ea3a3314f2f8fe86a0c064b147a988a4c473f64ef0dc49e94b4ea415103/robotframework_appium_extensions-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 15:43:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "restic36",
"github_project": "robotframework-appium-extensions",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "robotframework-appium-extensions"
}
JSON
