flowpilot-mobile-framework 1.1.2

Modern, Intelligent Mobile Automation Framework

FlowPilot Mobile

Modern, Python-first mobile automation framework. Provides clean Playwright-style APIs for smart mobile automation with a hidden runtime engine.

🚀 Installation

Prerequisites

• Python 3.11 or higher
• Physical Android Device

Install via pip

pip install flowpilot-mobile

---

🌟 The FlowPilot "Smart" Advantage

FlowPilot includes an Intelligent Layer that handles the "messy" parts of mobile testing automatically:

• Auto-Scroll Search: Automatically swipes and retries if an element is off-screen.
• Smart Locator Scoring: Distinguishes between actual inputs and "distractor" elements (like Search Labs icons).
• Nearby Label Matching: Fills input fields based on the text labels next to them.
• Self-Healing: Uses fuzzy matching for minor UI text changes (e.g., "Log In" vs "Login").
• Automatic Device Reset: Automatically presses the Home button before and after every test to ensure a clean baseline.
• Zero-Sleep Synchronization: Built-in polling ensures elements are ready before interaction.

---

🖥️ Live Monitoring & Evidence

Live Desktop Mirroring

See your phone's screen in a window on your desktop (Mac/Windows) during execution.

• Requirement: scrcpy (Installed automatically via flowpilot setup).
• Enable: Set mirror_screen: true in your flowpilot.yaml.

Automated Evidence

• Screen Recording (MP4): Every test is recorded with hardware encoding (zero performance drop). Includes professional 1s padding.
• Retention Policy: Automatically purges recordings older than 5 days (configurable) to save disk space.
• Smart Screenshots: Captures specific UI states into .flowpilot/screenshots/.
• Selective Cleanup: Wipes temporary flows and recent screenshots before each run while preserving your video history.

---

⚙️ Configuration (flowpilot.yaml)

Clients can overwrite framework behavior by placing a flowpilot.yaml in their project root:

project_name: "My Custom App"
output_dir: ".flowpilot"

# Features
record_video: true
mirror_screen: true

# Data Retention
recording_retention_days: 5

# Smart Engine Settings
auto_scroll: true
timeout: 30

---

🛠 Usage Guide

1. Smart Environment Setup

Automatically install ADB, Scrcpy, and all Python dependencies (Supports Mac and Windows):

flowpilot setup

2. Initialize Project

flowpilot init

3. Create a test (tests/test_demo.py)

def test_google_search(mobile):
    mobile.launch_app()
    mobile.fill("Search", "FlowPilot Mobile")
    mobile.press_key("Enter")
    mobile.screenshot("results")

4. Run Tests

flowpilot run tests/test_demo.py -s

---

📖 Public API Reference

Category	Method	Description	Example
Lifecycle	launch_app(pkg)	Opens a specific app (defaults to Chrome).	mobile.launch_app()
	home()	Returns to the device Home Screen.	mobile.home()
	back()	Simulates the hardware Back button.	mobile.back()
	navigate(url)	Opens a specific URL in the browser.	mobile.navigate("https://google.com")
Interactions	tap(target)	Smart Tap: Auto-scrolls and waits for visibility.	mobile.tap("Settings")
	fill(target, val)	Smart Fill: Finds nearest input to a label.	mobile.fill("Username", "admin")
	fill_focused(val)	Active Field: Types into currently focused input.	mobile.fill_focused("secret")
	press_key(key)	Presses hardware keys (Enter, Home, Back).	mobile.press_key("Enter")
	clear(target)	Clears text from an input field.	mobile.clear("Search")
Gestures	open_notifications()	Pulls down the notification shade (Left).	mobile.open_notifications()
	open_quick_settings()	Pulls down full Quick Settings (Center).	mobile.open_quick_settings()
	swipe_right()	Horizontal swipe to see widgets/discover.	mobile.swipe_right()
	swipe_left()	Horizontal swipe to return home.	mobile.swipe_left()
	scroll_down()	Performs a smart downward scroll.	mobile.scroll_down()
Discovery	get_screen_text()	Extracts all visible text from the screen.	texts = mobile.get_screen_text()
	find_text(target)	Checks if specific text is visible (True/False).	if mobile.find_text("Login"):
	list_elements(type)	Returns a list of all visible elements.	mobile.list_elements("button")
Verification	wait_for(target)	Polls until the element is found.	mobile.wait_for("Success")
	visible(target)	Asserts that an element is on screen.	mobile.visible("Profile")
	visual_assert(id)	Visual Check: Compares with a baseline image.	mobile.visual_assert("login")
Media	screenshot(name)	Saves a screenshot to .flowpilot/screenshots/.	mobile.screenshot("step_1")

---

🤖 CLI Commands

Command	Description
flowpilot setup	Automatically installs ADB, Scrcpy, and requirements.
flowpilot interactive	New: Start a live step-by-step automation session.
flowpilot init	Scaffolds a new project structure.

| flowpilot run | Executes tests with smart logs. | | flowpilot doctor | Checks ADB and device connectivity. | | flowpilot devices | Lists all connected physical Android devices. | | flowpilot report | Generates a rich HTML summary of test runs. |

---

🛡 Engineering Principles

1. Hide Complexity: Zero YAML or runtime engine logic exposed.
2. Text-First: Locators prioritize display text over brittle XPaths.
3. Hardware-Accelerated: Native MP4 capture and Scrcpy mirroring with zero host lag.
4. Resilient Reset: Automated pre/post Home screen logic for repeatability.