proxmox/docs/04-configuration/UDM_PRO_AUTOMATION_IMPROVEMENTS.md

UDM Pro Automation Improvements

Last Updated: 2026-01-14
Status: ✅ Enhanced with Context-Aware Detection

---

Summary

The automation script has been improved with:

1. ✅ Enhanced context-aware detection - Smart methods before brute force
2. ✅ Optional aggressive auto-click - Only enabled when explicitly requested
3. ✅ Comprehensive documentation - Clear warnings and usage guidelines

---

Detection Strategy Order

The script now follows this priority order:

1. Standard Selectors (50+ methods)

• Text-based selectors
• Aria-label selectors
• Data attributes
• Class-based patterns
• Icon-based detection
• XPath selectors

2. Context-Aware Detection (NEW - Default)

• Near "Static Routes" text: Finds buttons in parent/sibling elements
• Table headers: Specifically looks for buttons in table headers
• Prioritization: Plus icons, table headers, icon-only buttons get priority
• Smart filtering: Skips known non-Add buttons

3. JavaScript Evaluation

• Evaluates page structure
• Finds buttons with specific characteristics
• Tries multiple click methods

4. Aggressive Auto-Click (OPTIONAL - Last Resort)

• Default: Disabled
• Enable: AGGRESSIVE_AUTO_CLICK=true
• Systematically clicks through buttons
• Only used when explicitly enabled

5. Manual Intervention (Fallback)

• Waits for user to click Add button
• Automatically detects when form appears
• Continues automatically

---

Usage

Default Mode (Recommended)

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

What happens:

1. Tries 50+ standard selectors
2. Tries context-aware detection (near "Static Routes", table headers)
3. Tries JavaScript evaluation
4. If all fail: Waits for manual Add button click (120 seconds)
5. Automatically continues after form appears

Aggressive Mode (Last Resort)

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

What happens:

1. Tries all standard methods
2. Tries context-aware detection
3. Tries JavaScript evaluation
4. If enabled: Tries aggressive auto-click (clicks through all buttons)
5. If still fails: Waits for manual intervention

---

Environment Variables

Variable	Default	Description
AGGRESSIVE_AUTO_CLICK	false	Enable aggressive auto-click as last resort
HEADLESS	true	Run browser in headless mode
PAUSE_MODE	false	Pause at key points for manual inspection
DRY_RUN	false	Test mode without making changes

---

Risks and Warnings

Aggressive Auto-Click Risks

⚠️ Only enable if absolutely necessary

Risks:

• May click unintended buttons (navigation, settings, etc.)
• Could trigger side effects (opening menus, dialogs, navigating away)
• May be slow (up to 90 seconds testing 30 buttons)
• Could break if UI structure changes
• Browser window may flicker/jump visibly

When to use:

• Standard methods have failed
• Context-aware detection has failed
• You're willing to accept potential side effects
• You're monitoring the browser window

When NOT to use:

• In production without testing
• When UI structure is unknown
• When you need predictable behavior
• When you can't monitor the browser

---

Best Practices

1. Use Default Mode First

• Most reliable and predictable
• Uses smart context-aware detection
• Falls back to manual intervention if needed

2. Identify Selectors Manually

• Use browser DevTools to inspect Add button
• Find stable selector (data attribute, stable class)
• Add to standard selector list
• Most maintainable long-term solution

3. Monitor First Run

• Run with HEADLESS=false first time
• Watch what the script does
• Verify it finds the correct button
• Check for any side effects

4. Use Aggressive Mode Sparingly

• Only when other methods fail
• Monitor browser window
• Be prepared to stop if issues occur
• Document any side effects

---

Troubleshooting

Context-Aware Detection Not Finding Button

1. Check page structure:

   • Verify "Static Routes" text is visible
   • Check if table headers exist
   • Inspect button location in DevTools

2. Improve selectors:

   • Manually identify button selector
   • Add to standard selector list
   • Update context-aware detection logic

3. Enable aggressive mode:

   • Use as last resort
   • Monitor carefully
   • Document results

Aggressive Auto-Click Causing Issues

1. Stop the script immediately

2. Check what was clicked:

   • Review screenshots
   • Check browser state
   • Verify no unintended changes

3. Use manual intervention instead:

   • Run with HEADLESS=false
   • Click Add button manually
   • Script will continue automatically

---

Performance Comparison

Method	Speed	Reliability	Side Effects	Recommended
Standard Selectors	⚡ Fast	⭐⭐⭐ High	✅ None	✅ Yes
Context-Aware	⚡ Fast	⭐⭐⭐ High	✅ None	✅ Yes
JavaScript Eval	⚡ Fast	⭐⭐ Medium	✅ None	✅ Yes
Aggressive Auto-Click	🐌 Slow	⭐ Low	⚠️ Possible	⚠️ Last Resort
Manual Intervention	⚡ Fast	⭐⭐⭐ High	✅ None	✅ Yes

---

Future Improvements

1. Manual Selector Identification

   • Use DevTools to find stable selector
   • Add to standard selector list
   • Remove need for aggressive auto-click

2. Direct URL Navigation

   • If UniFi exposes direct URL for Add Route form
   • Navigate directly, skip button detection

3. API-Based Approach

   • If UniFi adds API support for static routes
   • Use API instead of browser automation

---

Last Updated: 2026-01-14
Status: ✅ Improvements Complete