Kea Parameter Options

Kea Parameters

Kea provides the following options. Use kea -h for more information.

The following parameters are the most important parameters in kea. Most of the time, you need to specify them.

-f: Test file containing properties. You can run multiple properties against multiple files. See What does kea do when running multiple properties?.

-a --apk: The installation package file or package name of the application under test.

-d --device_serial: Serial number of the device used for testing. (This parameter can be omitted when only one device is connected; kea will automatically specify the target device. You can use ‘adb devices’ or ‘hdc list targets’ to find your target device.)

-o --output: Output directory for execution results. (Default: “output”)

-p --policy: Name of the exploration policy. (“random”, “guided”, or “llm”)

-is_emulator: Declares the target device as an emulator.

Here are some examples of starting kea.

# 快速开始，默认随机策略，输出到 "output" 目录
kea -f my_property.py -a myapp.apk

# 自定义策略
kea -f my_property.py -a myapp.apk -p guided

# 使用多个性质
kea -f my_property1.py my_property2.py -a myapp.apk

# 自定义输出目录
kea -f my_property.py -a myapp.apk -o my_output

# 当有多台设备连接到你的电脑时，指定目标设备
kea -f my_property.py -a myapp.apk -d emulator-5554 -is_emulator

Here are commands to customize kea.

-t --timeout: Test duration (seconds).

-n: Restart the application after every n events, default is 100.

-debug: Run in debug mode (outputs debug information).

-keep_app: Keep the application on the device after testing.

-grant_perm: Grant all permissions at installation. Useful for Android 6.0+.

-is_harmonyos: Use HarmonyOS device.

-load_config: Load configuration from config.yml. Settings in config.yml will override command line parameters.

-utg: Generate UTG graph.

YAML Configuration

You can use YAML configuration to start kea. Find config.yml in your kea root directory.

The config.yml file is used to simplify the process of specifying parameters through a configuration file. Note that parameter values in config.yml will override those specified on the command line.

Mapping of Configuration Parameters

The following are the mappings of parameters in the config.yml file to the parameters in the Kea parameter object:

system: Corresponds to -is_harmonyos, used to specify whether to use a HarmonyOS device.

app_path, package, package_name: These parameters correspond to -a, used to specify the apk file path or package name of the application.

policy: Corresponds to -p, used to specify the exploration policy.

output_dir: Corresponds to -o, used to specify the output directory for execution results.

count: Corresponds to -n, used to specify the number of tests.

target, device, device_serial: These parameters correspond to -d, used to specify the device serial number used for testing.

property, properties, file, files: These parameters correspond to -f, used to specify a list of test files containing properties.

Here are examples of configurations.

# env: 你的电脑系统（例如 windows, macOS, Linux）
env: Linux

# system: 目标系统
system: android
# system: harmonyOS

device: emulator-5554
app_path: example/omninotes.apk
policy: guided
count: 100
properties:
- example/example_property.py
- example/example_mainpath_property.py
#  - example/advanced_example_property.py

Once the configuration is complete, you can simply start kea using kea -load_config.

Important

When using kea on HarmonyOS, config.yml is required.

What does kea do when running multiple properties?

By default, the random and main path guided exploration strategies validate a property of the application in each run. When multiple properties are available for the application, these two strategies can validate any subset of those properties together. One benefit is that Kea can enhance the efficiency of property validation. Another benefit is that the interactions of multiple properties provide a partial model of the application. This partial model makes it more likely for us to reach a deeper state of the application during testing.

Specifically, to validate multiple properties together, the random strategy checks if the prerequisites for multiple properties are satisfied and randomly selects one property to check. The main path guided exploration strategy randomly selects one property as the target and performs guided exploration along its main path. Once every state along this main path has been explored, this strategy randomly selects another property as a new target. Additionally, when the prerequisites for multiple properties are satisfied, this strategy randomly selects one property to check.

You can see more details in How It Works.