Metadata-Version: 2.4
Name: flowpilot-mobile
Version: 1.2.0
Summary: Modern, Intelligent Mobile Automation Framework (Compiled)
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
Requires-Dist: requests>=2.31.0
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: summary

# 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
```bash
pip install flowpilot-mobile
```

### 2. Initialize your Project
Initialize a new project folder with all necessary configurations:
```bash
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:
```yaml
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`)
```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.
