@relipa/ai-flow-kit 0.1.0 → 0.1.1

package/custom/mcp-presets/README.md

@@ -119,6 +119,39 @@ See: [Figma workflow guide](../../docs/common/workflows/figma.md)
 
 ---
 
+### Playwright (`playwright.json`)
+
+Drive a real browser to explore selectors, verify flows, and capture evidence. Powers the `automation-testing` skill (Phase 3 — Explore).
+
+**When to use:** Generating E2E UI tests. The skill uses MCP to read the live DOM (real selectors, not guessed) and screenshot each step, then emits durable `.spec.ts` files for CI.
+
+**Setup:**
+```bash
+aiflow init --adapter playwright
+```
+
+**Requirements:**
+- The web app under test must be running and reachable at `baseUrl`
+- No API token needed
+- First run downloads browsers via `npx playwright install` (one-time)
+
+**Tools provided by `@playwright/mcp`:**
+- `browser_navigate(url)` — open a page
+- `browser_snapshot()` — accessibility tree (source of real selectors)
+- `browser_click` / `browser_type` / `browser_fill` — interact with elements
+- `browser_take_screenshot(path)` — capture evidence
+
+**Usage:**
+```
+/automation-testing baseUrl: http://localhost:3000 explore: true
+```
+
+> **Hybrid principle:** MCP is for *exploration + evidence* only. It does not replace test files — the skill always emits committable `.spec.ts` so CI can re-run.
+
+See: [automation-testing design](../../requirements/autotest/AutomationTestWorkflow.md)
+
+---
+
 ### Google Sheets (`google-sheets.json`)
 
 Connect to Google Sheets for loading task context.

package/custom/mcp-presets/playwright.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}

package/custom/rules/test-patterns.md

@@ -0,0 +1,105 @@
+# E2E Test Patterns (Playwright)
+
+Reusable patterns the `automation-testing` skill applies when generating Page Objects and specs. Selector priority is always: **`getByRole` → `getByLabel` → `getByTestId`** → (CSS/XPath only as last resort).
+
+---
+
+## 1. Login / Authentication
+
+**Test cases to cover:**
+- Valid credentials → redirect to landing page
+- Wrong password → error message visible
+- Empty required field → validation message
+- (optional) Locked/disabled account → blocked
+
+```typescript
+test('TC01 - Login success', async ({ page }) => {
+  const login = new LoginPage(page);
+  await login.navigate('/login');
+  await login.login('user@example.com', 'Password123');
+  await expect(page).toHaveURL(/\/dashboard/);
+});
+```
+
+---
+
+## 2. CRUD (Create / Read / Update / Delete)
+
+**Cover:** create → appears in list → edit → reflects change → delete → removed. Always assert on the list/detail after each mutation, not just the success toast.
+
+```typescript
+test('Create item appears in list', async ({ page }) => {
+  const list = new ItemListPage(page);
+  await list.navigate('/items');
+  await list.openCreate();
+  await list.fillForm({ name: 'Sample' });
+  await list.submit();
+  await expect(list.rowByName('Sample')).toBeVisible();
+});
+```
+
+> **Test data:** prefer a unique suffix (e.g. timestamp passed in via fixture) so reruns don't collide. Clean up created data in `afterEach` when possible.
+
+---
+
+## 3. Form validation
+
+- Submit empty → each required field shows its message
+- Invalid format (email, phone) → format message
+- Boundary (min/max length) → length message
+- Valid input → no error, submit succeeds
+
+```typescript
+test('Email format validation', async ({ page }) => {
+  const form = new SignupPage(page);
+  await form.navigate('/signup');
+  await form.emailInput.fill('not-an-email');
+  await form.submit();
+  await expect(page.getByText(/invalid email/i)).toBeVisible();
+});
+```
+
+---
+
+## 4. Modal / Dialog
+
+- Open trigger → modal visible
+- Confirm → action runs + modal closes
+- Cancel / backdrop / Esc → modal closes, no action
+
+```typescript
+await page.getByRole('button', { name: 'Delete' }).click();
+const dialog = page.getByRole('dialog');
+await expect(dialog).toBeVisible();
+await dialog.getByRole('button', { name: 'Confirm' }).click();
+await expect(dialog).toBeHidden();
+```
+
+---
+
+## 5. Pagination / Table
+
+- Default page loads expected count
+- Next/Prev changes rows
+- Page size change updates count
+- Sort by column reorders rows
+
+```typescript
+await expect(page.getByRole('row')).toHaveCount(11); // header + 10 rows
+await page.getByRole('button', { name: 'Next' }).click();
+await expect(page.getByText('Page 2')).toBeVisible();
+```
+
+---
+
+## 6. General assertions & waits
+
+- Prefer **web-first assertions** (`await expect(locator).toBeVisible()`) — they auto-retry. Never `waitForTimeout` to "wait for UI".
+- Assert on **user-visible outcome** (URL, text, element state), not internal state.
+- For async data, assert the loaded element, not a spinner disappearing.
+
+---
+
+## 7. Evidence (MCP explore phase)
+
+When exploring via Playwright MCP, capture a screenshot per significant step into `<evidenceDir>/[ticket-id]/TC<NN>-step<N>.png`. Name files so the reviewer can map evidence → test case at a glance.

