roa2web-service-auto/reports-app/frontend/ANDROID_QUICK_START.md

# Android Testing - Quick Start (5 Minutes)

Ghid rapid pentru testarea ROA2WEB pe telefon Android real prin ADB WiFi.

## Prerequisites

- Windows 10/11
- Android phone (Android 10+)
- Phone and computer on same WiFi network

---

## Step 1: Install ADB on Windows (2 min)

**Windows PowerShell:**

```powershell
# Install ADB Platform Tools
winget install Google.PlatformTools

# Verify installation
adb version
```

---

## Step 2: Enable Wireless Debugging on Phone (1 min)

**On Android phone:**

```
Settings -> About phone -> Tap "Build number" 7 times
Settings -> Developer options -> Enable "USB debugging"
Settings -> Developer options -> Enable "Wireless debugging"
```

---

## Step 3: Connect Phone via WiFi (1 min)

**On phone:**
```
Settings -> Developer options -> Wireless debugging -> "Pair device with pairing code"
```

You'll see:
- **Pairing code:** 6 digits (e.g., 123456)
- **IP & Port:** e.g., 10.0.20.114:37639

**In Windows PowerShell:**

```powershell
# Pair (first time only)
adb pair 10.0.20.114:37639
# Enter the 6-digit code when prompted

# After pairing, check the MAIN port in "Wireless debugging" screen
# It's different from pairing port!

# Connect (use the wireless debugging port, NOT pairing port)
adb connect 10.0.20.114:XXXXX

# Verify
adb devices
# Should see: 10.0.20.114:XXXXX    device
```

---

## Step 4: Setup Port Forwarding (1 min)

**Windows PowerShell (Administrator):**

```powershell
# A) ADB port forwarding (Chrome DevTools)
adb forward tcp:9222 localabstract:chrome_devtools_remote

# B) Windows port proxy (for WSL/MCP access)
netsh interface portproxy add v4tov4 listenport=9222 listenaddress=0.0.0.0 connectport=9222 connectaddress=127.0.0.1

# C) Firewall rule
New-NetFirewallRule -DisplayName "Chrome-DevTools-Android" -Direction Inbound -LocalPort 9222 -Protocol TCP -Action Allow

# D) Port forwarding for app access from phone
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=172.18.251.234
netsh interface portproxy add v4tov4 listenport=8001 listenaddress=0.0.0.0 connectport=8001 connectaddress=172.18.251.234

# E) Firewall rules for app
New-NetFirewallRule -DisplayName "ROA2WEB-Frontend-WSL" -Direction Inbound -LocalPort 3000 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "ROA2WEB-Backend-WSL" -Direction Inbound -LocalPort 8001 -Protocol TCP -Action Allow

# Verify
netsh interface portproxy show all
```

**OR use automated setup script:**

```powershell
cd E:\proiecte\roa2web\roa2web\reports-app\frontend\scripts
.\android-test-setup.ps1
```

---

## Step 5: Test on Phone

**In WSL (start app):**

```bash
cd /mnt/e/proiecte/roa2web/roa2web
./start-dev.sh
```

**On phone Chrome:**
```
http://localhost:3000
```

---

## Step 6: Configure Chrome DevTools MCP (Optional)

For Claude Code to control Chrome on phone:

**Edit:** `~/.claude.json` (in WSL)

Find `chrome-devtools-android` and ensure it uses physical Windows IP:

```json
"chrome-devtools-android": {
  "type": "stdio",
  "command": "npx",
  "args": [
    "chrome-devtools-mcp@latest",
    "--browser-url",
    "http://10.0.20.144:9222"
  ]
}
```

Replace `10.0.20.144` with YOUR Windows IP:

```powershell
# Get your Windows IP
ipconfig | findstr "IPv4"
```

**Reload Claude Code:** Ctrl+Shift+P -> "Developer: Reload Window"

---

## Daily Workflow

**Morning setup:**
```powershell
# Windows PowerShell
adb connect 10.0.20.114:XXXXX  # Your phone IP:PORT
adb forward tcp:9222 localabstract:chrome_devtools_remote
```

**Start app (WSL):**
```bash
cd /mnt/e/proiecte/roa2web/roa2web
./start-dev.sh
```

**On phone:** Open Chrome -> `http://localhost:3000`

**In Claude Code:** Ask for screenshots directly via MCP:
```
"Folosind chrome-devtools-android, fa screenshot de pe telefon"
```

**End of day cleanup:**
```bash
# WSL
cd /mnt/e/proiecte/roa2web/roa2web/reports-app/frontend
./scripts/android-disconnect.sh
```

---

## Troubleshooting

### "adb: device unauthorized"
- Unlock phone
- Accept "Allow USB debugging" prompt
- Check "Always allow from this computer"

### "Connection refused"
- Phone and PC must be on SAME WiFi network
- Restart "Wireless debugging" on phone
- Re-pair and reconnect

### "localhost:3000 doesn't load on phone"
Try Windows IP instead:
```
http://10.0.20.144:3000
```

### "Chrome DevTools MCP doesn't connect"
```bash
# Test from WSL
curl http://10.0.20.144:9222/json/version
```

If fails, check Windows port proxy and firewall rules.

---

## Summary

| Component | Location | Command |
|-----------|----------|---------|
| **ADB Install** | Windows | `winget install Google.PlatformTools` |
| **Connect Phone** | Windows | `adb connect IP:PORT` |
| **Port Forwarding** | Windows Admin | `netsh interface portproxy ...` |
| **Setup Script** | Windows | `.\android-test-setup.ps1` |
| **Start App** | WSL | `./start-dev.sh` |
| **Screenshot** | Claude Code | Ask via MCP (inline, no file save) |

---

**Your physical IP addresses (fill in):**
- Windows IP: `___________________` (from `ipconfig`)
- Phone IP: `___________________` (from Wireless debugging)
- WSL IP for app: `172.18.251.234` (from `ip route show | grep default`)

---

For detailed guide, see: `tests/ANDROID_TESTING_GUIDE.md`