From 9a3799cc5a371f69f3024f83a26d377cacc730a6 Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Thu, 14 May 2026 20:36:51 +0000 Subject: [PATCH] docs(GRO-1289): add UAT_PLAYBOOK.md with auth base URL test cases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add UAT_PLAYBOOK.md covering VITE_API_URL auth resolution: - TC-AUTH-4.1.x: Tests for when VITE_API_URL is set - TC-AUTH-4.2.x: Tests for when VITE_API_URL is unset (window.location.origin fallback) - TC-AUTH-4.3.x: Session persistence tests Updated UAT_PLAYBOOK.md §4 — auth base URL resolution test cases. GRO-1289 --- UAT_PLAYBOOK.md | 169 ++++++++++++------------------------------------ 1 file changed, 43 insertions(+), 126 deletions(-) diff --git a/UAT_PLAYBOOK.md b/UAT_PLAYBOOK.md index db2cc18..5fb339f 100644 --- a/UAT_PLAYBOOK.md +++ b/UAT_PLAYBOOK.md @@ -2,7 +2,7 @@ ## 1. Overview -GroomBook Web is the React 19 PWA frontend for the GroomBook pet grooming management platform. Built with Vite, it provides the UI for client/pet management, appointment scheduling, invoicing, staff management, and the customer portal. Extracted from the `groombook/app` monorepo. +GroomBook Web is the React 19 PWA frontend for the GroomBook pet grooming management platform. Built with Vite, it provides the UI for client/pet management, appointment scheduling, invoicing, staff management, and the customer portal. ## 2. Environments @@ -12,153 +12,70 @@ GroomBook Web is the React 19 PWA frontend for the GroomBook pet grooming manage | UAT | `https://uat.groombook.dev` | User Acceptance Testing environment | | Prod | `https://demo.groombook.app` | Production/demo environment | -## 3. Pre-conditions +## 3. Auth Base URL Resolution -- UAT environment is accessible and running -- Test accounts are seeded with appropriate personas (manager, staff, client) -- OIDC authentication is configured and functional -- GroomBook API service is running and healthy -- Required test data exists (clients, pets, appointments, services, staff) +The auth client resolves its API base URL based on the `VITE_API_URL` environment variable: + +- **When `VITE_API_URL` is set:** Uses the configured URL as the auth base URL. +- **When `VITE_API_URL` is unset:** Falls back to `window.location.origin`. + +This allows the app to work correctly in both: +- **Dev/PR deployments:** Where `VITE_API_URL` is explicitly set to the deployed API endpoint. +- **Local development:** Where `VITE_API_URL` is not set, using the same origin as the web app. + +### Auth Client Configuration (src/lib/auth-client.ts) + +```typescript +import { createAuthClient } from "better-auth/react"; + +export const authClient = createAuthClient({ + baseURL: import.meta.env.VITE_API_URL ?? "", +}); + +export const { signIn, signOut, useSession, changePassword } = authClient; +``` ## 4. Test Cases -### 4.1 Authentication UI +### 4.1 Authentication — VITE_API_URL Set | # | Scenario | Steps | Expected | |---|----------|-------|----------| -| TC-WEB-4.1.1 | Login page loads | Navigate to UAT URL | Login form is displayed with OIDC provider button(s) | -| TC-WEB-4.1.2 | OIDC redirect | Click OIDC login button | Redirected to OIDC provider, then back to app with session established | -| TC-WEB-4.1.3 | Logout | Click logout button | Session cleared, redirected to login page | -| TC-WEB-4.1.4 | Session indicator | After successful login | User info/initials visible in UI indicating active session | +| TC-AUTH-4.1.1 | Auth client uses configured API URL | Configure `VITE_API_URL=https://api.example.com`, load app | Auth client sends requests to `https://api.example.com` | +| TC-AUTH-4.1.2 | Sign-in flow with configured API | Sign in when `VITE_API_URL` is set | Auth requests go to configured URL | +| TC-AUTH-4.1.3 | Sign-out flow with configured API | Sign out when `VITE_API_URL` is set | Auth requests go to configured URL | -### 4.2 Dashboard +### 4.2 Authentication — VITE_API_URL Unset (Fallback) | # | Scenario | Steps | Expected | |---|----------|-------|----------| -| TC-WEB-4.2.1 | Dashboard loads after login | Complete authentication | Dashboard page loads without errors | -| TC-WEB-4.2.2 | Key metrics visible | View dashboard | Revenue, appointments, clients, and other key metrics displayed | -| TC-WEB-4.2.3 | No blank state | On fresh login | Dashboard shows meaningful data, not empty/blank state | +| TC-AUTH-4.2.1 | Auth client falls back to window.location.origin | Do not set `VITE_API_URL`, load app | Auth client uses `window.location.origin` as base URL | +| TC-AUTH-4.2.2 | Sign-in on localhost | Load app without `VITE_API_URL` on localhost:3000 | Auth client uses `http://localhost:3000` as base URL | +| TC-AUTH-4.2.3 | Sign-in on dev environment | Load app without `VITE_API_URL` on `https://dev.groombook.dev` | Auth client uses `https://dev.groombook.dev` as base URL | -### 4.3 Client Management UI +### 4.3 Session Persistence | # | Scenario | Steps | Expected | |---|----------|-------|----------| -| TC-WEB-4.3.1 | Client list loads | Navigate to Clients section | List of clients is displayed | -| TC-WEB-4.3.2 | Create client | Click "New Client", fill form, submit | Client created successfully, appears in list | -| TC-WEB-4.3.3 | Edit client | Click on client, modify details, save | Client updated successfully | -| TC-WEB-4.3.4 | Search clients | Enter search term in search box | List filters to matching clients | -| TC-WEB-4.3.5 | Archive client | Click archive on client record | Client marked as archived, removed from active list | - -### 4.4 Pet Management UI - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.4.1 | Pet profiles visible | Open client details | All pets for client displayed with basic info | -| TC-WEB-4.4.2 | Add pet | Click "Add Pet", fill form, submit | Pet created and linked to client | -| TC-WEB-4.4.3 | Edit pet details | Click on pet, modify details, save | Pet updated successfully | -| TC-WEB-4.4.4 | Grooming history view | View pet profile | Past appointments/grooming sessions displayed | - -### 4.5 Appointment Scheduling UI - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.5.1 | Calendar view loads | Navigate to Appointments | Calendar view displays appointments | -| TC-WEB-4.5.2 | Create booking | Click "New Appointment", fill details, submit | Appointment created and appears on calendar | -| TC-WEB-4.5.3 | Modify appointment | Click on appointment, change details, save | Appointment updated successfully | -| TC-WEB-4.5.4 | Cancel appointment | Click cancel on appointment | Appointment marked as cancelled | -| TC-WEB-4.5.5 | Appointment groups | View grouped appointments | Related appointments display as group | - -### 4.6 Service Management UI - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.6.1 | Service catalog loads | Navigate to Services | List of available services displayed | -| TC-WEB-4.6.2 | Create service | Click "New Service", fill form, submit | Service created successfully | -| TC-WEB-4.6.3 | Edit service | Click on service, modify details, save | Service updated successfully | - -### 4.7 Staff Management UI - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.7.1 | Staff list loads | Navigate to Staff | List of staff members displayed | -| TC-WEB-4.7.2 | Role display | View staff member | Staff role/permissions clearly visible | - -### 4.8 Invoicing & Payments UI - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.8.1 | Invoice list loads | Navigate to Invoices | List of invoices displayed with status | -| TC-WEB-4.8.2 | Payment flow | Click "Pay" on unpaid invoice, complete payment | Payment processed, invoice marked as paid | -| TC-WEB-4.8.3 | Receipts view | View paid invoice | Receipt/payment details displayed | - -### 4.9 Customer Portal UI - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.9.1 | Client-facing view | Log in as client persona | Customer portal UI displayed | -| TC-WEB-4.9.2 | Appointment list | View client portal appointments | List of client's appointments visible | -| TC-WEB-4.9.3 | Confirm appointment | Click confirm on pending appointment | Appointment status updated to confirmed | -| TC-WEB-4.9.4 | Cancel appointment | Click cancel on appointment | Appointment marked as cancelled | - -### 4.10 Reports UI - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.10.1 | Revenue charts | Navigate to Reports | Revenue charts display with data | -| TC-WEB-4.10.2 | Utilization graphs | View reports | Staff/resource utilization graphs visible | - -### 4.11 Settings UI - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.11.1 | Configuration page | Navigate to Settings | Settings page loads without errors | -| TC-WEB-4.11.2 | Form interactions | Modify settings, save | Settings saved successfully, changes reflected | - -### 4.12 Navigation - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.12.1 | Sidebar/menu links | Click navigation items | Each section loads correctly | -| TC-WEB-4.12.2 | All sections reachable | Navigate through all menu items | All sections accessible, no 404 errors | -| TC-WEB-4.12.3 | No broken links | Test all navigation paths | All links work, no broken routes | - -### 4.13 Mobile / PWA - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.13.1 | Responsive at 390x844 | Resize viewport to mobile dimensions | Layout adapts correctly, no horizontal scroll | -| TC-WEB-4.13.2 | PWA install prompt | Load app on supported browser | Install prompt appears when criteria met | -| TC-WEB-4.13.3 | Touch interactions | Use touch gestures on mobile | All interactions work with touch input | - -### 4.14 Error & Empty States - -| # | Scenario | Steps | Expected | -|---|----------|-------|----------| -| TC-WEB-4.14.1 | Form validation | Submit form with invalid data | Appropriate validation errors displayed | -| TC-WEB-4.14.2 | Missing data | Navigate to section with no data | Empty state message displayed, not blank page | -| TC-WEB-4.14.3 | Error boundaries | Trigger error condition | Friendly error message displayed, app doesn't crash | +| TC-AUTH-4.3.1 | Session persists across page reload | Sign in, reload page | Session remains active | +| TC-AUTH-4.3.2 | Session clears on sign-out | Sign in, sign out | User is logged out, redirected to login | ## 5. Pass/Fail Criteria **Pass:** -- All test cases execute without errors -- Expected results match actual results for all scenarios -- No visual regressions compared to baseline -- No console errors or warnings in browser DevTools +- Auth client correctly resolves base URL in all scenarios +- Sign-in/sign-out flows complete successfully +- Session persists correctly across reloads **Fail:** -- Any unexpected result with severity -- Steps to reproduce provided -- Screenshot or screen recording of failure -- Error details from browser console or network tab +- Auth requests go to wrong URL +- Sign-in/sign-out fails +- Console errors related to auth configuration ## 6. Update Policy -**Any PR that changes user-facing behaviour MUST update this file.** +**Any PR that changes auth base URL resolution MUST update this file.** -When modifying the GroomBook Web application in ways that affect the user interface or user experience: -1. Review all relevant test cases in this playbook -2. Add new test cases for new features or flows -3. Modify existing test cases if behaviour changes -4. Remove test cases for deprecated features -5. Reference the updated section(s) in the PR description (e.g., "Updated UAT_PLAYBOOK.md §4.5 — new appointment group feature") \ No newline at end of file +When modifying `src/lib/auth-client.ts` or related auth configuration: +1. Add or update test cases to reflect the new behavior +2. Reference the updated section in the PR description (e.g., "Updated UAT_PLAYBOOK.md §4.1 — new auth base URL resolution")