package/custom/skills/automation-testing/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: automation-testing
+description: Generate runnable Playwright E2E tests for a web UI from requirement/business-logic docs or a tester's free-form draft. Uses Playwright MCP to explore real selectors and capture evidence on a live browser, then emits durable .spec.ts files plus an HTML report. Tester does not need to know TypeScript.
+keywords: automation, testing, playwright, e2e, mcp, testcase, browser, evidence, report, qa, tester
+---
+
+# Automation Testing (Hybrid MCP)
+
+Generate **runnable** Playwright E2E tests for a web UI. Works in a **multi-repo workspace** (a parent folder containing backend + frontend repos).
+
+## Core principle — HYBRID
+
+> Playwright MCP does **not** replace test files. It **improves** them.
+> Use the live browser to *learn* the app's real selectors and capture evidence, but the deliverable is always committable `.spec.ts` so CI can re-run.
+
+## When to use
+
+- Tester/Dev wants E2E UI tests but doesn't write TypeScript
+- A requirement (`requirement.md`) or business-logic doc exists and test cases should be derived from it
+- A finished feature needs regression coverage with evidence
+
+## How to invoke
+
+```
+/automation-testing baseUrl: <url> [explore: true|false] [autoRun: true|false] [headed: true|false] [ticketId: <id>]
+---
+(optional) tester's free-form test case draft
+```
+
+**Example:**
+```
+/automation-testing baseUrl: http://localhost:3000 explore: true autoRun: true
+---
+1. Vào /login, nhập đúng email/password → vào dashboard
+2. Nhập sai password → hiện thông báo lỗi
+3. Để trống email → hiện validation lỗi
+```
+
+## Params
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `baseUrl` | string | — | URL of the running web app **(required)** |
+| `explore` | boolean | `true` | Use Playwright MCP to explore real selectors + capture evidence before generating |
+| `autoRun` | boolean | `true` | Run `npx playwright test` after generating |
+| `headed` | boolean | `false` | Show browser window during `autoRun` (CI should keep `false`) |
+| `ticketId` | string | — | Ticket id; if omitted, read from `.aiflow/context/current.json` |
+
+---
+
+## Phase 1 — Collect
+
+1. **Resolve workspace.** Read `.aiflow/repos.json`.
+   - If it does NOT exist: copy the template at `.claude/skills/automation-testing/templates/repos.json`, ask the user to confirm the paths (`backend`, `frontend`, `e2e`, `planDir`, `evidenceDir`), then write `.aiflow/repos.json`. **Do not guess** the folder layout.
+2. **Resolve ticket.** Use `ticketId` param, else read `.aiflow/context/current.json`. If none, use a descriptive slug for `[ticket-id]`.
+3. **Read inputs** (any that exist):
+   - `<planDir>/[ticket-id]/requirement.md` (Gate 1)
+   - `<planDir>/[ticket-id]/plan.md` (Gate 2)
+   - business-logic doc (path provided by user or pasted)
+   - tester's draft (text after `---`)
+   - `custom/rules/test-patterns.md`
+4. **Require `baseUrl`.** If missing, ask before continuing.
+5. If NO testcase draft is provided, that's fine — derive test cases from the requirement + business-logic docs (this is the primary value).
+
+---
+
+## Phase 2 — Analyze (GATE 1)
+
+Produce a structured test case list:
+
+```
+## Test Cases — [Feature Name]
+
+| ID   | Test case                      | Steps                                          | Expected Result                  |
+|------|--------------------------------|------------------------------------------------|----------------------------------|
+| TC01 | Đăng nhập thành công           | 1. /login 2. Nhập email+pass hợp lệ 3. Submit  | Redirect /dashboard              |
+| TC02 | Sai mật khẩu                   | 1. /login 2. Sai password 3. Submit            | Hiện error message               |
+| TC03 | Validation email trống         | 1. /login 2. Submit ngay                       | "Email là bắt buộc"              |
+```
+
+> ⚠️ **GATE — STOP HERE.** Show the list and ask:
+> "Danh sách test cases trên có đúng không? Thêm/sửa/xóa gì không? Xác nhận để tôi khám phá app và sinh code."
+>
+> **Wait for confirmation before Phase 3.** Do not explore or generate code until confirmed.
+
+---
+
+## Phase 3 — Explore (Playwright MCP, live browser)
+
+Only if `explore: true` AND the Playwright MCP server is available AND the app is reachable.
+
+For each test case, drive the real app:
+1. `browser_navigate(baseUrl + path)` — open the page
+2. `browser_snapshot()` — read the accessibility tree; **extract real selectors** (prefer `getByRole` → `getByLabel` → `getByTestId`)
+3. Walk the flow (type, click) to confirm it behaves as the test case expects
+4. `browser_take_screenshot()` → save to `<evidenceDir>/[ticket-id]/TC<NN>-step<N>.png`
+5. Record the verified selectors for Phase 4
+
+**Output of this phase:** a selector map (element → verified locator) + evidence screenshots.
+
+> Do NOT commit the MCP session. The committable artifact is produced in Phase 4.
+
+### Fallback
+If `explore: false`, MCP unavailable, or the app is unreachable:
+- Generate from inference (v1 behavior)
+- **Warn clearly** that selectors are unverified and a developer must check them
+- Skip evidence capture
+
+---
+
+## Phase 4 — Generate (durable scripts)
+
+Write files under the `e2e` path from `repos.json`:
+
+```
+<e2e>/
+├── pages/
+│   ├── BasePage.ts          ← only if missing (template below)
+│   └── [Feature]Page.ts     ← Page Object; selectors from Phase 3
+├── specs/[ticket-id]/[feature].spec.ts
+├── fixtures/test.ts         ← only if missing
+└── playwright.config.ts     ← only if missing (template below)
+```
+
+**Rules:**
+- `BasePage.ts` / `playwright.config.ts` / `fixtures/test.ts` — create only if absent. Templates at `.claude/skills/automation-testing/templates/`.
+- **Page Object** — declare locators using verified selectors from Phase 3 (`getByRole` > `getByLabel` > `getByTestId`; avoid CSS/XPath unless unavoidable). One async method per action.
+- **Spec** — one `test()` per case; group with `test.describe`; test ids MUST match Phase 2 (TC01, TC02…); explicit `expect` assertions.
+- Apply patterns from `custom/rules/test-patterns.md` where relevant.
+
+---
+
+## Phase 5 — Run & Report
+
+### If `autoRun: true`
+1. Determine the target repo for E2E (per §Git below) and `cd` there.
+2. Run `npx playwright test <e2e>/specs/[ticket-id]/` (add `--headed` if `headed: true`).
+3. On completion: `npx playwright show-report` (or report the HTML path).
+4. Summarize: pass/fail count, failed-test screenshots, plus the Phase 3 exploration evidence folder.
+
+### If `autoRun: false`
+Print manual instructions:
+```
+✅ Scripts generated.
+  npx playwright test                              # all
+  npx playwright test <e2e>/specs/[ticket-id]/     # this ticket
+  npx playwright test --headed                     # show browser
+  npx playwright show-report                        # HTML report
+```
+
+---
+
+## Git & Gate 5 (multi-repo)
+
+The parent workspace is usually NOT a git repo. Commit to the **repo that owns the code under test**:
+
+| Artifact | Commit target |
+|----------|---------------|
+| E2E tests for UI | the **frontend** repo (`<frontend>/e2e/`) — unless a dedicated `e2e` repo exists |
+| requirement.md / plan.md | `<planDir>` at parent level (shared; not committed into a sub-repo) |
+
+> When creating a PR (aiflow Gate 5 / `requesting-code-review`), `cd` into the correct sub-repo first — `git`/PR commands must run inside that repo, not the parent cwd.
+
+---
+
+## Two mandatory gates
+1. After Phase 2 — confirm the test case list before exploring/generating.
+2. After Phase 5 — hand off (evidence + report) and ask the developer to review before commit/PR.

