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
TC-AUTH-5.3.4	SSO cookie set after Authentik callback (GRO-1592)	Complete Authentik SSO login on UAT without VITE_API_URL set	__Secure-better-auth.session_token cookie is present in browser; subsequent /api/* calls include the cookie and return 200

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.4.1 SSO Login Journey (Authentik OIDC end-to-end)

#	Scenario	Steps	Pass Criteria	Fail Criteria
TC-WEB-SSO-1	Sign-in page shows SSO button	Navigate to app root URL	Sign-in page displayed with "Sign in with SSO" button visible	No SSO button, 403 before page loads
TC-WEB-SSO-2	Click SSO redirects to Authentik	Click "Sign in with SSO" button	Browser redirected to Authentik login at auth.farh.net	No redirect, error shown, button does nothing
TC-WEB-SSO-3	Valid OIDC credentials authenticate	At Authentik, enter valid credentials and authenticate	Redirected back to app with active session	Redirect loop, 403, session not established
TC-WEB-SSO-4	Post-login dashboard accessible	After SSO flow completes, dashboard loads	Dashboard displays correctly with user identity shown	Blank page, 403, session not active
TC-WEB-SSO-5	User identity displayed correctly	After SSO login, check header/nav	User name/email/initials shown in nav, role reflected in UI	No user indicator, wrong user shown

5.4.2 OOBE Flow Post-Login

#	Scenario	Steps	Pass Criteria	Fail Criteria
TC-WEB-OOBE-1	Fresh DB shows setup wizard	On fresh DB (no super user), navigate to app	Setup wizard / OOBE screen displayed	Regular login page shown instead of setup
TC-WEB-OOBE-2	Configure OIDC via setup	During OOBE, configure OIDC auth provider via /api/setup/auth-provider	OIDC configured successfully, no 403	403 during setup, config rejected
TC-WEB-OOBE-3	Setup completes and redirects	Complete OOBE setup with business name	Redirected to app dashboard as super user, setup bypassed on reload	Setup errors, wrong redirect, setup reappears
TC-WEB-OOBE-4	Admin panel accessible after setup	After completing OOBE, navigate to admin panel	Admin features accessible	403 on admin panel, insufficient permissions
TC-WEB-OOBE-5	SSO login during OOBE does not interfere	During fresh OOBE, attempt SSO login before completing setup	SSO login redirected appropriately, setup can still complete	Auto-provision creates staff prematurely, setup flow broken

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.12b Dynamic Portal Time Slots (GRO-1793)

#	Scenario	Steps	Expected
TC-WEB-5.12.5	BookingFlow dynamic slots	Open Book New, select pet and service, pick a date	Time slots fetched from API; "Checking availability…" shown while loading
TC-WEB-5.12.6	BookingFlow slots match wizard	Compare BookingFlow slot times with public booking wizard for same date	Same slots displayed
TC-WEB-5.12.7	BookingFlow error state	Mock API failure on availability fetch	"Failed to load time slots" error shown
TC-WEB-5.12.8	BookingFlow no slots	Select date with no availability	"No available slots on this date" shown
TC-WEB-5.12.9	RescheduleFlow dynamic slots	Open reschedule, pick a new date	Time slots fetched from API; loading state shown
TC-WEB-5.12.10	RescheduleFlow error state	Mock API failure on availability fetch	"Failed to load time slots" error shown
TC-WEB-5.12.11	RescheduleFlow no slots	Select date with no availability	"No available slots on this date" shown

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

5.23 Pet Profile — API Persistence & Save UX (GRO-1470)

#	Scenario	Steps	Expected
TC-WEB-5.23.1	Save pet — API persistence	Edit a pet, change a field (e.g. coat type), click Save, reload the page	Changed field retained after reload (proves PATCH round-trip to server)
TC-WEB-5.23.2	Save pet — error state	Trigger an API save failure (e.g. network error)	Error message displayed; edit form stays open; no data cleared
TC-WEB-5.23.3	Save pet — saving indicator	Click Save	Spinner/indicator shown while request is in flight; form controls disabled

5.24 Booking Funnel Analytics Events (GRO-1794)

#	Scenario	Steps	Expected
TC-WEB-5.24.1	booking_step_service — public	Select a service in the public booking wizard	booking_step_service CustomEvent fires with detail.step="service" and detail.flow="public"
TC-WEB-5.24.2	booking_step_time — public	Select a time slot and click Continue	booking_step_time fires with detail.step="time" and detail.flow="public"
TC-WEB-5.24.3	booking_step_contact — public	Fill in contact/pet form, click "Review booking"	booking_step_contact fires with detail.step="contact" and detail.flow="public"
TC-WEB-5.24.4	booking_step_submit — public	Confirm and submit the booking	booking_step_submit fires with detail.step="submit" and detail.flow="public"
TC-WEB-5.24.5	booking_confirmed — public	Navigate to /booking-confirmed	booking_confirmed fires once on mount with detail.step="confirmed" and detail.flow="public"
TC-WEB-5.24.6	booking_error — public	Navigate to /booking-error	booking_error fires once on mount with detail.step="error" and detail.flow="public"
TC-WEB-5.24.7	booking_step_service — portal	Select a pet in the portal BookingFlow	booking_step_service fires with detail.step="service" and detail.flow="portal"
TC-WEB-5.24.8	booking_step_time — portal	Pick a date and time in portal BookingFlow	booking_step_time fires with detail.step="time" and detail.flow="portal"
TC-WEB-5.24.9	booking_step_contact — portal	Proceed from groomer selection to review screen	booking_step_contact fires with detail.step="groomer" and detail.flow="portal"
TC-WEB-5.24.10	booking_step_submit — portal	Submit booking in portal BookingFlow	booking_step_submit fires with detail.step="submit" and detail.flow="portal"
TC-WEB-5.24.11	booking_confirmed — portal	Portal booking request succeeds	Inline success state is shown and booking_confirmed fires with detail.step="confirmed" and detail.flow="portal"
TC-WEB-5.24.12	No PII in analytics payloads	Fire each event and inspect detail object	Payload contains only: step, flow, timestamp — no names, emails, phone numbers, or pet names
TC-WEB-5.24.13	No-op safe	Trigger analytics with window.dispatchEvent blocked (e.g. CSP)	No error thrown; booking flow completes normally

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