Initial commit. Working and linked on PSGallery

2026-05-15 08:53:21 +08:00
commit 7c77363885
17 changed files with 1109 additions and 0 deletions
--- a/TESTING.md
+++ b/TESTING.md
@@ -0,0 +1,368 @@
+# 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 |