@nockdev/awf 6.2.0 → 6.2.2

package/.agent/skills/cross-cutting/playwright/META.yaml

@@ -0,0 +1,90 @@
+name: playwright
+version: "1.0.0"
+display: Playwright
+category: cross-cutting
+tier: 1
+priority: 2
+
+desc: "Playwright browser automation: MCP tools (19), E2E testing, AI agents (Planner/Generator/Healer), comprehensive UI interaction checklist (58 checkpoints), accessibility snapshots, Page Object Model."
+
+  ### Data Files (6 domains, ~80 patterns)
+  - mcp-tools.yaml: 19 MCP tool definitions — navigation, interaction, observation (19)
+  - interaction-checklist.yaml: 58 mandatory checkpoints — dropdown, modal, button, hover (58)
+  - locator-patterns.yaml: Priority-ordered locator strategies (5)
+  - config-templates.yaml: CI/local/mobile/visual regression configs (4)
+  - ai-agents.yaml: Planner/Generator/Healer workflow patterns (3)
+  - open-source-tools.yaml: Browser automation ecosystem reference (8)
+
+triggers:
+  file_patterns:
+    - "playwright.config.*"
+    - "tests/e2e/**"
+    - "*.e2e.*"
+    - "*.pw.*"
+    - "**/__e2e__/**"
+  keywords:
+    # Core
+    - playwright
+    - browser testing
+    - e2e testing
+    - end to end
+    - browser automation
+    # MCP
+    - playwright mcp
+    - browser_snapshot
+    - browser_click
+    - accessibility snapshot
+    # Patterns
+    - cross-browser
+    - visual regression
+    - page object model
+    # Interactive elements
+    - test dropdown
+    - test modal
+    - verify button
+    - check hover
+  intents:
+    - test frontend
+    - verify UI
+    - browser test
+    - check dropdown
+    - test modal
+    - verify button action
+    - comprehensive UI test
+
+caps:
+  - Playwright MCP 19 tools reference (navigate, click, type, snapshot, etc.)
+  - 58-checkpoint comprehensive interaction testing checklist
+  - Dropdown testing (18 checkpoints: open/close/select/keyboard/validation)
+  - Modal testing (16 checkpoints: trigger/close/focus trap/Escape/form)
+  - Button testing (14 checkpoints: click action/disabled/loading/rage-click)
+  - Hover testing (10 checkpoints: tooltip/menu/keyboard equivalent)
+  - AI Test Agents — Planner/Generator/Healer patterns
+  - Accessibility snapshot vs screenshot strategy
+  - Page Object Model templates
+  - Locator priority: getByRole > getByLabel > getByTestId > locator
+  - Visual regression with toHaveScreenshot()
+  - Cross-browser & mobile device testing
+  - CI/CD pipeline integration configs
+  - Open-source tools ecosystem (Stagehand, Browser-Use, Midscene.js)
+
+data_files:
+  - data/mcp-tools.yaml
+  - data/interaction-checklist.yaml
+  - data/locator-patterns.yaml
+  - data/config-templates.yaml
+  - data/ai-agents.yaml
+  - data/open-source-tools.yaml
+
+related_skills:
+  - testing
+  - accessibility
+  - browser-agent
+  - mcp
+
+hsa_adapter:
+  enabled: true
+  data_dir: "skills/cross-cutting/playwright/data"
+  preload_data: true
+
+# _DOMYH Awesome Code • Playwright Skill META v1.0.0_

