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
TC-WEB-5.7.5	Add pet with size/coat	Create pet with Size Category and Coat Type filled	Size and coat type persisted, visible on pet profile
TC-WEB-5.7.6	Edit pet size/coat	Edit existing pet, change size/coat dropdowns	Updated values saved to pet record
TC-WEB-5.7.7	Size/coat optional	Create pet without selecting size or coat	Pet created successfully, fields remain unset

5.8.1 Buffer Rules Management UI (GRO-1173)

#	Scenario	Steps	Expected
TC-WEB-5.8.2	Buffer rules section visible	Navigate to Settings	"Buffer Rules" section shown with description
TC-WEB-5.8.3	Create buffer rule	Click "+ Add Rule", select service and buffer minutes, submit	Rule appears in list, matches service/size/coat
TC-WEB-5.8.4	Edit buffer minutes inline	Click Edit on a rule, change minutes, click Save	New buffer value reflected in list
TC-WEB-5.8.5	Delete buffer rule	Click Delete, confirm	Rule removed from list
TC-WEB-5.8.6	Create rule with size/coat	Create rule with Size Category or Coat Type specified	Rule shows size/coat tags in list
TC-WEB-5.8.7	Empty state	Navigate to Settings with no rules	"No buffer rules configured yet" message shown

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
TC-WEB-5.9.4	Create service with default buffer	Create service with "Default buffer time" filled	Buffer shown in service list and form after save
TC-WEB-5.9.5	Edit service buffer	Open existing service, change default buffer minutes	Updated value persisted after save

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

5.18 Pet Profile UI — Enhanced Fields (GRO-1178)

#	Scenario	Steps	Expected
TC-WEB-5.18.1	Coat type displayed in Grooming tab	Open pet profile, go to Grooming tab	Coat type shown (e.g. "Curly", "Double")
TC-WEB-5.18.2	Preferred cuts displayed	Open Grooming tab	Preferred cuts shown as tags/chips
TC-WEB-5.18.3	Temperament score displayed (read-only)	Open Basic Info tab	1–5 star display with score label "(N/5 · staff-set)"
TC-WEB-5.18.4	Temperament flags displayed (read-only)	Open Basic Info tab	Flag chips shown (e.g. "Anxious", "Good with kids")
TC-WEB-5.18.5	Medical alerts in Medical tab	Open Medical tab	Alert cards with type, description, severity badge
TC-WEB-5.18.6	Medical alert severity badges	View Medical tab	Low=green, Medium=amber, High=red badges
TC-WEB-5.18.7	Edit pet — coat type dropdown	Click Edit on pet, select coat type	Coat type persisted on save
TC-WEB-5.18.8	Edit pet — add medical alert	Click Edit, add alert with type + severity, save	Alert appears in Medical tab after save
TC-WEB-5.18.9	Edit pet — remove medical alert	Click Edit, remove an alert, save	Alert removed after save
TC-WEB-5.18.10	Edit pet — add preferred cut (Enter)	Click Edit, type cut name, press Enter	Cut tag added; persists after save
TC-WEB-5.18.11	Edit pet — remove preferred cut	Click Edit, click X on cut tag	Cut removed; not persisted after save
TC-WEB-5.18.12	Medical alert validation	Click Edit, add alert with empty type, try to save	Error "Type is required"; form not submitted
TC-WEB-5.18.13	Temperament fields read-only	View edit form for pet with temperament data	Temperament score and flags not editable (display only)

5.19 Booking Wizard — Pet Size & Coat (GRO-1174)

#	Scenario	Steps	Expected
TC-WEB-5.19.1	Pet size dropdown visible	Step 3 of booking wizard (pet details)	Pet size dropdown shown after breed field with options: Small, Medium, Large, X-Large
TC-WEB-5.19.2	Coat type dropdown visible	Step 3 of booking wizard	Coat type dropdown shown after pet size with options: Smooth, Double, Curly, Wire, Long, Hairless
TC-WEB-5.19.3	Size/coat pre-fill from URL	Navigate to booking with ?petSizeCategory=large&petCoatType=curly	Fields pre-filled with provided values
TC-WEB-5.19.4	Size/coat optional	Proceed through booking without selecting size/coat	Booking completes successfully
TC-WEB-5.19.5	Confirmation shows appointment duration	Confirm booking step	Service duration shown as "X min appointment" (buffer not exposed)
TC-WEB-5.19.6	Confirmation shows pet size/coat	Confirm booking with size/coat selected	Size and coat type shown on pet card in confirmation
TC-WEB-5.19.7	Availability uses buffer for large/x-large	Select large or x-large size, check availability	Availability slots reflect service duration + buffer for large/x-large
TC-WEB-5.19.8	Form reset clears size/coat	Complete booking, click "Book another"	Size and coat fields reset to empty
TC-WEB-5.19.9	New pet record has size/coat	Complete booking, view created pet in admin	Pet record shows selected size and coat type

