TrigDroid Module

The main TrigDroid public API module provides classes and functions for interacting with the framework.

Main API

Configuration

Configuration classes for TrigDroid API.

class trigdroid.api.config.TestConfiguration(package='', device_id=None, min_runtime=1, background_time=0, acceleration=0, gyroscope=0, light=0, pressure=0, battery_rotation=0, wifi=None, data=None, bluetooth=None, bluetooth_mac=None, install_dummy_apps=<factory>, uninstall_apps=<factory>, grant_permissions=<factory>, revoke_permissions=<factory>, frida_hooks=False, frida_constants=None, adb_enabled=None, uptime_offset=0, geolocation=None, language=None, baseband=None, build_properties=<factory>, log_level=LogLevel.INFO, log_file=None, suppress_console_logs=False, extended_log_format=False, log_filter_include=<factory>, log_filter_exclude=<factory>, disable_changelog=False, changelog_file='changelog.txt', interaction=False, no_unroot=False)

Bases: object

Test configuration for TrigDroid API.

This class provides a clean, type-safe interface for configuring TrigDroid tests programmatically. All parameters have sensible defaults for quick setup.

Examples

# Minimal configuration config = TestConfiguration(package=’com.example.app’)

# Full configuration config = TestConfiguration(

package=’com.example.app’, device_id=’emulator-5554’, acceleration=5, gyroscope=3, battery_rotation=4, min_runtime=5, log_level=LogLevel.DEBUG, frida_hooks=True, install_dummy_apps=[‘com.dummy.app1’, ‘com.dummy.app2’]

)

# Load from file config = TestConfiguration.from_yaml_file(‘config.yaml’)

# Convert to dictionary config_dict = config.to_dict()

Parameters:

• package (str)

• device_id (str | None)

• min_runtime (int)

• background_time (int)

• acceleration (int)

• gyroscope (int)

• light (int)

• pressure (int)

• battery_rotation (int)

• wifi (bool | None)

• data (bool | None)

• bluetooth (bool | None)

• bluetooth_mac (str | None)

• install_dummy_apps (List[str])

• uninstall_apps (List[str])

• grant_permissions (List[str])

• revoke_permissions (List[str])

• frida_hooks (bool)

• frida_constants (str | None)

• adb_enabled (bool | None)

• uptime_offset (int)

• geolocation (str | None)

• language (str | None)

• baseband (str | None)

• build_properties (Dict[str, str])

• log_level (LogLevel)

• log_file (str | None)

• suppress_console_logs (bool)

• extended_log_format (bool)

• log_filter_include (List[str])

• log_filter_exclude (List[str])

• disable_changelog (bool)

• changelog_file (str)

• interaction (bool)

• no_unroot (bool)

package: str = ''

device_id: str | None = None

min_runtime: int = 1

background_time: int = 0

acceleration: int = 0

gyroscope: int = 0

light: int = 0

pressure: int = 0

battery_rotation: int = 0

wifi: bool | None = None

data: bool | None = None

bluetooth: bool | None = None

bluetooth_mac: str | None = None

install_dummy_apps: List[str]

uninstall_apps: List[str]

grant_permissions: List[str]

revoke_permissions: List[str]

frida_hooks: bool = False

frida_constants: str | None = None

adb_enabled: bool | None = None

uptime_offset: int = 0

geolocation: str | None = None

language: str | None = None

baseband: str | None = None

build_properties: Dict[str, str]

log_level: LogLevel = 'INFO'

log_file: str | None = None

suppress_console_logs: bool = False

extended_log_format: bool = False

log_filter_include: List[str]

log_filter_exclude: List[str]

disable_changelog: bool = False

changelog_file: str = 'changelog.txt'

interaction: bool = False

no_unroot: bool = False

__post_init__()

Validate configuration after initialization.

is_valid()

Check if configuration is valid.

Returns:

True if valid, False otherwise

Return type:

bool

