From 89b3d81a82bba0f3b449db99482e5e9a15eb7e75 Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Fri, 22 May 2026 11:39:56 +0000 Subject: [PATCH] docs: add MCP-driven execution method to UAT playbook (GRO-1502) 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 --- UAT_PLAYBOOK.md | 54 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/UAT_PLAYBOOK.md b/UAT_PLAYBOOK.md index f4d1cd8..4cd9f1f 100644 --- a/UAT_PLAYBOOK.md +++ b/UAT_PLAYBOOK.md @@ -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").