Chris Farhood
9a3799cc5a
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
82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
# UAT Playbook — GroomBook Web
|
|
|
|
## 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.
|
|
|
|
## 2. Environments
|
|
|
|
| Environment | URL | Purpose |
|
|
|-------------|-----|---------|
|
|
| Dev | `https://dev.groombook.dev` | Development environment for daily development |
|
|
| UAT | `https://uat.groombook.dev` | User Acceptance Testing environment |
|
|
| Prod | `https://demo.groombook.app` | Production/demo environment |
|
|
|
|
## 3. Auth Base URL Resolution
|
|
|
|
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 — VITE_API_URL Set
|
|
|
|
| # | Scenario | Steps | Expected |
|
|
|---|----------|-------|----------|
|
|
| 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 Authentication — VITE_API_URL Unset (Fallback)
|
|
|
|
| # | Scenario | Steps | Expected |
|
|
|---|----------|-------|----------|
|
|
| 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 Session Persistence
|
|
|
|
| # | Scenario | Steps | Expected |
|
|
|---|----------|-------|----------|
|
|
| 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:**
|
|
- Auth client correctly resolves base URL in all scenarios
|
|
- Sign-in/sign-out flows complete successfully
|
|
- Session persists correctly across reloads
|
|
|
|
**Fail:**
|
|
- Auth requests go to wrong URL
|
|
- Sign-in/sign-out fails
|
|
- Console errors related to auth configuration
|
|
|
|
## 6. Update Policy
|
|
|
|
**Any PR that changes auth base URL resolution MUST update this 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")
|