flowpilot-mobile 1.2.0

Modern, Intelligent Mobile Automation Framework (Compiled)

FlowPilot Mobile

Modern, Python-first mobile automation framework. Provides clean Playwright-style APIs for smart mobile automation with AI-assisted test generation.

🚀 Quick Start

1. Install via pip

pip install flowpilot-mobile

2. Initialize your Project

Initialize a new project folder with all necessary configurations:

flowpilot setup --project_folder my_tests

3. Configure Tool Paths

Open my_tests/flowpilot.yaml and specify your manual paths for ADB and Scrcpy if they are not in your system PATH:

tools:
  adb_path: "C:\\path\\to\\adb.exe"
  scrcpy_path: "C:\\path\\to\\scrcpy.exe"

---

🌟 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.

---

🤖 AI-Assisted Automation (TEST_GEN_PROMPT)

FlowPilot now supports Instant Test Generation via AI. Every project initialized with flowpilot setup includes a TEST_GEN_PROMPT.md file.

1. Copy the content of TEST_GEN_PROMPT.md.
2. Paste it into Gemini or ChatGPT.
3. Provide your manual test steps or describe a screen recording.
4. Result: The AI will generate a complete FlowPilot Python test script for you.

---

🖥️ Live Monitoring & Evidence

Live Desktop Mirroring

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

• Enable: Set mirror_screen: true in your flowpilot.yaml.
• Manual Path: Configure scrcpy_path in flowpilot.yaml if needed.

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)

project_name: "My Custom App"

# Manual Tool Paths
tools:
  adb_path: ""
  scrcpy_path: ""

# Evidence & Storage
output_dir: ".flowpilot"
recordings_dir: ".flowpilot/recordings"
screenshots_dir: ".flowpilot/screenshots"

# Features
record_video: true
mirror_screen: true

# Smart Engine Settings
auto_scroll: true
timeout: 30

---

📖 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")
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()
	scroll_down()	Performs a smart downward scroll.	mobile.scroll_down()
Media	screenshot(name)	Saves a screenshot to .flowpilot/screenshots/.	mobile.screenshot("step_1")

---

🤖 CLI Commands

Command	Description
flowpilot setup	Initializes a new project folder and generates configurations.
flowpilot interactive	Start a live step-by-step automation session.
flowpilot run	Executes tests with smart logs.
flowpilot devices	Lists all connected physical Android devices.

---

🛡 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.