property validation_errors: List[str]

Get list of validation errors.

Returns:

List of validation error messages

to_dict()

Convert configuration to dictionary.

Returns:

Dictionary representation of configuration

Return type:

Dict[str, Any]

to_yaml(file_path=None)

Convert configuration to YAML format.

Parameters:

file_path (str | None) – Optional path to save YAML file

Returns:

YAML string representation

Return type:

str

classmethod from_dict(data)

Create configuration from dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary containing configuration values

Returns:

TestConfiguration instance

Return type:

TestConfiguration

classmethod from_yaml_file(file_path)

Load configuration from YAML file.

Parameters:

file_path (str) – Path to YAML configuration file

Returns:

TestConfiguration instance

Raises:

ConfigurationError – If file cannot be loaded or parsed

Return type:

TestConfiguration

classmethod from_command_line(args)

Create configuration from command line arguments.

Parameters:

args (List[str]) – List of command line arguments

Returns:

TestConfiguration instance

Return type:

TestConfiguration

merge_with(other)

Merge this configuration with another, with other taking precedence.

Parameters:

other (TestConfiguration) – Configuration to merge with

Returns:

New TestConfiguration instance with merged values

Return type:

TestConfiguration

copy()

Create a copy of this configuration.

Returns:

New TestConfiguration instance

Return type:

TestConfiguration

__init__(package='', device_id=None, min_runtime=1, background_time=0, acceleration=0, gyroscope=0, light=0, pressure=0, battery_rotation=0, wifi=None, data=None, bluetooth=None, bluetooth_mac=None, install_dummy_apps=<factory>, uninstall_apps=<factory>, grant_permissions=<factory>, revoke_permissions=<factory>, frida_hooks=False, frida_constants=None, adb_enabled=None, uptime_offset=0, geolocation=None, language=None, baseband=None, build_properties=<factory>, log_level=LogLevel.INFO, log_file=None, suppress_console_logs=False, extended_log_format=False, log_filter_include=<factory>, log_filter_exclude=<factory>, disable_changelog=False, changelog_file='changelog.txt', interaction=False, no_unroot=False)

Parameters:

• package (str)

• device_id (str | None)

• min_runtime (int)

• background_time (int)

• acceleration (int)

• gyroscope (int)

• light (int)

• pressure (int)

• battery_rotation (int)

• wifi (bool | None)

• data (bool | None)

• bluetooth (bool | None)

• bluetooth_mac (str | None)

• install_dummy_apps (List[str])

• uninstall_apps (List[str])

• grant_permissions (List[str])

• revoke_permissions (List[str])

• frida_hooks (bool)

• frida_constants (str | None)

• adb_enabled (bool | None)

• uptime_offset (int)

• geolocation (str | None)

• language (str | None)

• baseband (str | None)

• build_properties (Dict[str, str])

• log_level (LogLevel)

• log_file (str | None)

• suppress_console_logs (bool)

• extended_log_format (bool)

• log_filter_include (List[str])

• log_filter_exclude (List[str])

• disable_changelog (bool)

• changelog_file (str)

• interaction (bool)

• no_unroot (bool)

Return type:

None

Device Management

Device management classes for TrigDroid API.

class trigdroid.api.devices.AndroidDevice(device_id, logger=None)

Bases: object

Represents an Android device for testing.

This class provides a simplified interface over the more complex infrastructure AndroidDevice class.

Parameters:

• device_id (str)

• logger (Logger | None)

__init__(device_id, logger=None)

Parameters:

• device_id (str)

• logger (Logger | None)

execute_command(command)

Execute ADB command on device.

Parameters:

command (str)

install_app(apk_path)

Install APK on device.

Parameters:

apk_path (str)

Return type:

bool

uninstall_app(package_name)

Uninstall app from device.

Parameters:

package_name (str)

Return type:

bool

is_app_installed(package_name)

Check if app is installed.

Parameters:

