proxmox/docs/04-configuration/UDM_PRO_AUTOMATION_COMPLETE.md

UDM Pro Browser Automation - Complete Solution

Last Updated: 2026-01-14
Status: ✅ Ready to Use

---

Summary

The browser automation framework for UDM Pro static route configuration is complete and ready to use. The framework includes:

• ✅ Full authentication and navigation
• ✅ Comprehensive button detection (50+ strategies)
• ✅ Manual intervention mode (when automatic detection needs help)
• ✅ Automatic form filling and submission
• ✅ Complete error handling and recovery

---

Quick Start: Two Options

Option 1: Fully Automated (When Button Selector is Known)

cd /home/intlc/projects/proxmox
UNIFI_USERNAME=unifi_api UNIFI_PASSWORD='L@kers2010$$' \
  HEADLESS=true \
  node scripts/unifi/configure-static-route-playwright.js

Note: This requires the Add button selector to be identified first (see Option 2).

Option 2: Manual Add Button Click (Works Now)

cd /home/intlc/projects/proxmox
./scripts/unifi/run-with-manual-add.sh

Or manually:

cd /home/intlc/projects/proxmox
UNIFI_USERNAME=unifi_api UNIFI_PASSWORD='L@kers2010$$' \
  HEADLESS=false PAUSE_MODE=true \
  node scripts/unifi/configure-static-route-playwright.js

What happens:

1. Script logs in automatically
2. Navigates to Static Routes page
3. Pauses and waits for you to click the Add button
4. Automatically detects when form appears
5. Fills form fields automatically
6. Clicks Save
7. Verifies route was created

Time required: ~30 seconds of your time (just click Add button)

---

How It Works

Step-by-Step Process

1. Authentication ✅

   • Logs in with unifi_api account
   • Handles SSL certificate issues
   • Verifies successful login

2. Navigation ✅

   • Navigates to Settings → Routing & Firewall → Static Routes
   • Waits for page to fully load
   • Handles redirects and page state

3. Add Button Detection ⚠️

   • Tries 50+ automatic detection strategies
   • If not found, enters manual intervention mode
   • Waits up to 120 seconds for manual click
   • Automatically detects when form appears

4. Form Filling ✅

   • Fills route name: "Route to VLAN 11"
   • Fills destination: "192.168.11.0/24"
   • Fills gateway: "192.168.11.1"
   • Handles all form fields automatically

5. Submission ✅

   • Clicks Save button
   • Waits for confirmation
   • Verifies route was created

6. Verification ✅

   • Checks route list for new route
   • Confirms route details
   • Reports success

---

Configuration

The script is configured to create:

• Name: Route to VLAN 11
• Destination Network: 192.168.11.0/24
• Gateway: 192.168.11.1
• Distance: 1 (default)

To change these values, edit ROUTE_CONFIG in scripts/unifi/configure-static-route-playwright.js:

const ROUTE_CONFIG = {
  name: 'Route to VLAN 11',
  destination: '192.168.11.0/24',
  gateway: '192.168.11.1',
  distance: 1,
};

---

Environment Variables

• UNIFI_UDM_URL: UDM Pro URL (default: https://192.168.0.1)
• UNIFI_USERNAME: Username (default: unifi_api)
• UNIFI_PASSWORD: Password (required)
• UNIFI_BROWSER_USERNAME: Override username for browser
• UNIFI_BROWSER_PASSWORD: Override password for browser
• DRY_RUN: Set to true to test without making changes
• HEADLESS: Set to false to see browser (default: true)
• PAUSE_MODE: Set to true to pause for manual intervention

---

Troubleshooting

Script Can't Find Add Button

Solution: Use manual intervention mode:

HEADLESS=false PAUSE_MODE=true node scripts/unifi/configure-static-route-playwright.js

The script will wait for you to click Add, then continue automatically.

Form Doesn't Appear After Clicking Add

1. Check browser console for errors (F12)
2. Verify you're on the Static Routes page
3. Try refreshing the page
4. Check if Add button requires specific permissions

Navigation Fails

1. Verify UDM Pro URL is correct
2. Check network connectivity
3. Verify credentials are correct
4. Check if UDM Pro requires different authentication

Form Fields Not Filling

1. Check screenshot: scripts/unifi/screenshots/08-add-route-form.png
2. Verify form field names haven't changed
3. Check browser console for errors

---

Screenshots

Screenshots are automatically saved to scripts/unifi/screenshots/:

• 01-login-page.png - Login page
• 02-credentials-filled.png - After filling credentials
• 03-after-login.png - After successful login
• 05-routing-page.png - Routing settings page
• 06-static-routes-page.png - Static Routes page
• 07-before-add-button.png - Before searching for Add button
• 08-add-route-form.png - Route form (when it appears)
• 09-waiting-for-manual-add-click.png - Waiting for manual click
• 10-form-filled.png - After filling form
• 11-route-saved.png - After saving route
• error-state.png - If an error occurs

---

Tools Available

1. Main Automation Script

File: scripts/unifi/configure-static-route-playwright.js

• Complete automation with manual intervention fallback

2. Visual Page Analyzer

File: scripts/unifi/analyze-page-visually.js

• Interactive tool to identify Add button selector
• Highlights buttons and tests each one

3. Strategy Tester

File: scripts/unifi/test-all-add-button-strategies.js

• Tests all buttons and strategies automatically
• Reports which strategy works

4. Quick Start Script

File: scripts/unifi/run-with-manual-add.sh

• Convenient wrapper for manual intervention mode

---

Next Steps (Optional)

To Make It Fully Automated

1. Identify Add Button Selector:

   node scripts/unifi/analyze-page-visually.js
   

   • Test buttons interactively
   • Note the selector when form appears

2. Update Script:

   • Add selector to addButtonSelectors array in configure-static-route-playwright.js
   • Test with HEADLESS=true

3. Verify:

   • Run full automation
   • Confirm it works without manual intervention

---

Success Criteria

✅ Automation is successful when:

• Script navigates to Static Routes page
• Form appears (either automatically or after manual click)
• Form is filled correctly
• Route is saved successfully
• Route appears in routes list

---

Support

For issues or questions:

1. Check screenshots in scripts/unifi/screenshots/
2. Review script logs for error messages
3. Use HEADLESS=false to see what's happening
4. Use PAUSE_MODE=true for manual intervention

---

Last Updated: 2026-01-14
Status: ✅ Complete and Ready to Use