web/UAT_PLAYBOOK.md

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. Extracted from the groombook/app monorepo.

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. Pre-conditions

• 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)

4. 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)

import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient({
  baseURL: import.meta.env.VITE_API_URL ?? "",
});

export const { signIn, signOut, useSession, changePassword } = authClient;

5. Test Cases

5.1 Authentication UI

#	Scenario	Steps	Expected
TC-WEB-5.1.1	Login page loads	Navigate to UAT URL	Login form is displayed with OIDC provider button(s)
TC-WEB-5.1.2	OIDC redirect	Click OIDC login button	Redirected to OIDC provider, then back to app with session established
TC-WEB-5.1.3	Logout	Click logout button	Session cleared, redirected to login page
TC-WEB-5.1.4	Session indicator	After successful login	User info/initials visible in UI indicating active session

5.2 Authentication — VITE_API_URL Set

#	Scenario	Steps	Expected
TC-AUTH-5.2.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-5.2.2	Sign-in flow with configured API	Sign in when VITE_API_URL is set	Auth requests go to configured URL
TC-AUTH-5.2.3	Sign-out flow with configured API	Sign out when VITE_API_URL is set	Auth requests go to configured URL

5.3 Authentication — VITE_API_URL Unset (Fallback)

#	Scenario	Steps	Expected
TC-AUTH-5.3.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-5.3.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-5.3.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

5.4 Session Persistence

#	Scenario	Steps	Expected
TC-AUTH-5.4.1	Session persists across page reload	Sign in, reload page	Session remains active
TC-AUTH-5.4.2	Session clears on sign-out	Sign in, sign out	User is logged out, redirected to login

5.5 Dashboard

#	Scenario	Steps	Expected
TC-WEB-5.5.1	Dashboard loads after login	Complete authentication	Dashboard page loads without errors
TC-WEB-5.5.2	Key metrics visible	View dashboard	Revenue, appointments, clients, and other key metrics displayed
TC-WEB-5.5.3	No blank state	On fresh login	Dashboard shows meaningful data, not empty/blank state

5.6 Client Management UI

#	Scenario	Steps	Expected
TC-WEB-5.6.1	Client list loads	Navigate to Clients section	List of clients is displayed
TC-WEB-5.6.2	Create client	Click "New Client", fill form, submit	Client created successfully, appears in list
TC-WEB-5.6.3	Edit client	Click on client, modify details, save	Client updated successfully
TC-WEB-5.6.4	Search clients	Enter search term in search box	List filters to matching clients
TC-WEB-5.6.5	Archive client	Click archive on client record	Client marked as archived, removed from active list

5.7 Pet Management UI

#	Scenario	Steps	Expected
TC-WEB-5.7.1	Pet profiles visible	Open client details	All pets for client displayed with basic info
TC-WEB-5.7.2	Add pet	Click "Add Pet", fill form, submit	Pet created and linked to client
TC-WEB-5.7.3	Edit pet details	Click on pet, modify details, save	Pet updated successfully
TC-WEB-5.7.4	Grooming history view	View pet profile	Past appointments/grooming sessions displayed

5.8 Appointment Scheduling UI

#	Scenario	Steps	Expected
TC-WEB-5.8.1	Calendar view loads	Navigate to Appointments	Calendar view displays appointments
TC-WEB-5.8.2	Create booking	Click "New Appointment", fill details, submit	Appointment created and appears on calendar
TC-WEB-5.8.3	Modify appointment	Click on appointment, change details, save	Appointment updated successfully
TC-WEB-5.8.4	Cancel appointment	Click cancel on appointment	Appointment marked as cancelled
TC-WEB-5.8.5	Appointment groups	View grouped appointments	Related appointments display as group

5.9 Service Management UI

#	Scenario	Steps	Expected
TC-WEB-5.9.1	Service catalog loads	Navigate to Services	List of available services displayed
TC-WEB-5.9.2	Create service	Click "New Service", fill form, submit	Service created successfully
TC-WEB-5.9.3	Edit service	Click on service, modify details, save	Service updated successfully

5.10 Staff Management UI

#	Scenario	Steps	Expected
TC-WEB-5.10.1	Staff list loads	Navigate to Staff	List of staff members displayed
TC-WEB-5.10.2	Role display	View staff member	Staff role/permissions clearly visible

5.11 Invoicing & Payments UI

#	Scenario	Steps	Expected
TC-WEB-5.11.1	Invoice list loads	Navigate to Invoices	List of invoices displayed with status
TC-WEB-5.11.2	Payment flow	Click "Pay" on unpaid invoice, complete payment	Payment processed, invoice marked as paid
TC-WEB-5.11.3	Receipts view	View paid invoice	Receipt/payment details displayed

5.12 Customer Portal UI

#	Scenario	Steps	Expected
TC-WEB-5.12.1	Client-facing view	Log in as client persona	Customer portal UI displayed
TC-WEB-5.12.2	Appointment list	View client portal appointments	List of client's appointments visible
TC-WEB-5.12.3	Confirm appointment	Click confirm on pending appointment	Appointment status updated to confirmed
TC-WEB-5.12.4	Cancel appointment	Click cancel on appointment	Appointment marked as cancelled

5.13 Reports UI

#	Scenario	Steps	Expected
TC-WEB-5.13.1	Revenue charts	Navigate to Reports	Revenue charts display with data
TC-WEB-5.13.2	Utilization graphs	View reports	Staff/resource utilization graphs visible

5.14 Settings UI

#	Scenario	Steps	Expected
TC-WEB-5.14.1	Configuration page	Navigate to Settings	Settings page loads without errors
TC-WEB-5.14.2	Form interactions	Modify settings, save	Settings saved successfully, changes reflected

5.15 Navigation

#	Scenario	Steps	Expected
TC-WEB-5.15.1	Sidebar/menu links	Click navigation items	Each section loads correctly
TC-WEB-5.15.2	All sections reachable	Navigate through all menu items	All sections accessible, no 404 errors
TC-WEB-5.15.3	No broken links	Test all navigation paths	All links work, no broken routes

5.16 Mobile / PWA

#	Scenario	Steps	Expected
TC-WEB-5.16.1	Responsive at 390x844	Resize viewport to mobile dimensions	Layout adapts correctly, no horizontal scroll
TC-WEB-5.16.2	PWA install prompt	Load app on supported browser	Install prompt appears when criteria met
TC-WEB-5.16.3	Touch interactions	Use touch gestures on mobile	All interactions work with touch input

5.17 Error & Empty States

#	Scenario	Steps	Expected
TC-WEB-5.17.1	Form validation	Submit form with invalid data	Appropriate validation errors displayed
TC-WEB-5.17.2	Missing data	Navigate to section with no data	Empty state message displayed, not blank page
TC-WEB-5.17.3	Error boundaries	Trigger error condition	Friendly error message displayed, app doesn't crash

6. 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

Fail:

• Any unexpected result with severity
• Steps to reproduce provided
• Screenshot or screen recording of failure
• Error details from browser console or network tab

7. Update Policy

Any PR that changes user-facing behaviour 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 §5.5 — new appointment group feature")