package_name (str)

Return type:

bool

start_app(package_name)

Start an application.

Parameters:

package_name (str)

Return type:

bool

stop_app(package_name)

Stop an application.

Parameters:

package_name (str)

Return type:

bool

get_device_info()

Get device information.

Return type:

Dict[str, str]

grant_permission(package_name, permission)

Grant permission to app.

Parameters:

• package_name (str)

• permission (str)

Return type:

bool

revoke_permission(package_name, permission)

Revoke permission from app.

Parameters:

• package_name (str)

• permission (str)

Return type:

bool

class trigdroid.api.devices.DeviceManager(logger=None)

Bases: object

Manages Android device connections and discovery.

Parameters:

logger (Logger | None)

__init__(logger=None)

Parameters:

logger (Logger | None)

list_devices()

List all connected Android devices.

Returns:

List of device information dictionaries

Return type:

List[Dict[str, str]]

connect_to_device(device_id=None)

Connect to a specific device or auto-select if only one available.

Parameters:

device_id (str | None) – Specific device ID to connect to, or None for auto-select

Returns:

AndroidDevice instance or None if connection fails

Return type:

AndroidDevice | None

get_device_info(device_id)

Get detailed information about a device.

Parameters:

device_id (str) – Device ID to query

Returns:

Dictionary containing device information

Return type:

Dict[str, Any]

wait_for_device(device_id=None, timeout=30)

Wait for a device to become available.

Parameters:

• device_id (str | None) – Specific device to wait for, or None for any device

• timeout (int) – Timeout in seconds

Returns:

AndroidDevice instance or None if timeout

Return type:

AndroidDevice | None

Test Results

Test result classes for TrigDroid API.

class trigdroid.api.results.TestResult(success, phase, error=None, config=None, start_time=<factory>, end_time=None, duration_seconds=None, device_info=<factory>, tests_run=<factory>, tests_passed=<factory>, tests_failed=<factory>, tests_skipped=<factory>, frida_hooks_loaded=0, frida_hooks_active=0, frida_errors=<factory>, sensor_tests_executed=<factory>, sensor_values_changed=<factory>, network_state_changes=<factory>, app_started=False, app_crashed=False, app_background_time=0.0, log_file_path=None, changelog_file_path=None, screenshot_paths=<factory>)

Bases: object

Result of a TrigDroid test execution.

Contains all information about test execution including success status, timing information, configuration used, and any errors encountered.

Examples

# Successful test result = TestResult(success=True, phase=TestPhase.EXECUTION)

# Failed test result = TestResult(

success=False, phase=TestPhase.SETUP, error=”Device connection failed”, config=config

)

Parameters:

• success (bool)

• phase (TestPhase)

• error (str | None)

• config (TestConfiguration | None)

• start_time (datetime)

• end_time (datetime | None)

• duration_seconds (float | None)

• device_info (Dict[str, Any])

• tests_run (List[str])

• tests_passed (List[str])

• tests_failed (List[str])

• tests_skipped (List[str])

• frida_hooks_loaded (int)

• frida_hooks_active (int)

• frida_errors (List[str])

• sensor_tests_executed (Dict[str, bool])

• sensor_values_changed (Dict[str, int])

• network_state_changes (Dict[str, bool])

• app_started (bool)

• app_crashed (bool)

• app_background_time (float)

• log_file_path (str | None)

• changelog_file_path (str | None)

• screenshot_paths (List[str])

success: bool

phase: TestPhase

error: str | None = None

config: TestConfiguration | None = None

start_time: datetime

end_time: datetime | None = None

duration_seconds: float | None = None

device_info: Dict[str, Any]

tests_run: List[str]

tests_passed: List[str]

tests_failed: List[str]

tests_skipped: List[str]

frida_hooks_loaded: int = 0

frida_hooks_active: int = 0

frida_errors: List[str]

sensor_tests_executed: Dict[str, bool]

