UnifiCLI/TESTING.md

# UnifiCLI — Testing Guide

## Sideloading the Module

### Prerequisites

Confirm PowerShell 7+ is installed (required — Windows PowerShell 5.x is not supported):

```powershell
$PSVersionTable.PSVersion
# Major should be 7 or higher
```

If you need to install it: https://aka.ms/powershell

---

### Option A — Import for the current session only

Use this while developing or sharing with colleagues who just want to try it out.
No files are copied anywhere; the module is gone when the PS window closes.

```powershell
# Clone or copy the repo, then from the repo root:
Import-Module .\UnifiCLI.psd1 -Force

# Confirm it loaded
Get-Module UnifiCLI
```

---

### Option B — Install to your user module path (persists across sessions)

This makes `Import-Module UnifiCLI` work from any directory, any window.

```powershell
# Find your user module directory
$env:PSModulePath -split ';'
# Pick the one under your profile, e.g. C:\Users\<you>\Documents\PowerShell\Modules

# Copy the whole repo folder there
$dest = "$HOME\Documents\PowerShell\Modules\UnifiCLI"
Copy-Item -Path 'C:\path\to\UnifiCLI' -Destination $dest -Recurse -Force

# Now load it from anywhere
Import-Module UnifiCLI -Force
```

To uninstall:

```powershell
Remove-Item "$HOME\Documents\PowerShell\Modules\UnifiCLI" -Recurse -Force
```

---

### Verify the module loaded correctly

```powershell
Get-Command -Module UnifiCLI
# Should list: Connect-UnifiController, Disconnect-UnifiController,
#              Get-UnifiConnectionStatus, Get-UnifiSite, Get-UnifiDevice,
#              Get-UnifiClient, Get-UnifiWlan, Set-UnifiWlanPassword, Invoke-UnifiCli

Get-Alias unifi-cli
# Should resolve to Invoke-UnifiCli
```

---

## Phase 1 — Connect / Disconnect / Status

### 1.1  Help output (no arguments)

```powershell
unifi-cli
```

**Expected:** Usage block listing all available commands. No errors.

---

### 1.2  Status when not connected

```powershell
unifi-cli status
# or
Get-UnifiConnectionStatus
```

**Expected:** Red "Not connected" message with a hint to run `connect`.

---

### 1.3  Connect — credential prompt

```powershell
unifi-cli connect 192.168.1.1 --insecure
```

**Expected:** A credential prompt appears. After entering valid admin credentials, output shows:
```
Connected to https://192.168.1.1:443 as <username>
```

---

### 1.4  Connect — inline credential (useful for scripting, not recommended for shared sessions)

```powershell
$cred = Get-Credential
Connect-UnifiController -Controller 192.168.1.1 -Credential $cred -SkipCertificateCheck
```

**Expected:** Same green "Connected" output without a second prompt.

---

### 1.5  Connect with non-default port

```powershell
unifi-cli connect 192.168.1.1 --port 8443 --insecure
```

**Expected:** Connects to `https://192.168.1.1:8443`. URL shown in status reflects the port.

---

### 1.6  Status when connected

```powershell
unifi-cli status
```

**Expected:** All fields populated — Controller, Username, Connected timestamp, Site (default).
If `--insecure` was used, a yellow TLS warning line should appear.

---

### 1.7  Connect with --save

```powershell
unifi-cli connect 192.168.1.1 --insecure --save
```

**Expected:** Connects successfully. Verify the config file was written (password must NOT appear):

```powershell
Get-Content "$env:APPDATA\UnifiCLI\config.json"
# Should show ControllerUrl, Username, SkipCertificateCheck — no password field
```

---

### 1.8  Disconnect

```powershell
unifi-cli disconnect
```

**Expected:** Yellow "Disconnected." message.

---

### 1.9  Status after disconnect

```powershell
unifi-cli status
```

**Expected:** Back to red "Not connected" state.

---

### 1.10  Disconnect when not connected

```powershell
unifi-cli disconnect
```

**Expected:** Warning saying "Not currently connected to a controller." — no crash.

---

### 1.11  Wrong password

```powershell
Connect-UnifiController -Controller 192.168.1.1 -SkipCertificateCheck `
    -Credential (New-Object PSCredential('admin', (ConvertTo-SecureString 'wrongpassword' -AsPlainText -Force)))