package/custom/skills/automation-testing/templates/BasePage.ts

@@ -0,0 +1,30 @@
+import { Page, expect } from '@playwright/test';
+
+/**
+ * BasePage — shared helpers for all Page Objects.
+ * Generated by the aiflow `automation-testing` skill. Create once; extend per feature.
+ */
+export abstract class BasePage {
+  constructor(protected readonly page: Page) {}
+
+  /** Navigate to a path relative to playwright.config `baseURL`. */
+  async navigate(path = '/'): Promise<void> {
+    await this.page.goto(path);
+    await this.waitForLoad();
+  }
+
+  /** Wait until network is idle (page settled). */
+  async waitForLoad(): Promise<void> {
+    await this.page.waitForLoadState('networkidle');
+  }
+
+  /** Capture a full-page screenshot as evidence. */
+  async screenshot(name: string): Promise<void> {
+    await this.page.screenshot({ path: `evidence/${name}.png`, fullPage: true });
+  }
+
+  /** Assert the current URL matches (string or RegExp). */
+  async expectUrl(url: string | RegExp): Promise<void> {
+    await expect(this.page).toHaveURL(url);
+  }
+}

package/custom/skills/automation-testing/templates/playwright.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Playwright config generated by the aiflow `automation-testing` skill.
+ * Create once per target repo; edit to fit your environment.
+ */
+export default defineConfig({
+  testDir: './specs',
+  fullyParallel: false,
+  retries: process.env.CI ? 1 : 0,
+  reporter: [['html', { open: 'never' }], ['list']],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+});

package/custom/skills/automation-testing/templates/repos.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "Workspace map for the automation-testing skill. Copied to .aiflow/repos.json. Paths are relative to the parent workspace folder (aiflow cwd). Adjust to match your layout.",
+  "backend": "./backend",
+  "frontend": "./frontend",
+  "e2e": "./frontend/e2e",
+  "planDir": "./plan",
+  "evidenceDir": "./frontend/e2e/evidence"
+}