package/.agent/skills/cross-cutting/playwright/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: playwright
+detect: ["playwright.config.*", "*.e2e.*", "tests/e2e/**"]
+version: "1.0.0"
+---
+
+# Playwright Browser Automation (2026)
+
+> Comprehensive browser testing skill with 58-checkpoint interaction checklist. Check `data/` for lookup tables.
+
+## 📦 Data Files
+
+| File                         | Content                                 | Records |
+| ---------------------------- | --------------------------------------- | ------- |
+| `mcp-tools.yaml`             | 19 Playwright MCP tool definitions      | 19      |
+| `interaction-checklist.yaml` | 58 mandatory UI interaction checkpoints | 58      |
+| `locator-patterns.yaml`      | Priority-ordered locator strategies     | 5       |
+| `config-templates.yaml`      | CI/local/mobile/visual configs          | 4       |
+| `ai-agents.yaml`             | Planner/Generator/Healer patterns       | 3       |
+| `open-source-tools.yaml`     | Browser automation ecosystem            | 8       |
+
+## 🎯 Core Problem & Solution
+
+```
+❌ Agent chỉ kiểm tra: page load, layout, text visible
+✅ Agent PHẢI kiểm tra: dropdown, modal, button, hover, form, keyboard nav
+```
+
+**Solution**: 58-checkpoint interaction checklist — buộc test TỪNG interactive element.
+
+## 🛠️ MCP Tools Quick Reference
+
+### Navigation (5 tools)
+
+| Tool                    | Purpose           |
+| ----------------------- | ----------------- |
+| `browser_navigate`      | Mở URL            |
+| `browser_navigate_back` | Quay lại          |
+| `browser_close`         | Đóng browser      |
+| `browser_resize`        | Thay đổi viewport |
+| `browser_tabs`          | Quản lý tabs      |
+
+### Interaction (9 tools) — **CRITICAL cho comprehensive testing**
+
+| Tool                    | Use Case                            |
+| ----------------------- | ----------------------------------- |
+| `browser_click`         | Button, link, tab, accordion        |
+| `browser_type`          | Form input, search                  |
+| `browser_press_key`     | Escape đóng modal, Enter submit     |
+| `browser_hover`         | Tooltip, dropdown menu, hover state |
+| `browser_select_option` | Native `<select>` dropdown          |
+| `browser_drag`          | Drag-and-drop, reorder              |
+| `browser_file_upload`   | File input                          |
+| `browser_handle_dialog` | Alert/confirm/prompt                |
+| `browser_fill_form`     | Nhiều fields cùng lúc               |
+
+### Observation (5 tools)
+
+| Tool                       | Use Case                          |
+| -------------------------- | --------------------------------- |
+| `browser_snapshot`         | **CORE: LLM hiểu page structure** |
+| `browser_take_screenshot`  | Visual verification               |
+| `browser_evaluate`         | Run JS, check DOM/CSS             |
+| `browser_console_messages` | Error detection                   |
+| `browser_network_requests` | API verification                  |
+
+## 🎯 Locator Priority
+
+```
+1. getByRole('button', { name: 'Submit' })  ← BEST (semantic)
+2. getByLabel('Email')                       ← Form fields
+3. getByTestId('submit-btn')                 ← Explicit markers
+4. getByText('Sign in')                      ← Visible content
+5. locator('.btn-primary')                   ← LAST RESORT
+```
+
+## 📋 58-Checkpoint Summary
+
+### Dropdown (18 checks)
+
+- **Functional**: open list, select updates value, default value, dependent, multi-select, search
+- **Keyboard**: Tab focus, Enter/Space open, arrows navigate, typing jumps, Escape close
+- **Visual**: no truncation, scroll, no layout shift
+- **Validation**: required error, invalid input blocked, clear message
+
+### Modal (16 checks)
+
+- **Trigger**: button triggers, centered overlay, background blocked, content visible
+- **Close**: X button, overlay click, Escape key, focus returns
+- **Keyboard**: Tab trap inside, Shift+Tab backward, no focus escape, screen reader
+- **Form**: submit works, validation, success/error states
+
+### Button (14 checks)
+
+- **Functional**: click performs action, state changes, rage-click safe, disabled, navigation, toggle
+- **Visual**: consistent design, hitbox accurate, text meaningful, responsive
+- **Accessibility**: Tab order, Enter activates, focus visible, screen reader name
+
+### Hover (10 checks)
+
+- **Trigger**: hover triggers state, content persists, keyboard equivalent
+- **Content**: readable, no layout shift, no obstruction
+- **Dismiss**: Escape dismisses, no interference
+- **Technical**: CSS states correct, JS handlers work
+
+## 🤖 AI Test Agents
+
+| Agent         | Role                             | I/O                        |
+| ------------- | -------------------------------- | -------------------------- |
+| **Planner**   | Explore app → generate test plan | App URL → Markdown plan    |
+| **Generator** | Plan → executable tests          | Markdown → Playwright code |
+| **Healer**    | Detect UI changes → repair tests | Failed test → Fixed code   |
+
+## 🔍 Decision Tree
+
+```
+Need to interact with page?
+├─ Understand page structure → browser_snapshot (accessibility tree)
+├─ Visual verification → browser_take_screenshot
+├─ Click/type/select → browser_click / browser_type / browser_select_option
+├─ Open modal → browser_click trigger → browser_snapshot modal content
+├─ Close modal → browser_press_key "Escape"
+├─ Test dropdown → browser_click → browser_select_option → browser_snapshot
+└─ Check errors → browser_console_messages + browser_network_requests
+```
+
+## ⚠️ Common Pitfalls
+
+| ❌ Don't                             | ✅ Do                                       |
+| ------------------------------------ | ------------------------------------------- |
+| Use screenshot for LLM understanding | Use `browser_snapshot` (accessibility tree) |
+| Test only page load                  | Test ALL interactive elements               |
+| Use CSS selectors                    | Use `getByRole()` / `getByLabel()`          |
+| Skip keyboard testing                | Test Tab, Enter, Escape                     |
+| Ignore console errors                | Always check `browser_console_messages`     |
+| Single browser                       | Cross-browser: Chromium + Firefox + WebKit  |
+
+## Playwright Config (Quick Start)
+
+```typescript
+import { defineConfig, devices } from "@playwright/test";
+export default defineConfig({
+  testDir: "./tests/e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: "html",
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+  },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "mobile", use: { ...devices["iPhone 14"] } },
+  ],
+});
+```
+
+## Page Object Model
+
+```typescript
+import { Page, Locator, expect } from "@playwright/test";
+
+export class LoginPage {
+  readonly page: Page;
+  readonly email: Locator;
+  readonly password: Locator;
+  readonly submit: Locator;
+  readonly errorMsg: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.email = page.getByLabel("Email");
+    this.password = page.getByLabel("Password");
+    this.submit = page.getByRole("button", { name: "Sign in" });
+    this.errorMsg = page.getByRole("alert");
+  }
+
+  async login(email: string, password: string) {
+    await this.email.fill(email);
+    await this.password.fill(password);
+    await this.submit.click();
+  }
+
+  async expectError(message: string) {
+    await expect(this.errorMsg).toContainText(message);
+  }
+}
+```
+
+## 🔌 HSA Integration
+
+Data powered by HSA BM25 search engine:
+
+| Domain    | Query Examples                        |
+| --------- | ------------------------------------- |
+| MCP Tools | "browser_click browser_snapshot"      |
+| Checklist | "dropdown testing modal verification" |
+| Locators  | "getByRole getByLabel priority"       |
+| Config    | "CI pipeline mobile testing"          |
+| AI Agents | "planner generator healer"            |
+| Tools     | "stagehand browser-use midscene"      |
+
+**Data domains**: `mcp-tools`, `interaction-checklist`, `locator-patterns`, `config-templates`, `ai-agents`, `open-source-tools`
+
+---
+
+_DOMYH Awesome Code — Playwright Browser Automation (Data-Driven + HSA)_

