Metadata-Version: 2.1
Name: pytest-android
Version: 2019.1a8
Summary: This fixture provides a configured "driver" for Android Automated Testing, using uiautomator2.
Home-page: https://github.com/edsion1107/pytest-android
Author: edsion
Author-email: edsion@i1hao.com
Maintainer: edsion
Maintainer-email: edsion@i1hao.com
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: MacOS
Classifier: Operating System :: Android
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Natural Language :: Chinese (Simplified)
Classifier: License :: OSI Approved :: MIT License
Requires-Python: ~=3.6
Description-Content-Type: text/markdown
Requires-Dist: pytest
Requires-Dist: pytest-variables
Requires-Dist: uiautomator2
Requires-Dist: pillow
Provides-Extra: allure
Requires-Dist: allure-pytest ; extra == 'allure'
Provides-Extra: hjson
Requires-Dist: hjson ; extra == 'hjson'
Provides-Extra: rerunfailures
Requires-Dist: pytest-rerunfailures ; extra == 'rerunfailures'
Provides-Extra: weditor
Requires-Dist: weditor ; extra == 'weditor'
Provides-Extra: yaml
Requires-Dist: PyYAML ; extra == 'yaml'

# pytest-android

![PyPI version](https://img.shields.io/pypi/v/pytest-android.svg) ![Python versions](https://img.shields.io/pypi/pyversions/pytest-android.svg) ![See Build Status on Travis CI](https://travis-ci.org/edsion1107/pytest-android.svg?branch=master)

pytest-android is a plugin for [pytest](http://pytest.org/) that provides a configured 'driver' for Android Automated Testing, using [uiautomator2](https://github.com/openatx/uiautomator2).

pytest-android 是 [pytest](http://pytest.org/) 的插件，它通过 [uiautomator2](https://github.com/openatx/uiautomator2) 为 Android 自动化测试提供“驱动”。



目录
=================

   * [pytest-android](#pytest-android)
   * [目录](#目录)
      * [主要功能](#主要功能)
      * [安装](#安装)
         * [1. 安装 python](#1-安装-python)
         * [2. 创建工程](#2-创建工程)
         * [3. 安装插件和一些可选模块](#3-安装插件和一些可选模块)
      * [使用](#使用)
         * [1. 创建配置文件](#1-创建配置文件)
            * [1.1 config.yaml](#11-configyaml)
            * [1.2 pytest.ini](#12-pytestini)
         * [2. 编写用例](#2-编写用例)
            * [2.1 可用的Fixtures](#21-可用的fixtures)
            * [2.2 编写用例](#22-编写用例)
      * [Issues](#issues)
      * [贡献代码](#贡献代码)
      * [License](#license)


## 主要功能

- 整合 [uiautomator2](https://github.com/openatx/uiautomator2)，实现基于控件的自动化测试
- 依赖 [pytest-variables](https://github.com/pytest-dev/pytest-variables) 实现参数化配置
- 借助 [allure](https://github.com/allure-framework/allure-python) 生成测试报告
- 借助 hook 机制，实现“点击、滑动时自动截图”、“异常时自动抓取控件信息和截图”等 fixture，减少重复工作
- 通过安装 pytest 插件，实现诸如“失败重试”、“分布式执行”、“用例分层”等



## 安装

**强烈建议** 使用 git 对代码进行版本控制，灵活运用分支开发的策略，并且将自动化整合进 DevOps 流程中。

**推荐** 本地开发使用基于`virtualenv`的工具实现环境隔离和解决各个模块之间的依赖，如`pipenv`。

**建议** 生产环境使用`docker`对各个设备之间进行“隔离”。

### 1. 安装 python

macOS、linux可以通过 [pyenv](https://github.com/pyenv/pyenv) 实现多个 python 版本的共存和切换，Windows上需要下载可执行文件、手动安装和配置环境变量。

> 因为使用了 python 3.6 的 [f-string](https://realpython.com/python-f-strings/) 特性，所以建议的 python 版本大于等于3.6。

具体安装过程略。

### 2. 创建工程

```bash
mkdir demo
cd demo
```

### 3. 安装插件和一些可选模块

推荐使用 [pipenv](https://github.com/pypa/pipenv) 进行环境管理：

```bash
# macOS
brew install pipenv
# windows,linux
pip install --user pipenv

# 必须，根据您的配置文件格式，二选一（因为插件目前在 alpha 测试阶段，需要添加`--pre`参数）
# 注意，pipenv在2018.11.26版本之后，才能支持额外（extras）模块（即安装时的中括号语法），所以使用较新的版本、或手动安装
pipenv install --pre pytest-android[yaml]	# yaml 作为配置文件，推荐
pipenv install --pre pytest-android[hjson]	# json 作为配置文件

# 以下为可选模块，根据需要选择性安装
pipenv install weditor		# uiautomator2 的录制工具
pipenv install allure-pytest		# 使用 allure 生成报告
pipenv install pytest-rerunfailures		# 使 pytest 支持失败重试
```
> PS: pip版本大于等于18时，pipenv需要的最低版本为2018.11.26（如果低于此版本会导致一系列错误）

> 注意：根据[这里的观点](https://pipenv.readthedocs.io/en/latest/advanced/#pipfile-vs-setup-py)，pytest-android 作为 **libraries**，将部署到某个特定的环境中，然后才能使所有依赖项和子依赖项的确切版本具体化。0

## 使用

### 1. 创建配置文件

#### 1.1 config.yaml

创建项目级配置文件，参考 [config.yaml](https://raw.githubusercontent.com/edsion1107/pytest-android/master/config.yaml)。此文件可以使用 yaml 和 hjson 格式（由 pytest-variables 插件实现），文件名任意。

配置文件可以同时指定多个（遇到相同字段，后面的会覆盖前面的），借助此功能可以实现：指定设备参数、实现复杂情况下的兼容性测试等。

#### 1.2 pytest.ini

创建 pytest 的配置文件，参考[文档](https://docs.pytest.org/en/latest/reference.html#configuration-options)进行基础配置。

添加`addopts = --variables config.yaml`，指定项目配置文件。



[可选]

如果使用 allure 生成报告，并安装了对应依赖，可以通过`--alluredir`指定报告的路径，通过`--clean-alluredir`指定开始前是否清理历史数据。更多参数可参考[插件文档](https://docs.qameta.io/allure/#_pytest)

如果借助 pytest-rerunfailures 插件实现失败重试，参考[插件文档](https://github.com/pytest-dev/pytest-rerunfailures)，添加`--reruns`

其他诸如 log 、markers，和第三方插件配置，根据需要参考对应文档。



这里是一份 [pytest.ini](https://raw.githubusercontent.com/edsion1107/pytest-android/master/pytest.ini) 的示例。

### 2. 编写用例

#### 2.1 可用的Fixtures

此处文档可能更新不及时，通过执行命令`python -m pytest --fixtures`，可以列出所有 fixtures 及其最新说明文档。

| Name           |  Scope   | Autouse | Description                                    |
| :------------- | :------: | :-----: | :--------------------------------------------- |
| driver         | session  |  True   | 初始化设备                                     |
| show_case_name | function |  True   | toast 提示显示用例描述或名字，便于了解进度     |
| app_start      | function |  True   | 启动 app ，（仅）通过当前 app 包名判断是否启动 |
| app_stop       | function |  True   | 每条 case 结束自动 close app                   |

根据 pytest 的[加载顺序](https://docs.pytest.org/en/latest/writing_plugins.html#plugin-discovery-order-at-tool-startup)，插件中定义的 fixture 是可以被 `conftest.py`和本地插件`pytest_plugins `覆盖的。也就是说，如果具体到项目时不满足需求，可以在`conftest.py`文件中，编写同名 fixture，修改`scope`、`autoues`和其具体行为。

#### 2.2 编写用例

新建文件 `test_demo.py`，输入以下代码：

```python
#!/usr/bin/env python
# encoding: utf-8
from uiautomator2 import UIAutomatorServer


def test_233(driver: UIAutomatorServer):
    print(driver.device_info)
```



运行：

```bash
pipenv run python -m pytest
```



## Issues

如果插件使用中遇到问题，请通过 github issues 提交。

## 贡献代码

Contributions are very welcome. 

## License

Distributed under the terms of the [MIT](LICENSE) license, "pytest-android" is free and open source software.

根据[MIT](LICENSE)许可条款分发，“pytest-android”是免费的开源软件。