sensor_values_changed: Dict[str, int]

network_state_changes: Dict[str, bool]

app_started: bool = False

app_crashed: bool = False

app_background_time: float = 0.0

log_file_path: str | None = None

changelog_file_path: str | None = None

screenshot_paths: List[str]

__post_init__()

Calculate derived fields after initialization.

mark_completed(success=None)

Mark the test as completed.

Parameters:

success (bool | None) – Optional override for success status

Return type:

None

add_test_result(test_name, passed, error=None)

Add result for a specific test.

Parameters:

• test_name (str) – Name of the test

• passed (bool) – Whether the test passed

• error (str | None) – Optional error message

Return type:

None

skip_test(test_name, reason)

Mark a test as skipped.

Parameters:

• test_name (str) – Name of the test

• reason (str) – Reason for skipping

Return type:

None

property total_tests: int

Total number of tests run.

property passed_tests: int

Number of tests that passed.

property failed_tests: int

Number of tests that failed.

property skipped_tests: int

Number of tests that were skipped.

property success_rate: float

Success rate as a percentage.

property result_enum: TestResult

Get the result as an enum value.

to_dict()

Convert result to dictionary.

Returns:

Dictionary representation of the result

Return type:

Dict[str, Any]

summary()

Get a human-readable summary of the results.

Returns:

Summary string

Return type:

str

__init__(success, phase, error=None, config=None, start_time=<factory>, end_time=None, duration_seconds=None, device_info=<factory>, tests_run=<factory>, tests_passed=<factory>, tests_failed=<factory>, tests_skipped=<factory>, frida_hooks_loaded=0, frida_hooks_active=0, frida_errors=<factory>, sensor_tests_executed=<factory>, sensor_values_changed=<factory>, network_state_changes=<factory>, app_started=False, app_crashed=False, app_background_time=0.0, log_file_path=None, changelog_file_path=None, screenshot_paths=<factory>)

Parameters:

• success (bool)

• phase (TestPhase)

• error (str | None)

• config (TestConfiguration | None)

• start_time (datetime)

• end_time (datetime | None)

• duration_seconds (float | None)

• device_info (Dict[str, Any])

• tests_run (List[str])

• tests_passed (List[str])

• tests_failed (List[str])

• tests_skipped (List[str])

• frida_hooks_loaded (int)

• frida_hooks_active (int)

• frida_errors (List[str])

• sensor_tests_executed (Dict[str, bool])

• sensor_values_changed (Dict[str, int])

• network_state_changes (Dict[str, bool])

• app_started (bool)

• app_crashed (bool)

• app_background_time (float)

• log_file_path (str | None)

• changelog_file_path (str | None)

• screenshot_paths (List[str])

Return type:

None

Test Runners

Quick Start

Command Line Interface

Core Utilities

Core enumerations for TrigDroid.

class trigdroid.core.enums.LogLevel(value)

Bases: Enum

Logging levels.

DEBUG = 'DEBUG'

INFO = 'INFO'

WARNING = 'WARNING'

ERROR = 'ERROR'

CRITICAL = 'CRITICAL'

class trigdroid.core.enums.TestPhase(value)

Bases: Enum

Test execution phases.

SETUP = 'setup'

EXECUTION = 'execution'

TEARDOWN = 'teardown'

class trigdroid.core.enums.TestResult(value)

Bases: Enum

Test execution results.

SUCCESS = 'success'

FAILURE = 'failure'

SKIPPED = 'skipped'

ERROR = 'error'

class trigdroid.core.enums.DeviceConnectionState(value)

Bases: Enum

Android device connection states.

CONNECTED = 'connected'

DISCONNECTED = 'disconnected'

UNAUTHORIZED = 'unauthorized'

OFFLINE = 'offline'

class trigdroid.core.enums.SensorType(value)

Bases: Enum

Android sensor types.

ACCELEROMETER = 'accelerometer'

GYROSCOPE = 'gyroscope'