package/.agent/skills/cross-cutting/playwright/data/ai-agents.yaml

@@ -0,0 +1,137 @@
+# =============================================================================
+# ai-agents.yaml — Playwright AI Test Agent Patterns
+# =============================================================================
+
+version: "1.0.0"
+
+agents:
+  planner:
+    name: "Planner Agent"
+    role: "Explore application and generate structured test plan"
+    input: "Application URL + description"
+    output: "Markdown test plan with scenarios, steps, assertions"
+    workflow:
+      - "Navigate to application root"
+      - "Use browser_snapshot to map all pages and routes"
+      - "Identify interactive elements per page"
+      - "Generate test scenarios with expected behaviors"
+      - "Output: structured Markdown test plan"
+    template: |
+      ## Test Plan: [Application Name]
+
+      ### Page: /login
+      **Interactive Elements**: email input, password input, submit button, forgot password link
+
+      #### Scenario 1: Successful Login
+      1. Navigate to /login
+      2. Fill email: test@example.com
+      3. Fill password: password123
+      4. Click "Sign in" button
+      5. **Assert**: Redirected to /dashboard
+      6. **Assert**: Welcome message visible
+
+      #### Scenario 2: Invalid Credentials
+      1. Navigate to /login
+      2. Fill email: wrong@example.com
+      3. Fill password: wrongpass
+      4. Click "Sign in" button
+      5. **Assert**: Error message "Invalid credentials"
+      6. **Assert**: Still on /login page
+
+      #### Scenario 3: Empty Form Submission
+      1. Navigate to /login
+      2. Click "Sign in" without filling fields
+      3. **Assert**: Validation errors for email and password
+
+  generator:
+    name: "Generator Agent"
+    role: "Convert test plan to executable Playwright tests"
+    input: "Markdown test plan"
+    output: "Playwright test files (.spec.ts)"
+    workflow:
+      - "Parse Markdown test plan"
+      - "Map scenarios to test blocks"
+      - "Use getByRole/getByLabel for locators"
+      - "Add assertions with expect()"
+      - "Validate against live browser"
+    template: |
+      import { test, expect } from '@playwright/test';
+
+      test.describe('Login Page', () => {
+        test.beforeEach(async ({ page }) => {
+          await page.goto('/login');
+        });
+
+        test('successful login', async ({ page }) => {
+          await page.getByLabel('Email').fill('test@example.com');
+          await page.getByLabel('Password').fill('password123');
+          await page.getByRole('button', { name: 'Sign in' }).click();
+
+          await expect(page).toHaveURL('/dashboard');
+          await expect(page.getByText('Welcome')).toBeVisible();
+        });
+
+        test('invalid credentials shows error', async ({ page }) => {
+          await page.getByLabel('Email').fill('wrong@example.com');
+          await page.getByLabel('Password').fill('wrongpass');
+          await page.getByRole('button', { name: 'Sign in' }).click();
+
+          await expect(page.getByRole('alert')).toContainText('Invalid credentials');
+          await expect(page).toHaveURL('/login');
+        });
+
+        test('empty form shows validation errors', async ({ page }) => {
+          await page.getByRole('button', { name: 'Sign in' }).click();
+
+          await expect(page.getByText('Email is required')).toBeVisible();
+          await expect(page.getByText('Password is required')).toBeVisible();
+        });
+      });
+
+  healer:
+    name: "Healer Agent"
+    role: "Detect and repair failing tests due to UI changes"
+    input: "Failed test + error message + current page state"
+    output: "Updated test with fixed locators/assertions"
+    workflow:
+      - "Run failing test, capture error"
+      - "Take browser_snapshot of current page state"
+      - "Compare expected vs actual element references"
+      - "Identify what changed (selector, text, structure)"
+      - "Update locator or assertion to match new UI"
+      - "Re-run test to verify fix"
+    detection_patterns:
+      - pattern: "Element not found"
+        cause: "Selector changed (class, ID, text)"
+        fix: "Use browser_snapshot to find new ref, update locator"
+      - pattern: "Expected text mismatch"
+        cause: "Content text changed"
+        fix: "Update expected text in assertion"
+      - pattern: "Timeout waiting"
+        cause: "Element removed or hidden"
+        fix: "Check if element still exists, update test flow"
+      - pattern: "Navigation mismatch"
+        cause: "URL structure changed"
+        fix: "Update expected URL pattern"
+    template: |
+      // Before (failing):
+      // await page.locator('#submit-btn').click();
+      // Error: Element not found: #submit-btn
+
+      // After browser_snapshot, found new ref:
+      await page.getByRole('button', { name: 'Submit' }).click();
+      // ✅ Healed: switched from ID to semantic role locator
+
+# Integration with AI IDEs
+ide_integration:
+  antigravity:
+    tool: "browser_subagent"
+    usage: "Delegate test plan generation to Planner via browser_subagent task"
+  cursor:
+    tool: "Playwright MCP"
+    usage: "Use MCP tools directly for interaction"
+  vscode:
+    tool: "Playwright Test extension"
+    usage: "Built-in test runner with UI mode"
+
+# _DOMYH Awesome Code • AI Test Agent Patterns v1.0.0_

