Metadata-Version: 2.4
Name: flowpilot-mobile-framework
Version: 1.1.2
Summary: Modern, Intelligent Mobile Automation Framework
Author-email: Niranjan Kumar <niranjan4@outlook.in>
License: MIT
Project-URL: Homepage, https://github.com/niranjangs4/flowpilot-mobile
Project-URL: Documentation, https://github.com/niranjangs4/flowpilot-mobile#readme
Keywords: mobile,automation,android,smart,testing,pytest
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Testing
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pytest>=8.0.0
Requires-Dist: pytest-xdist>=3.5.0
Requires-Dist: rich>=13.0.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: cryptography>=41.0.0

# 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
```bash
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:

```yaml
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):
```bash
flowpilot setup
```

### 2. Initialize Project
```bash
flowpilot init
```

### 3. Create a test (`tests/test_demo.py`)
```python
def test_google_search(mobile):
    mobile.launch_app()
    mobile.fill("Search", "FlowPilot Mobile")
    mobile.press_key("Enter")
    mobile.screenshot("results")
```

### 4. Run Tests
```bash
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.
