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:

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

# 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):

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

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

---

Step 5: Test on Phone

In WSL (start app):

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:

"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:

# Get your Windows IP
ipconfig | findstr "IPv4"

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

---

Daily Workflow

Morning setup:

# Windows PowerShell
adb connect 10.0.20.114:XXXXX  # Your phone IP:PORT
adb forward tcp:9222 localabstract:chrome_devtools_remote

Start app (WSL):

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:

# 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"

# 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