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.

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)

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