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)

```bash
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)

```bash
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