命令行交互功能

本部分旨在解释 Kea 的命令行界面（CLI）是如何设计及实现的，包括如何处理命令行参数、YAML 配置文件以及参数清洗。

功能说明与功能设计

下述流程图的介绍了Kea工具CLI的启动和配置过程。涵盖了从命令行参数解析、配置文件加载、测试环境设置到自动化测试执行的整个自动化测试准备和启动过程。通过这种方式，用户可以灵活地配置测试环境，并自动化地执行测试用例。

../../../_images/cli_flowchart.png — CLI实现的流程图

具体执行步骤如下：

解析命令行和配置文件参数
- 使用 argparse 库创建一个参数解析器。
- 定义接受的命令行参数，例如 -f 用于指定性质文件，-d 用于指定设备序列号等。
- 解析命令行输入的参数。
检查是否加载配置文件
- 检查命令行参数中是否包含了 --load_config 标志，该标志指示是否从配置文件 config.yml 中加载参数。
从`config.yml`加载参数
- 如果指定了 --load_config ，则调用 load_ymal_args 函数从 config.yml 文件中读取参数。
- 这些参数会覆盖命令行中指定的参数。
使用命令行参数
- 如果没有指定 --load_config ，则直接使用命令行解析得到的参数。
设置参数并创建`Setting`实例
- 根据解析得到的参数，创建一个 Setting 类的实例，该实例包含了所有需要的配置信息。
加载PDL驱动
- 根据 Setting 实例中的 is_harmonyos 属性判断目标设备是Android还是HarmonyOS。
- 根据平台加载相应的PDL（Property Description Language）驱动。
创建`Kea`实例
- 创建 Kea 类的实例， Kea 可能是一个自动化测试框架的核心类。
加载应用性质
- 使用 Kea.load_app_properties 方法加载需要测试的应用性质，这些性质定义了要测试的应用行为。
启动`Kea`
- 调用 start_kea 函数，传入 Kea 实例和 Setting 实例，开始执行自动化测试流程。
- start_kea 函数会初始化 DroidBot ，它是 Kea 的数据生成器，并启动测试。

命令行参数解析

Kea 使用 argparse 库来解析命令行参数。以下是主要的命令行参数：

-f 或 --property_files: 指定要测试的应用性质文件。
-d 或 --device_serial: 指定目标设备的序列号。
-a 或 --apk: 指定待测应用安装包文件的路径，或待测应用的包名。
-o 或 --output: 指定输出目录，默认为 “output”。
-p 或 --policy: 指定输入事件生成策略，默认为 “random”。
-t 或 --timeout: 指定超时时间（秒），默认为预设值。
-debug: 开启调试模式，输出调试信息。
-keep_app: 测试后保留设备上的应用。
-grant_perm: 安装时授予所有权限，对 Android 6.0+ 有用。
-is_emulator: 声明目标设备为模拟器。
-is_harmonyos: 使用 HarmonyOS 设备。
-load_config: 从 config.yml 加载参数，命令行参数将被忽略。

YAML 配置文件

Kea 支持通过 YAML 配置文件（config.yml）来指定参数，以简化参数的配置过程。YAML 文件中的参数值将覆盖命令行参数。

参数对象

Kea 使用 dataclass 定义了一个名为 Setting 的参数对象，用于存储和传递参数。这个对象包含了所有与测试相关的配置。

启动 Kea

以下是 Kea 启动流程的简要说明：

解析命令行参数和 YAML 配置文件。
设置参数对象 Setting。
根据目标平台加载相应的 PDL 驱动。
创建 Kea 实例并加载应用性质。
启动 Kea 进行测试。

主要函数设计

以下是 Kea CLI 中每个主要函数的功能介绍：

parse_args 函数：
- 负责解析命令行输入的参数。
- 根据用户输入设置相应的命令行参数，并处理 -load_config 选项以决定是否从 YAML 配置文件中加载参数。
其简化代码如下：

def parse_args():
    parser = argparse.ArgumentParser(...)
    parser.add_argument(...)
    options = parser.parse_args()

    # load the args from the config file `config.yml`
    if options.load_config:
        options = load_ymal_args(options)

    # sanitize these args
    sanitize_args(options)

    return options

load_yaml_args 函数：
- 负责从 config.yml YAML 配置文件中读取参数。
- 将配置文件中的参数值应用到参数对象中，覆盖命令行输入的参数。
其简化代码如下：

def load_yaml_args(opts):
    config = get_yml_config()
    key_map = {...}
    for key, value in config.items():
        key_lower = key.lower()
        if value and key_lower in key_map:
            key_map[key_lower](value)

    return opts

sanitize_args 函数：
- 对解析后的参数进行清洗和验证。
- 确保所有参数在传递给 Kea 之前都是有效和一致的。
其简化代码如下：

def sanitize_args(options):
    if not options.device_serial:
        identify_device_serial(options)
    if not options.apk_path or not options.property_files:
        raise Error
    if not options.apk_path.endswith(('.apk', '.hap')):
        sanitize_app_package_name(options)

Setting 数据类：
- 定义了 Kea 运行所需的配置参数的数据结构。
- 存储和管理如 APK 路径、设备序列号、输出目录等参数。
其简化代码如下：

class Setting:
    apk_path: str
    device_serial: str = None
    output_dir: str = "output"
    is_emulator: bool = True
    policy_name: str = "default_policy"
    event_count: int = 100
    keep_app: bool = None
    keep_env = None
    number_of_events_that_restart_app: int = 100
    is_harmonyos: bool = False
    generate_utg: bool = False
    is_package: bool = False

load_pdl_driver 函数：
- 根据目标平台（Android 或 HarmonyOS）加载相应的 PDL 驱动。
- 确保 Kea 能够与目标设备的操作系统交互。
其简化代码如下：

def load_pdl_driver(settings):
    if settings.is_harmonyos:
        from kea.harmonyos_pdl_driver import HarmonyOS_PDL_Driver
        return HarmonyOS_PDL_Driver(serial=settings.device_serial)
    else:
        from kea.android_pdl_driver import Android_PDL_Driver
        return Android_PDL_Driver(serial=settings.device_serial)

start_kea 函数：
- 初始化 DroidBot 实例，并设置 Kea 的 PDL 驱动。
- 创建 Kea 实例，加载应用性质，并开始执行测试。
其简化代码如下：

def start_kea(kea, settings):

    # droidbot is used as the data generator of Kea
    droidbot = DroidBot(...)
    kea._pdl_driver.set_droidbot(droidbot)
    droidbot.start()

main 函数：
- 作为程序的入口点，串联起整个 Kea 启动流程。
- 调用其他函数完成参数解析、配置加载、PDL 驱动加载和 Kea 启动。
其简化代码如下：

def main():
    options = parse_args()
    settings = Setting(...)
    driver = load_pdl_driver(settings)
    Kea.set_pdl_driver(driver)
    Kea.load_app_properties(options.property_files)
    kea = Kea()
    start_kea(kea, settings)