LIGHT = 'light'

PRESSURE = 'pressure'

MAGNETOMETER = 'magnetometer'

TEMPERATURE = 'temperature'

PROXIMITY = 'proximity'

class trigdroid.core.enums.ConnectionType(value)

Bases: Enum

Network connection types.

WIFI = 'wifi'

DATA = 'data'

BLUETOOTH = 'bluetooth'

NFC = 'nfc'

class trigdroid.core.enums.BatteryRotationLevel(value)

Bases: IntEnum

Battery rotation elaborateness levels.

DISABLED = 0

SUPER_FAST = 1

FAST = 2

DETAILED = 3

SUPER_DETAILED = 4

class trigdroid.core.enums.SensorElaboratenessLevel(value)

Bases: IntEnum

Sensor test elaborateness levels.

DISABLED = 0

MINIMAL = 1

LOW = 2

MEDIUM = 3

HIGH = 4

VERY_HIGH = 5

EXTREME = 6

MAXIMUM = 7

ULTRA = 8

INSANE = 9

ULTIMATE = 10

class trigdroid.core.enums.PhoneType(value)

Bases: IntEnum

Phone types from Android TelephonyManager.

NONE = 0

GSM = 1

CDMA = 2

SIP = 3

class trigdroid.core.enums.NetworkType(value)

Bases: IntEnum

Network types from Android TelephonyManager.

UNKNOWN = 0

GPRS = 1

EDGE = 2

UMTS = 3

CDMA = 4

EVDO_0 = 5

EVDO_A = 6

RTT = 7

HSDPA = 8

HSUPA = 9

HSPA = 10

IDEN = 11

EVDO_B = 12

LTE = 13

EHRPD = 14

HSPAP = 15

GSM = 16

TD_SCDMA = 17

IWLAN = 18

NR = 20

Resource cleanup handlers for TrigDroid.

class trigdroid.core.cleanup.CleanupManager(logger=None)

Bases: object

Manages cleanup of resources during TrigDroid execution.

This class ensures that temporary files, processes, and other resources are properly cleaned up when TrigDroid exits, even if execution is interrupted.

Examples

# Register a cleanup function cleanup = CleanupManager() cleanup.register_file(“/tmp/trigdroid_temp.log”) cleanup.register_callback(lambda: print(“Cleaning up…”))

# Use as context manager with CleanupManager() as cleanup:

cleanup.register_file(temp_file) # … do work …

# Cleanup happens automatically

Parameters:

logger (Logger | None)

__init__(logger=None)

Parameters:

logger (Logger | None)

__enter__()

Enter context manager.

Return type:

CleanupManager

__exit__(exc_type, exc_val, exc_tb)

Exit context manager and perform cleanup.

register_file(file_path)

Register a file for cleanup.

Parameters:

file_path (str) – Path to file to delete on cleanup

Return type:

None

register_directory(dir_path)

Register a directory for cleanup.

Parameters:

dir_path (str) – Path to directory to delete on cleanup

Return type:

None

register_callback(callback)

Register a callback function for cleanup.

Parameters:

callback (Callable[[], Any]) – Function to call during cleanup

Return type:

None

register_process(process)

Register a process for termination.

Parameters:

process (Any) – Process object with terminate() method

Return type:

None

register_frida_session(session)

Register a Frida session for detachment.

Parameters:

session (Any) – Frida session object

Return type:

None

create_temp_file(suffix='', prefix='trigdroid_')

Create a temporary file that will be cleaned up.

Parameters:

• suffix (str) – File suffix

• prefix (str) – File prefix

Returns:

Path to temporary file

Return type:

Path

create_temp_dir(prefix='trigdroid_')

Create a temporary directory that will be cleaned up.

Parameters:

prefix (str) – Directory prefix

Returns:

Path to temporary directory

Return type:

Path

cleanup()

Perform all registered cleanup operations.

Return type:

None

