diff --git a/TEST_INSTRUCTIONS.md b/TEST_INSTRUCTIONS.md index fa96a3b..2811d73 100644 --- a/TEST_INSTRUCTIONS.md +++ b/TEST_INSTRUCTIONS.md @@ -1,380 +1,182 @@ # NextWks — Manual Test Instructions -This document contains step-by-step test protocols you can run to verify the system end-to-end. +## Credentials & URLs -## Pre-Test Setup +Copy these as needed: -```bash -# 1. Ensure services are running -systemctl status authelia # Should show: active (running) +``` +Authelia Login: https://auth.lohmar.co.uk +Username: admin +Password: ueM8tLARi5v3orIzvd56w6u6! -# 2. Build NextWks -cd /root/lexton-it/NextWks/src && go build -o ../app/core . +Workspace: https://wks.lohmar.co.uk -# 3. Start NextWks in a separate terminal -cd /root/lexton-it/NextWks/app && ./core +Admin API Token: grep secret_token /opt/nextwks/config.yaml ``` -Keep the server running for all tests below. Replace `` with your admin token from `app/config.yaml` (`admin.secret_token`). +All services are deployed and running via systemd on `172.16.8.22`: +- `authelia` — port 9091 +- `nextwks` — port 8080 --- -## Test Suite 1 — Core Health +## Test Suite 1 — OIDC Login Flow (Browser) -### T1.1 — Health Endpoint -```bash -curl http://localhost:8080/api/health -``` -**Expected:** `{"status":"ok"}` +### T1.1 — Workspace Redirect +Open: `https://wks.lohmar.co.uk/` -### T1.2 — Auth Status Endpoint -```bash -curl http://localhost:8080/auth/status -``` -**Expected:** `{"provider":"Authelia","issuer":"http://127.0.0.1:9091","status":"configured"}` +**Expected:** Redirected to `https://auth.lohmar.co.uk/` login page. -### T1.3 — Authelia Health -```bash -curl http://127.0.0.1:9091/api/health -``` -**Expected:** `{"status":"OK"}` +### T1.2 — Login +Enter credentials: +- Username: `admin` +- Password: `ueM8tLARi5v3orIzvd56w6u6!` -### T1.4 — Service Listening -```bash -ss -tlnp | grep -E '8080|9091' -``` -**Expected:** Both ports listed. 8080 = nextwks, 9091 = authelia. +**Expected:** After login, redirected back to workspace launcher page. Shows "Welcome" heading and app grid with 6 tiles. + +### T1.3 — Session Persistence +Close the browser tab, reopen `https://wks.lohmar.co.uk/`. + +**Expected:** Should go directly to launcher (session cookie still valid). + +### T1.4 — Logout (if implemented) +Visit `https://wks.lohmar.co.uk/auth/logout` + +**Expected:** Redirected to Authelia login page. --- -## Test Suite 2 — Admin API (Bearer Token) +## Test Suite 2 — Admin UI (Browser) -### T2.1 — Protected Access (No Token) +The admin panel requires a bearer token in the `Authorization` header. Get the token: ```bash -curl http://localhost:8080/admin/api/health +ssh root@172.16.8.22 "grep secret_token /opt/nextwks/config.yaml | head -1" +``` + +### T2.1 — Admin Dashboard +With the token set as a header, visit: `https://wks.lohmar.co.uk/admin` + +**Expected:** Dark-themed admin dashboard with user count stat card and sidebar. + +### T2.2 — User Management +Navigate to `https://wks.lohmar.co.uk/admin/users` + +**Expected:** User table loads, shows existing users with status badges. "+ Add User" and "Delete" buttons work via HTMX. + +--- + +## Test Suite 3 — Admin API (Terminal) + +Run from the server or any machine that can reach `172.16.8.22:8080`. + +```bash +TOKEN=$(ssh root@172.16.8.22 "grep secret_token /opt/nextwks/config.yaml | head -1 | sed 's/.*: *\"//;s/\"//'") +API="http://172.16.8.22:8080/admin/api" +``` + +### T3.1 — Health Check +```bash +curl -H "Authorization: Bearer $TOKEN" $API/health +``` +**Expected:** `{"status":"ok","user_count":...}` + +### T3.2 — List Users +```bash +curl -H "Authorization: Bearer $TOKEN" $API/users | python3 -m json.tool +``` +**Expected:** JSON array of users with role, groups, etc. + +### T3.3 — Create User +```bash +curl -X POST $API/users \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"users":[{"username":"testuser","display_name":"Test","email":"test@test.com","role":"user"}]}' +``` +**Expected:** Generated password displayed. User appears in Authelia YAML within seconds. + +### T3.4 — Delete User +```bash +curl -X DELETE -H "Authorization: Bearer $TOKEN" $API/users/testuser +``` +**Expected:** `{"status":"deleted","username":"testuser"}` + +### T3.5 — No Token +```bash +curl $API/health ``` **Expected:** `{"error":"unauthorized"}` (HTTP 401) -### T2.2 — Protected Access (Wrong Token) -```bash -curl -H "Authorization: Bearer wrong-token" http://localhost:8080/admin/api/health -``` -**Expected:** `{"error":"unauthorized"}` (HTTP 401) +--- -### T2.3 — Admin Health (Correct Token) +## Test Suite 4 — Authelia Sync Verification + +### T4.1 — Check YAML ```bash -TOKEN="dev-admin-secret-token" -curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/admin/api/health +ssh root@172.16.8.22 "cat /opt/authelia/users_database.yml" ``` -**Expected:** `{"status":"ok","user_count":...,"authelia_db":"/opt/authelia/users_database.yml"}` +**Expected:** Contains all NextWks users with argon2id password hashes. + +### T4.2 — Create & Check +Create a user via API (T3.3), then immediately: +```bash +ssh root@172.16.8.22 "grep testuser /opt/authelia/users_database.yml" +``` +**Expected:** User appears in YAML within seconds. --- -## Test Suite 3 — User Management +## Test Suite 5 — PWA & Launcher -### T3.1 — List Users (Empty/Fresh) +### T5.1 — Manifest ```bash -curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/admin/api/users +curl -s https://wks.lohmar.co.uk/static/manifest.json | python3 -m json.tool ``` -**Expected:** JSON array (may include bootstrapped Authelia users: `admin`, `clohmar`) +**Expected:** `"name":"Next Workspace"`, `"display":"standalone"` -### T3.2 — Create Single User +### T5.2 — Service Worker ```bash -curl -X POST http://localhost:8080/admin/api/users \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "users": [ - { - "username": "testuser1", - "display_name": "Test User", - "email": "test@example.com", - "groups": "users" - } - ] - }' | python3 -m json.tool +curl -s -o /dev/null -w "%{http_code}" https://wks.lohmar.co.uk/static/sw.js ``` -**Expected:** -```json -{ - "results": [ - { - "username": "testuser1", - "generated_password": "<20-char-password>", - "error": "" - } - ] -} -``` -- ✅ Password is 20 characters -- ✅ No error -- ✅ Save the generated password for later +**Expected:** `200` -### T3.3 — Create Duplicate User -```bash -curl -X POST http://localhost:8080/admin/api/users \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"users":[{"username":"testuser1"}]}' -``` -**Expected:** `{"results":[{"username":"testuser1","error":"user already exists"}]}` +### T5.3 — Install Button +On the launcher page, click the download icon in the header bar (might need PWA trigger or click Install to Desktop at bottom). -### T3.4 — Create Empty Username -```bash -curl -X POST http://localhost:8080/admin/api/users \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"users":[{"username":""}]}' -``` -**Expected:** `{"results":[{"username":"","error":"username is required"}]}` - -### T3.5 — Create Multiple Users -```bash -curl -X POST http://localhost:8080/admin/api/users \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "users": [ - {"username":"user-a","display_name":"User A"}, - {"username":"user-b","display_name":"User B"}, - {"username":"user-c","display_name":"User C"} - ] - }' | python3 -m json.tool -``` -**Expected:** 3 results, all with generated passwords, no errors. - -### T3.6 — List Users After Creation -```bash -curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/admin/api/users | python3 -m json.tool -``` -**Expected:** List includes `testuser1`, `user-a`, `user-b`, `user-c` plus bootstrapped users. - -### T3.7 — Delete User -```bash -curl -X DELETE -H "Authorization: Bearer $TOKEN" http://localhost:8080/admin/api/users/testuser1 -``` -**Expected:** `{"status":"deleted","username":"testuser1"}` - -### T3.8 — Delete Nonexistent User -```bash -curl -X DELETE -H "Authorization: Bearer $TOKEN" http://localhost:8080/admin/api/users/nonexistent -``` -**Expected:** `{"error":"user nonexistent not found"}` (HTTP 404) +**Expected:** Either native install prompt or modal with platform-specific instructions (iOS Safari, Android Chrome, Desktop). --- -## Test Suite 4 — Authelia YAML Sync +## Test Suite 6 — Error Cases -### T4.1 — Verify Sync After Creation +### T6.1 — Invalid Token ```bash -cat /opt/authelia/users_database.yml +curl -H "Authorization: Bearer bad-token" $API/health ``` -**Expected:** The file contains entries for `user-a`, `user-b`, `user-c` (the users created in T3.5). +**Expected:** `{"error":"unauthorized"}` -### T4.2 — Verify Sync After Deletion +### T6.2 — Empty Users Array ```bash -cat /opt/authelia/users_database.yml | grep testuser1 || echo "testuser1 removed" +curl -X POST $API/users -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"users":[]}' ``` -**Expected:** `testuser1 removed` (not in the YAML anymore). +**Expected:** `{"error":"no users provided"}` -### T4.3 — Verify Argon2 Hash Format +### T6.3 — 404 ```bash -grep "password:" /opt/authelia/users_database.yml | head -1 +curl -I https://wks.lohmar.co.uk/nonexistent ``` -**Expected:** `password: "$argon2id$v=19$m=65536,t=3,p=4$...$..."` +**Expected:** HTTP 404 --- -## Test Suite 5 — Admin UI (Browser) +## Results -### T5.1 — Admin Dashboard -Open in browser: -``` -http://localhost:8080/admin -``` -**Note:** You need the bearer token. Configure your browser to add header: -`Authorization: Bearer dev-admin-secret-token` (use browser extension or curl to verify). - -**Expected:** -- Dark-themed dashboard loads -- Shows "Admin Dashboard" with user count stat card -- Sidebar navigation visible (Dashboard, Users) - -### T5.2 — User Management Page -Navigate to `http://localhost:8080/admin/users` - -**Expected:** -- User table loads via HTMX (lazy-load) -- Shows created users with status badges -- "+ Add User" button visible -- Delete buttons with confirmation prompt - -### T5.3 — Create User (UI) -1. Click "+ Add User" button -2. Fill in: Username, Display Name, Email, Groups -3. Click "Create User" - -**Expected:** -- Success alert with generated password shown -- Auto-refreshes the user table after creation - -### T5.4 — Delete User (UI) -1. Click the red "Delete" button next to a test user -2. Confirm the dialog - -**Expected:** -- Row disappears from the table -- User removed from Authelia YAML - ---- - -## Test Suite 6 — OIDC Authentication Flow - -### Prerequisites -Authelia must have the `nextwks` OIDC client registered and running. Verify: -```bash -curl -s http://127.0.0.1:9091/.well-known/openid-configuration | grep authorization_endpoint -``` -**Expected:** `"authorization_endpoint":"http://127.0.0.1:9091/api/oidc/authorization"` - -### T6.1 — Login Redirect -Open in browser: -``` -http://localhost:8080/ -``` -**Expected:** Redirected to Authelia login page at `http://127.0.0.1:9091/` with OIDC parameters in URL. - -### T6.2 — Full Login Flow -1. Visit `http://localhost:8080/` → redirected to Authelia login -2. Login with credentials (e.g., `admin` / `ueM8tLARi5v3orIzvd56w6u6!`) -3. After successful login → redirected back to NextWks launcher - -**Expected:** -- See workspace launcher page -- Shows "Welcome" heading (with username if extracted) -- App grid visible with 6 tiles - ---- - -## Test Suite 7 — Launcher & PWA - -### T7.1 — Launcher Page -Visit `http://localhost:8080/` (after OIDC login or with session cookie) - -**Expected:** -- Dark-themed workspace layout -- Header bar with logo "NextWks" and install button -- App grid with 6 tiles: Admin Panel, Files, Calendar, Mail, Office, Settings -- Admin Panel tile shows "● Available" -- Other tiles show "● Coming Soon" and are greyed out - -### T7.2 — PWA Assets -```bash -curl http://localhost:8080/static/manifest.json | python3 -m json.tool -curl http://localhost:8080/static/sw.js | head -5 -curl -o /dev/null -w "%{http_code}" http://localhost:8080/static/icons/icon-192.svg -``` -**Expected:** -- `manifest.json` → valid JSON with `"name":"Next Workspace"` -- `sw.js` → JavaScript content -- `icon-192.svg` → HTTP 200 - -### T7.3 — PWA Install Modal -1. Click the install/download button in the header bar -2. If browser doesn't trigger native prompt → modal appears - -**Expected:** -- Modal shows "Install Next Workspace" with platform-specific instructions: - - Desktop Chrome/Edge steps - - iOS Safari steps (Share → Add to Home Screen) - - Android Chrome steps (Menu → Install app) -- "Got it" button closes the modal - -### T7.4 — Manifest Validity -```bash -curl -s http://localhost:8080/static/manifest.json | python3 -c " -import json, sys -m = json.load(sys.stdin) -assert m['name'] == 'Next Workspace', 'Wrong name' -assert m['display'] == 'standalone', 'Wrong display mode' -assert len(m['icons']) >= 2, 'Missing icons' -assert m['start_url'] == '/', 'Wrong start_url' -print('Manifest valid:', m['name']) -" -``` -**Expected:** `Manifest valid: Next Workspace` - ---- - -## Test Suite 8 — Installer - -### T8.1 — Installer Help -```bash -cd /root/lexton-it/NextWks && ./install.sh --help -``` -**Expected:** Usage text with all flags listed. - -### T8.2 — Status Check -```bash -./install.sh --status -``` -**Expected:** Shows binary, config, service status, Authelia status. - -### T8.3 — Build Only -```bash -./install.sh --build-only -``` -**Expected:** Compiles binary to `app/core`, runs tests, skips install. - -### T8.4 — Config Only -```bash -./install.sh --config-only 2>&1 | head -20 -``` -**Expected:** Generates config (or warns it exists), shows admin token. - ---- - -## Test Suite 9 — Error Cases - -### T9.1 — Invalid JSON Body -```bash -curl -X POST http://localhost:8080/admin/api/users \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d 'not-json' -``` -**Expected:** `{"error":"invalid JSON body"}` (HTTP 400) - -### T9.2 — Empty Users Array -```bash -curl -X POST http://localhost:8080/admin/api/users \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"users":[]}' -``` -**Expected:** `{"error":"no users provided"}` (HTTP 400) - -### T9.3 — 404 Page -```bash -curl http://localhost:8080/nonexistent-page -``` -**Expected:** 404 Not Found - ---- - -## Test Results Summary - -| Suite | Tests | Pass | Notes | -|-------|-------|------|-------| -| 1. Core Health | 4 | | | -| 2. Admin API Auth | 3 | | | -| 3. User Management | 8 | | | -| 4. Authelia Sync | 3 | | | -| 5. Admin UI | 4 | | | -| 6. OIDC Flow | 2 | | | -| 7. Launcher & PWA | 4 | | | -| 8. Installer | 4 | | | -| 9. Error Cases | 3 | | | -| **Total** | **35** | | | - -Fill in passes as you complete each test. Report any failures or unexpected behavior. +| Suite | Tests | ✓ | Notes | +|-------|-------|---|-------| +| 1. OIDC Login | 4 | | | +| 2. Admin UI | 2 | | | +| 3. Admin API | 5 | | | +| 4. Authelia Sync | 2 | | | +| 5. PWA & Launcher | 3 | | | +| 6. Error Cases | 3 | | | +| **Total** | **19** | | |