Metadata-Version: 2.4
Name: flowpilot-mobile
Version: 1.2.12
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

FlowPilot Mobile is a high-performance, intelligent mobile automation framework built for speed, privacy, and simplicity. Unlike other frameworks that wrap heavy external engines, FlowPilot uses a custom-built, zero-dependency **Intelligent ADB Runtime**.

## 🌟 Why FlowPilot?

- **Lightweight & Fast:** No Java, no Node.js, and no Maestro/Appium binaries required. It talks directly to your device via ADB, making it significantly faster and easier to set up.
- **Privacy-First:** Designed for enterprise security. It features an anonymous licensing system with zero telemetry and no hardware/user data collection.
- **Intelligent Locators:** A built-in scoring engine that handles distractors automatically. It finds what you want (e.g., "Search") and ignores what you don't (e.g., "Search History").
- **Zero-Sleep Synchronization:** Built-in polling and smart-waits ensure elements are ready before interaction. No more manual `sleep()` calls.
- **Auto-Scroll Search:** Automatically swipes and retries if an element is off-screen.

---

## 🚀 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. Write your first test
Create a file `tests/test_demo.py`:
```python
def test_google_search(mobile):
    mobile.launch_app()
    mobile.navigate("https://www.google.com")
    mobile.fill("Search", "FlowPilot Mobile")
    mobile.press_key("Enter")
    mobile.visible("github.com")
```

---

## 🤖 AI-Assisted Automation (TEST_GEN_PROMPT)

FlowPilot 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 using the integrated `scrcpy` support.
- **Enable:** Set `mirror_screen: true` in your `flowpilot.yaml`.

### Automated Evidence
- **Hardware-Accelerated Recording (MP4)**: Every test is recorded with hardware encoding (zero performance drop). Includes professional 1s padding.
- **Smart Screenshots**: Captures specific UI states into `.flowpilot/screenshots/`.
- **Retention Policy**: Automatically purges recordings older than **5 days** (configurable) to save disk space.

---

## 📖 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()` |
| **Relational** | `below(anchor)` | Maestro-style relational selection. | `mobile.below("Login").tap()` |
| **Discovery** | `get_text(target)` | **Data Extraction**: Gets text/ID value. | `mobile.get_text("login_id")` |
| | `get_screen_text()` | Gets all visible text on screen. | `mobile.get_screen_text()` |

---

## Configuration (`flowpilot.yaml`)

```yaml
project_name: "My Custom App"

# Manual Tool Paths
tools:
  adb_path: ""
  # Supports both folder path OR full .exe path
  scrcpy_path: "C:\\path\\to\\scrcpy_folder" 
```
---

## 🛡 Engineering Principles
1. **WHAT, not HOW**: Focus on test intent; FlowPilot handles the low-level ADB coordination.
2. **Privacy-First**: Anonymous licensing, zero telemetry, no system fingerprinting.
3. **Nuitka Protected**: Core logic is compiled into high-performance binaries for security.
4. **Resilient Reset**: Automated pre/post Home screen logic for clean repeatable baselines.

---
*Built for engineers who value speed, privacy, and clean code.*