classmethod cleanup_all()

Cleanup all active CleanupManager instances.

Return type:

None

trigdroid.core.cleanup.get_global_cleanup_manager()

Get the global cleanup manager instance.

Returns:

Global CleanupManager instance

Return type:

CleanupManager

trigdroid.core.cleanup.register_cleanup_file(file_path)

Register a file for cleanup using the global manager.

Parameters:

file_path (str) – Path to file to delete on cleanup

Return type:

None

trigdroid.core.cleanup.register_cleanup_dir(dir_path)

Register a directory for cleanup using the global manager.

Parameters:

dir_path (str) – Path to directory to delete on cleanup

Return type:

None

trigdroid.core.cleanup.register_cleanup_callback(callback)

Register a callback for cleanup using the global manager.

Parameters:

callback (Callable[[], Any]) – Function to call during cleanup

Return type:

None

trigdroid.core.cleanup.create_temp_file(suffix='', prefix='trigdroid_')

Create a temporary file using the global cleanup manager.

Parameters:

• suffix (str) – File suffix

• prefix (str) – File prefix

Returns:

Path to temporary file

Return type:

Path

trigdroid.core.cleanup.create_temp_dir(prefix='trigdroid_')

Create a temporary directory using the global cleanup manager.

Parameters:

prefix (str) – Directory prefix

Returns:

Path to temporary directory

Return type:

Path

class trigdroid.core.cleanup.TempResource(cleanup_manager=None)

Bases: object

Context manager for temporary resources with automatic cleanup.

Examples

# Temporary file with TempResource.file() as temp_file:

temp_file.write_text(“test data”) # … use file …

# File is automatically deleted

# Temporary directory with TempResource.dir() as temp_dir:

(temp_dir / “test.txt”).write_text(“test”) # … use directory …

# Directory is automatically deleted

Parameters:

cleanup_manager (CleanupManager | None)

__init__(cleanup_manager=None)

Parameters:

cleanup_manager (CleanupManager | None)

classmethod file(suffix='', prefix='trigdroid_')

Create a temporary file resource.

Parameters:

• suffix (str) – File suffix

• prefix (str) – File prefix

Returns:

TempFileResource context manager

Return type:

TempFileResource

classmethod dir(prefix='trigdroid_')

Create a temporary directory resource.

Parameters:

prefix (str) – Directory prefix

Returns:

TempDirResource context manager

Return type:

TempDirResource

class trigdroid.core.cleanup.TempFileResource(suffix='', prefix='trigdroid_')

Bases: object

Context manager for temporary files.

Parameters:

• suffix (str)

• prefix (str)

__init__(suffix='', prefix='trigdroid_')

Parameters:

• suffix (str)

• prefix (str)

class trigdroid.core.cleanup.TempDirResource(prefix='trigdroid_')

Bases: object

Context manager for temporary directories.

Parameters:

prefix (str)

__init__(prefix='trigdroid_')

Parameters:

prefix (str)

Exceptions

Exception classes for TrigDroid.

exception trigdroid.exceptions.TrigDroidError

Bases: Exception

Base exception for TrigDroid errors.

exception trigdroid.exceptions.ConfigurationError

Bases: TrigDroidError

Configuration-related errors.

exception trigdroid.exceptions.DeviceError

Bases: TrigDroidError

Android device-related errors.

exception trigdroid.exceptions.TestExecutionError

Bases: TrigDroidError

Test execution errors.

exception trigdroid.exceptions.FridaError

Bases: TrigDroidError

Frida-related errors.

exception trigdroid.exceptions.HookError

Bases: FridaError

Hook compilation or injection errors.

exception trigdroid.exceptions.NetworkError

Bases: TrigDroidError

Network communication errors.

exception trigdroid.exceptions.PermissionError

Bases: DeviceError

Permission-related errors.

exception trigdroid.exceptions.PackageError

Bases: DeviceError

Package installation/management errors.