```

**Expected:** Error message from the controller (e.g. "Login rejected by controller: Invalid credentials"). 
Session must NOT be set — verify with `unifi-cli status` showing "Not connected".

---

### 1.12  Unreachable host

```powershell
unifi-cli connect 10.255.255.1 --insecure
```

**Expected:** Connection error (timeout or refused). No crash, no partial session state.
Verify `unifi-cli status` still shows "Not connected".

---

### 1.13  Phase 2 stub — should not crash

```powershell
# Connect first (1.3 or 1.4), then:
unifi-cli list sites
```

**Expected:** Yellow warning: "Get-UnifiSite is not yet implemented (Phase 2)." — no error.

---

### 1.14  Phase 2 stub — not connected

```powershell
# Without connecting first:
unifi-cli list sites
```

**Expected:** Error: "Not connected. Run Connect-UnifiController first."

---

## Phase 2 — Read Commands  *(complete once Phase 2 is built)*

### 2.1  List all sites

```powershell
unifi-cli list sites
# or
Get-UnifiSite
```

**Expected:** Table or list of sites with at minimum Site ID and Description columns.
Multi-site controllers should show multiple rows. Single-site will show just `default`.

---

### 2.2  List devices

```powershell
unifi-cli list devices
# or
Get-UnifiDevice -Site default
```

**Expected:** List of adopted Unifi devices (APs, switches, gateways) with name, model, MAC, and state.

---

### 2.3  List active clients

```powershell
unifi-cli list clients
# or
Get-UnifiClient -Site default -Active
```

**Expected:** List of currently connected clients with hostname, IP, MAC, SSID or port.

---

### 2.4  List WLANs

```powershell
unifi-cli list wlans
# or
Get-UnifiWlan -Site default
```

**Expected:** Table of SSIDs with name, enabled state, security mode.
Passwords should NOT appear in default output.

---

### 2.5  Filter WLAN by SSID name

```powershell
Get-UnifiWlan -Site default -Ssid 'georgiou-guest'
```

**Expected:** Returns only the matching SSID entry.

---

### 2.6  Non-default site

```powershell
Get-UnifiDevice -Site <site-id-from-2.1>
```

**Expected:** Devices scoped to that site, not all sites combined.

---

## Phase 3 — Write Commands  *(complete once Phase 3 is built)*

### 3.1  Rotate password — single site, prompt

```powershell
Set-UnifiWlanPassword -Ssid 'georgiou-guest' -Site default
```

**Expected:** Secure password prompt appears. After entry, success message.
Verify by running `Get-UnifiWlan -Ssid 'georgiou-guest'` and confirming the new password.

---

### 3.2  Rotate password — inline SecureString

```powershell
$newPass = ConvertTo-SecureString 'NewP@ss99' -AsPlainText -Force
Set-UnifiWlanPassword -Ssid 'georgiou-guest' -Site default -NewPassword $newPass
```

**Expected:** Password updated without prompting.

---

### 3.3  WhatIf — no change should be made

```powershell
Set-UnifiWlanPassword -Ssid 'georgiou-guest' -Site default -WhatIf
```

**Expected:** Output describes what would happen. No API call is made. Password unchanged.

---

### 3.4  Rotate across all sites

```powershell
Get-UnifiSite | ForEach-Object {
    Set-UnifiWlanPassword -Ssid 'georgiou-guest' -Site $_.Name -NewPassword $newPass
}
```

**Expected:** Each site processed in sequence. Sites without the target SSID report "not found" rather than erroring.

---

### 3.5  SSID not found on site

```powershell
Set-UnifiWlanPassword -Ssid 'ssid-that-does-not-exist' -Site default
```

**Expected:** Clear message that the SSID was not found. No error thrown, no partial update.

---

## Regression Checks (run after any phase)

| Check | Command | Pass condition |
|---|---|---|
| Module loads | `Import-Module .\UnifiCLI.psd1 -Force` | No errors |
| All commands present | `Get-Command -Module UnifiCLI` | 9 functions listed |
| Alias works | `Get-Alias unifi-cli` | Resolves to `Invoke-UnifiCli` |
| Help renders | `unifi-cli` | Usage block with no errors |
| Status clean | `unifi-cli status` (not connected) | "Not connected" — no exceptions |
| Config has no password | `Get-Content "$env:APPDATA\UnifiCLI\config.json"` | No `password` key present |