package/.agent/skills/cross-cutting/playwright/data/config-templates.yaml

@@ -0,0 +1,141 @@
+# =============================================================================
+# config-templates.yaml — Playwright Configuration Templates
+# =============================================================================
+
+version: "1.0.0"
+
+templates:
+  local_development:
+    name: "Local Development"
+    when: "Day-to-day development testing"
+    config: |
+      import { defineConfig, devices } from '@playwright/test';
+      export default defineConfig({
+        testDir: './tests/e2e',
+        fullyParallel: true,
+        retries: 0,
+        workers: undefined, // Use all CPU cores
+        reporter: [['html', { open: 'never' }]],
+        use: {
+          baseURL: 'http://localhost:3000',
+          trace: 'on', // Always trace for debugging
+          screenshot: 'on', // Always capture
+          video: 'on', // Record all tests
+          headless: false, // See browser
+        },
+        projects: [
+          { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+        ],
+        webServer: {
+          command: 'npm run dev',
+          url: 'http://localhost:3000',
+          reuseExistingServer: true,
+        },
+      });
+
+  ci_pipeline:
+    name: "CI Pipeline"
+    when: "GitHub Actions, GitLab CI, Jenkins"
+    config: |
+      import { defineConfig, devices } from '@playwright/test';
+      export default defineConfig({
+        testDir: './tests/e2e',
+        fullyParallel: true,
+        forbidOnly: true, // Fail on test.only
+        retries: 2, // Retry flaky tests
+        workers: 1, // Sequential for stability
+        reporter: [
+          ['html', { outputFolder: 'test-results/html' }],
+          ['json', { outputFile: 'test-results/results.json' }],
+          ['github'], // GitHub Actions annotations
+        ],
+        use: {
+          baseURL: 'http://localhost:3000',
+          trace: 'on-first-retry', // Trace only on failure
+          screenshot: 'only-on-failure',
+          video: 'retain-on-failure',
+          headless: true,
+        },
+        projects: [
+          { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+          { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+          { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+        ],
+        webServer: {
+          command: 'npm run start',
+          url: 'http://localhost:3000',
+          reuseExistingServer: false,
+          timeout: 120_000,
+        },
+      });
+
+  mobile_testing:
+    name: "Mobile Device Testing"
+    when: "Responsive design, touch interactions"
+    config: |
+      import { defineConfig, devices } from '@playwright/test';
+      export default defineConfig({
+        testDir: './tests/e2e/mobile',
+        use: {
+          baseURL: 'http://localhost:3000',
+          trace: 'on-first-retry',
+        },
+        projects: [
+          // iPhone
+          { name: 'iphone-14', use: { ...devices['iPhone 14'] } },
+          { name: 'iphone-14-landscape', use: { ...devices['iPhone 14 landscape'] } },
+          // Android
+          { name: 'pixel-7', use: { ...devices['Pixel 7'] } },
+          // iPad
+          { name: 'ipad', use: { ...devices['iPad (gen 7)'] } },
+          { name: 'ipad-landscape', use: { ...devices['iPad (gen 7) landscape'] } },
+        ],
+      });
+
+  visual_regression:
+    name: "Visual Regression"
+    when: "Screenshot comparison testing"
+    config: |
+      import { defineConfig, devices } from '@playwright/test';
+      export default defineConfig({
+        testDir: './tests/visual',
+        snapshotDir: './tests/visual/__snapshots__',
+        updateSnapshots: process.env.UPDATE_SNAPSHOTS ? 'all' : 'missing',
+        expect: {
+          toHaveScreenshot: {
+            maxDiffPixelRatio: 0.01, // 1% tolerance
+            threshold: 0.2, // Color threshold
+            animations: 'disabled', // Freeze animations
+          },
+          toMatchSnapshot: {
+            maxDiffPixelRatio: 0.01,
+          },
+        },
+        use: {
+          baseURL: 'http://localhost:3000',
+          screenshot: 'on',
+          // Consistent rendering
+          colorScheme: 'dark',
+          locale: 'en-US',
+          timezoneId: 'America/New_York',
+        },
+        projects: [
+          { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+        ],
+      });
+    test_example: |
+      import { test, expect } from '@playwright/test';
+
+      test('homepage visual', async ({ page }) => {
+        await page.goto('/');
+        await page.waitForLoadState('networkidle');
+        await expect(page).toHaveScreenshot('homepage.png');
+      });
+
+      test('dark mode toggle', async ({ page }) => {
+        await page.goto('/');
+        await page.getByRole('button', { name: 'Toggle theme' }).click();
+        await expect(page).toHaveScreenshot('homepage-dark.png');
+      });
+
+# _DOMYH Awesome Code • Playwright Config Templates v1.0.0_