5.20 Buffer Rules Management — Admin UI (GRO-1173)

#	Scenario	Steps	Expected
TC-WEB-5.20.1	Buffer rules section loads	Navigate to Settings page (admin)	"Buffer Rules" section visible with "+ Add Rule" button
TC-WEB-5.20.2	Add rule — required fields only	Click "+ Add Rule", select a service, enter buffer minutes, submit	Rule created, appears in list below
TC-WEB-5.20.3	Add rule — with size category	Add rule, select service + size category + buffer minutes	Rule created with size tag shown in list
TC-WEB-5.20.4	Add rule — with coat type	Add rule, select service + coat type + buffer minutes	Rule created with coat tag shown in list
TC-WEB-5.20.5	Add rule — with both size and coat	Add rule, select service + size + coat + buffer minutes	Rule created with both tags shown
TC-WEB-5.20.6	Validation — missing service	Submit form without selecting service	Error: "Service and valid buffer minutes are required"
TC-WEB-5.20.7	Validation — zero buffer	Submit form with 0 buffer minutes	Error: "Service and valid buffer minutes are required"
TC-WEB-5.20.8	Edit rule inline	Click "Edit" on a rule, change buffer value, click "Save"	Rule updated in list
TC-WEB-5.20.9	Cancel edit	Click "Edit", then "Cancel"	Original value unchanged
TC-WEB-5.20.10	Delete rule — confirmation	Click "Delete" on a rule	Confirmation prompt appears
TC-WEB-5.20.11	Confirm delete	On confirmation prompt, click "Confirm"	Rule removed from list
TC-WEB-5.20.12	Cancel delete	On confirmation prompt, click "Cancel"	Rule remains in list
TC-WEB-5.20.13	Empty state	No rules exist	Message: "No buffer rules configured yet."
TC-WEB-5.20.14	Toggle form	Click "+ Add Rule", then "Cancel"	Form hidden, no rule created

5.21 Service Default Buffer Minutes (GRO-1173)

#	Scenario	Steps	Expected
TC-WEB-5.21.1	Default buffer shown in table	Navigate to Services page	"Default Buffer" column visible in services table
TC-WEB-5.21.2	New service default is 0	Click "+ Add Service"	Default Buffer field pre-filled with 0
TC-WEB-5.21.3	Create service with buffer	Fill service form, set Default Buffer = 10, submit	Service created with 10 min default buffer
TC-WEB-5.21.4	Edit service — view buffer	Edit an existing service	Current default buffer value shown in form
TC-WEB-5.21.5	Update buffer on existing service	Edit service, change Default Buffer to 15, save	Buffer updated, table shows 15 min
TC-WEB-5.21.6	Buffer field — zero allowed	Set Default Buffer to 0, save	Service saved with 0 (no default buffer)
TC-WEB-5.21.7	Buffer field — integer only	Enter non-integer value	Field restricts to integer values

5.22 Pet Profile — Size Category & Coat Type (GRO-1173)

#	Scenario	Steps	Expected
TC-WEB-5.22.1	Size category dropdown visible	Open Add Pet or Edit Pet form (portal)	"Size Category" dropdown visible with options: Small, Medium, Large, X-Large
TC-WEB-5.22.2	Coat type dropdown visible	Open Add Pet or Edit Pet form	"Coat Type" dropdown visible with options: Smooth, Double, Curly, Wire, Long, Hairless
TC-WEB-5.22.3	Size and coat both optional	Submit pet form without selecting size or coat	Pet saved successfully
TC-WEB-5.22.4	Save pet with size category	Select "Large", fill required fields, save	Pet saved with size = "large"
TC-WEB-5.22.5	Save pet with coat type	Select "Curly", fill required fields, save	Pet saved with coat = "curly"
TC-WEB-5.22.6	Size and coat persisted	Save pet with size + coat, edit again	Both fields retain their selected values
TC-WEB-5.22.7	Clear size	Select size, then clear back to default	Size cleared on save

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