visual-sonar 1.0.0

WVD/Citrix Remote Desktop Automation using Computer Vision

Visual Sonar 🔊

Automate WVD/Citrix remote desktop sessions using Computer Vision — no DOM access, no server agents, no licensing fees.

Visual Sonar "echolocates" form fields by pressing TAB and detecting visual focus changes. Works where Selenium and traditional RPA tools can't.

---

✨ Features

Feature	Description
🎯 Visual Field Detection	Detects fields by screen diff when focus changes
📊 Data-Driven Testing	Run same test with multiple data sets (CSV/JSON)
🔍 OCR Text Extraction	Extract text from screen (pytesseract/easyocr)
🖥️ WVD Simulator	Test safely without real remote desktop
🔒 Secrets Scrubbing	Passwords never appear in logs
📸 Step Screenshots	Every action captured for debugging
⚡ DPI Aware	Per-monitor scaling support

---

🚀 Quick Start

Option A: Install from PyPI (Recommended)

pip install visual-sonar

Then use:

visual-sonar map
visual-sonar run
visual-sonar --help

Option B: Install from Source

git clone https://github.com/godhiraj-code/wvdautomation.git
cd wvdautomation
pip install -e .

2. Map Your Form

python visual_sonar.py map

Name fields as name:type (types: text, click, toggle, dropdown, double_click)

3. Create Input

{
    "username": "[e-mail]",
    "password": "SecretPass123",
    "signin": true
}

4. Run

python visual_sonar.py run

---

📋 Commands

Command	Description
map	Interactive field mapping
run [file.json]	Execute automation
list	Show available test cases
batch <data.csv>	Data-driven batch testing
extract screen	OCR extract from full screen
extract region x y w h	OCR extract from region
help	Show full help

---

🧪 Testing Without Remote Desktop

Use the built-in simulator:

# Terminal 1 - Start simulator
python wvd_simulator.py

# Terminal 2 - Map and run
python visual_sonar.py map
python visual_sonar.py run

---

📊 Data-Driven Testing

Run same test with multiple credentials:

Create test_cases/users.csv:

username,password,signin
[e-mail],pass1,true
[e-mail],pass2,true

Run batch:

python visual_sonar.py batch test_cases/users.csv

---

🔍 OCR Text Extraction

# Full screen
python visual_sonar.py extract screen

# Specific region
python visual_sonar.py extract region 100 200 300 50

# Verify text exists (for assertions)
python visual_sonar.py extract verify 100 200 300 50 "Success"

Note: Requires pip install pytesseract + Tesseract-OCR

---

🛡️ Safety

• Emergency Stop: Move mouse to TOP-LEFT corner
• FailSafe: Always enabled by default
• Secrets: Never logged, always scrubbed
• Screenshots: Captured on every step

---

📁 Files

File	Purpose	Git
wvd_map.json	Field coordinates	✅
input.json	Your secrets	❌
test_cases/	Test data files	✅
*.png	Debug screenshots	❌

---

🔧 Troubleshooting

Issue	Solution
"No map file"	Run python visual_sonar.py map first
"Screen Unstable"	WVD connection laggy, wait and retry
Wrong coordinates	Remap (resolution/DPI may have changed)
OCR not working	Install Tesseract-OCR software

---

📖 Documentation

• USER_GUIDE.md - Comprehensive beginner guide

---

📜 License

MIT © Visual Sonar Team