groombook/app
Archived
13
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add MCP-driven execution method to UAT playbook (GRO-1502)

Browse Source 
UAT is now executed by Shedward Scissorhands via the groombook-playwright
MCP server. Legacy scripted Playwright suites remain for CI regression
only. Added Section 2 documenting the MCP tools, how test cases map to
MCP calls, and the role of legacy CI tests.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Chris Farhood
2026-05-22 11:39:56 +00:00
committed by The Dogfather [agent]
parent 4a628ef3b7
commit 89b3d81a82
1 changed files with 48 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
UAT_PLAYBOOK.md
+48 -6
View File
@@ -4,7 +4,49 @@
GroomBook is an open-source, self-hostable pet grooming business management & CRM platform. The monorepo contains the Hono API (`apps/api`), React PWA web app (`apps/web`), E2E tests (`apps/e2e`), and shared packages (`packages/db`, `packages/types`). Tech stack: Hono + React 19 + Vite + PostgreSQL + Drizzle ORM + Authentik OIDC.
## 2. Environments
## 2. Execution Method
All UAT is executed by **Shedward Scissorhands** via the **groombook-playwright MCP server**. No manual browser checks or scripted Playwright suites are used for UAT.
### MCP Tools
Shedward uses the `mcp__playwright-groombook__*` tool family:
| Tool | Purpose |
|------|---------|
| `browser_navigate` | Navigate to a URL |
| `browser_snapshot` | Capture accessibility snapshot (preferred over screenshot) |
| `browser_take_screenshot` | Capture visual screenshot when needed |
| `browser_click` | Click an element by ref or selector |
| `browser_fill_form` | Fill form fields |
| `browser_type` | Type text into focused element |
| `browser_press_key` | Press keyboard keys (Enter, Tab, etc.) |
| `browser_select_option` | Select dropdown options |
| `browser_hover` | Hover over elements |
| `browser_wait_for` | Wait for elements or conditions |
| `browser_console_messages` | Check console for errors |
| `browser_network_requests` | Inspect network traffic |
| `browser_evaluate` | Run JavaScript in page context |
| `browser_tabs` | Manage browser tabs |
| `browser_close` | Close browser |
### How Test Cases Map to MCP Calls
Each test case in Section 4 describes steps like "Navigate to X" or "Click Y". Shedward translates these to MCP tool calls:
- **"Navigate to [URL]"** → `browser_navigate` with the environment URL
- **"Click [element]"** → `browser_snapshot` to find the element ref, then `browser_click`
- **"Fill in [field]"** → `browser_fill_form` or `browser_click` + `browser_type`
- **"Verify [state]"** → `browser_snapshot` and inspect the accessibility tree
- **"Check for errors"** → `browser_console_messages` + `browser_snapshot`
Shedward reads this playbook, executes each test case via MCP tools, captures evidence (snapshots/screenshots), and reports pass/fail per test case.
### Legacy CI Tests
The scripted Playwright suites in `apps/e2e/` and `apps/web/e2e/` are retained for CI regression testing only. They are **not** the primary UAT mechanism. UAT is exclusively MCP-driven by Shedward.
## 3. Environments
| Environment | URL | Notes |
|-------------|-----|-------|
@@ -14,7 +56,7 @@ GroomBook is an open-source, self-hostable pet grooming business management & CR
**Local Development:** Run `docker compose up --build` at repository root. Web app available at `localhost:8080`, API at `localhost:3000`.
## 3. Pre-conditions
## 4. Pre-conditions
- UAT environment is accessible at `https://uat.groombook.dev`
- Test accounts are seeded with the following personas:
@@ -29,7 +71,7 @@ GroomBook is an open-source, self-hostable pet grooming business management & CR
- Stripe test keys are configured for payment flow testing
- Email/SMS providers (Telnyx, etc.) are configured for notification testing
## 4. Test Cases
## 5. Test Cases
### 4.1 Authentication
@@ -252,7 +294,7 @@ GroomBook is an open-source, self-hostable pet grooming business management & CR
| TC-APP-4.21.10 | Whitespace trimming | 1. Send ` START ` or `\tSTOP\n` | Keywords are trimmed before matching |
| TC-APP-4.21.11 | Non-keyword messages ignored | 1. Send `STOP IT`, `help me`, `hello` | Returns null from `detectKeyword`, no consent event inserted, no reply sent |
| TC-APP-4.21.12 | Consent event audit log | 1. After any keyword, query `messageConsentEvents` table | Record exists with correct `clientId`, `businessId`, `kind`, and `source: "sms_keyword"` |
## 5. Pass/Fail Criteria
## 6. Pass/Fail Criteria
**Pass:** All test cases execute without errors. Expected results match actual results. No regressions are observed. All functionality works as documented.
@@ -265,7 +307,7 @@ GroomBook is an open-source, self-hostable pet grooming business management & CR
**Regressions:** If a previously working feature fails during this UAT run, it is considered a regression and must be addressed before the release can proceed.
## 6. Update Policy
## 7. Update Policy
**Any PR that changes user-facing behaviour MUST update this file.**
@@ -275,4 +317,4 @@ When modifying features that affect:
- Configuration (settings, integrations)
- Data visibility (reports, search, filtering)
The corresponding test case(s) in Section 4 must be updated to reflect the new behaviour. The PR description must reference which playbook section was updated (e.g., "Updated UAT_PLAYBOOK.md §4.5 — new appointment group scheduling feature").
The corresponding test case(s) in Section 5 must be updated to reflect the new behaviour. The PR description must reference which playbook section was updated (e.g., "Updated UAT_PLAYBOOK.md §4.5 — new appointment group scheduling feature").