@nockdev/awf 6.2.0 → 6.2.1

package/.agent/skills/cross-cutting/playwright/data/interaction-checklist.yaml

@@ -0,0 +1,398 @@
+# =============================================================================
+# interaction-checklist.yaml — 58 Mandatory UI Interaction Checkpoints
+# =============================================================================
+# Agent MUST verify ALL applicable checkpoints for comprehensive testing.
+# Each checkpoint maps to specific MCP tools for execution.
+# =============================================================================
+
+version: "1.0.0"
+total_checkpoints: 58
+
+# =============================================================================
+# DROPDOWN (18 checkpoints)
+# =============================================================================
+dropdown:
+  count: 18
+
+  functional:
+    - id: DD-F01
+      check: "Click opens option list"
+      mcp_tool: browser_click
+      severity: critical
+      verify: "browser_snapshot → options visible"
+
+    - id: DD-F02
+      check: "All options present in correct order"
+      mcp_tool: browser_snapshot
+      severity: critical
+      verify: "Count options, verify order"
+
+    - id: DD-F03
+      check: "Selecting option updates displayed value"
+      mcp_tool: browser_select_option
+      severity: critical
+      verify: "browser_snapshot → selected value shown"
+
+    - id: DD-F04
+      check: "Default value displayed on load"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "Check initial state matches expected default"
+
+    - id: DD-F05
+      check: "Dependent dropdowns load correct options"
+      mcp_tool: browser_select_option
+      severity: high
+      verify: "Select parent → browser_snapshot child options"
+
+    - id: DD-F06
+      check: "Multi-select works (if applicable)"
+      mcp_tool: browser_select_option
+      severity: medium
+      verify: "Select multiple → verify all shown"
+
+    - id: DD-F07
+      check: "Search/filter functionality (if applicable)"
+      mcp_tool: browser_type
+      severity: medium
+      verify: "Type filter text → options filtered"
+
+  keyboard:
+    - id: DD-K01
+      check: "Tab key moves focus to dropdown"
+      mcp_tool: browser_press_key
+      severity: high
+      verify: "Press Tab → browser_snapshot focus state"
+
+    - id: DD-K02
+      check: "Enter/Space opens dropdown"
+      mcp_tool: browser_press_key
+      severity: high
+      verify: "Press Enter → options visible"
+
+    - id: DD-K03
+      check: "Up/Down arrows navigate options"
+      mcp_tool: browser_press_key
+      severity: high
+      verify: "Press ArrowDown → highlight moves"
+
+    - id: DD-K04
+      check: "Typing letter jumps to matching option"
+      mcp_tool: browser_press_key
+      severity: medium
+      verify: "Press 'V' → jumps to 'Vietnam'"
+
+    - id: DD-K05
+      check: "Escape closes dropdown"
+      mcp_tool: browser_press_key
+      severity: high
+      verify: "Press Escape → options hidden"
+
+  visual:
+    - id: DD-V01
+      check: "Text not truncated in dropdown"
+      mcp_tool: browser_snapshot
+      severity: medium
+      verify: "All text fully visible"
+
+    - id: DD-V02
+      check: "Scrolling works for long lists"
+      mcp_tool: browser_evaluate
+      severity: medium
+      verify: "Check scrollHeight > clientHeight"
+
+    - id: DD-V03
+      check: "No layout shift on open/close"
+      mcp_tool: browser_take_screenshot
+      severity: medium
+      verify: "Compare before/after screenshots"
+
+  validation:
+    - id: DD-VA01
+      check: "Required field shows error when empty"
+      mcp_tool: browser_click
+      severity: critical
+      verify: "Submit empty → browser_snapshot error message"
+
+    - id: DD-VA02
+      check: "Invalid input blocked (if editable)"
+      mcp_tool: browser_type
+      severity: high
+      verify: "Type invalid → blocked or error shown"
+
+    - id: DD-VA03
+      check: "Error message clear and informative"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "Read error text, verify helpful"
+
+# =============================================================================
+# MODAL (16 checkpoints)
+# =============================================================================
+modal:
+  count: 16
+
+  trigger_and_display:
+    - id: MD-TD01
+      check: "Trigger action opens modal"
+      mcp_tool: browser_click
+      severity: critical
+      verify: "Click trigger → browser_snapshot → modal visible"
+
+    - id: MD-TD02
+      check: "Modal centered with overlay"
+      mcp_tool: browser_take_screenshot
+      severity: high
+      verify: "Visual check: centered, overlay behind"
+
+    - id: MD-TD03
+      check: "Background interaction blocked"
+      mcp_tool: browser_click
+      severity: critical
+      verify: "Try clicking background element → should fail"
+
+    - id: MD-TD04
+      check: "Content fully visible, not cut off"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "All expected content in accessibility tree"
+
+  close_behavior:
+    - id: MD-CB01
+      check: "Close button (X) works"
+      mcp_tool: browser_click
+      severity: critical
+      verify: "Click X → browser_snapshot → modal gone"
+
+    - id: MD-CB02
+      check: "Overlay click closes (if designed)"
+      mcp_tool: browser_click
+      severity: high
+      verify: "Click overlay → modal closes"
+
+    - id: MD-CB03
+      check: "Escape key closes modal"
+      mcp_tool: browser_press_key
+      severity: critical
+      verify: "Press Escape → browser_snapshot → modal gone"
+
+    - id: MD-CB04
+      check: "Focus returns to trigger element"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "After close → focus on original trigger"
+
+  keyboard_accessibility:
+    - id: MD-KA01
+      check: "Tab cycles only within modal"
+      mcp_tool: browser_press_key
+      severity: critical
+      verify: "Tab multiple times → stays inside modal"
+
+    - id: MD-KA02
+      check: "Shift+Tab moves backward within modal"
+      mcp_tool: browser_press_key
+      severity: high
+      verify: "Shift+Tab → reverse cycle within modal"
+
+    - id: MD-KA03
+      check: "Focus cannot escape to background"
+      mcp_tool: browser_press_key
+      severity: critical
+      verify: "Tab exhaustively → never reaches background"
+
+    - id: MD-KA04
+      check: "Screen reader announces as dialog"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "Accessibility tree: role=dialog"
+
+  form_inside_modal:
+    - id: MD-FM01
+      check: "Form submit works within modal"
+      mcp_tool: browser_fill_form
+      severity: critical
+      verify: "Fill + submit → success state"
+
+    - id: MD-FM02
+      check: "Validation works inside modal"
+      mcp_tool: browser_click
+      severity: high
+      verify: "Submit empty → error messages visible"
+
+    - id: MD-FM03
+      check: "Success state displays correctly"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "After submit → success message/redirect"
+
+    - id: MD-FM04
+      check: "Error state displays correctly"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "On error → clear error message shown"
+
+# =============================================================================
+# BUTTON (14 checkpoints)
+# =============================================================================
+button:
+  count: 14
+
+  functional:
+    - id: BT-F01
+      check: "Click performs expected action"
+      mcp_tool: browser_click
+      severity: critical
+      verify: "Click → browser_snapshot → action happened"
+
+    - id: BT-F02
+      check: "State changes correctly (disabled, loading)"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "After action → state updated"
+
+    - id: BT-F03
+      check: "Rapid clicks don't duplicate (rage-click safe)"
+      mcp_tool: browser_click
+      severity: critical
+      verify: "Click 3x fast → only 1 action"
+
+    - id: BT-F04
+      check: "Disabled state not clickable"
+      mcp_tool: browser_click
+      severity: high
+      verify: "Click disabled → no action"
+
+    - id: BT-F05
+      check: "Navigation goes to correct page"
+      mcp_tool: browser_click
+      severity: critical
+      verify: "Click nav button → URL correct"
+
+    - id: BT-F06
+      check: "Toggle state works (if applicable)"
+      mcp_tool: browser_click
+      severity: medium
+      verify: "Click toggle → state flips"
+
+  visual:
+    - id: BT-V01
+      check: "Design consistent with design system"
+      mcp_tool: browser_take_screenshot
+      severity: medium
+      verify: "Visual matches expected style"
+
+    - id: BT-V02
+      check: "Clickable area (hitbox) accurate"
+      mcp_tool: browser_evaluate
+      severity: medium
+      verify: "Check element bounds match visual"
+
+    - id: BT-V03
+      check: "Text meaningful and clear"
+      mcp_tool: browser_snapshot
+      severity: medium
+      verify: "Button text describes action"
+
+    - id: BT-V04
+      check: "Responsive - no text truncation"
+      mcp_tool: browser_resize
+      severity: medium
+      verify: "Resize viewport → text still visible"
+
+  accessibility:
+    - id: BT-A01
+      check: "Tab order correct"
+      mcp_tool: browser_press_key
+      severity: high
+      verify: "Tab → reaches button in logical order"
+
+    - id: BT-A02
+      check: "Enter/Space activates button"
+      mcp_tool: browser_press_key
+      severity: high
+      verify: "Focus + Enter → action triggered"
+
+    - id: BT-A03
+      check: "Focus state visible"
+      mcp_tool: browser_take_screenshot
+      severity: high
+      verify: "Tab to button → visible outline/highlight"
+
+    - id: BT-A04
+      check: "Screen reader announces name correctly"
+      mcp_tool: browser_snapshot
+      severity: high
+      verify: "Accessibility tree: name matches purpose"
+
+# =============================================================================
+# HOVER STATE (10 checkpoints)
+# =============================================================================
+hover:
+  count: 10
+
+  trigger:
+    - id: HV-T01
+      check: "Hover triggers visual state change"
+      mcp_tool: browser_hover
+      severity: high
+      verify: "Hover → browser_take_screenshot → visual changed"
+
+    - id: HV-T02
+      check: "Hover content persists while hovering"
+      mcp_tool: browser_hover
+      severity: high
+      verify: "Hover → tooltip/menu stays visible"
+
+    - id: HV-T03
+      check: "Keyboard focus triggers equivalent state"
+      mcp_tool: browser_press_key
+      severity: high
+      verify: "Tab to element → same visual as hover"
+
+  content:
+    - id: HV-C01
+      check: "Hover content readable and formatted"
+      mcp_tool: browser_snapshot
+      severity: medium
+      verify: "Content text is clear and complete"
+
+    - id: HV-C02
+      check: "No layout shift (CLS) caused"
+      mcp_tool: browser_take_screenshot
+      severity: medium
+      verify: "Compare layout before/after hover"
+
+    - id: HV-C03
+      check: "Hover content doesn't obstruct other elements"
+      mcp_tool: browser_snapshot
+      severity: medium
+      verify: "No critical elements hidden"
+
+  dismiss:
+    - id: HV-D01
+      check: "Escape dismisses hover content"
+      mcp_tool: browser_press_key
+      severity: medium
+      verify: "Press Escape → hover content gone"
+
+    - id: HV-D02
+      check: "No interference with other elements"
+      mcp_tool: browser_click
+      severity: medium
+      verify: "Click elsewhere → hover dismissed cleanly"
+
+  technical:
+    - id: HV-TE01
+      check: "CSS :hover/:focus states correct"
+      mcp_tool: browser_evaluate
+      severity: medium
+      verify: "getComputedStyle check for hover/focus states"
+
+    - id: HV-TE02
+      check: "JavaScript hover handlers work"
+      mcp_tool: browser_hover
+      severity: high
+      verify: "Hover → JS-driven content appears"
+
+# _DOMYH Awesome Code • 58-Checkpoint Interaction Checklist v1.0.0_

package/.agent/skills/cross-cutting/playwright/data/locator-patterns.yaml

@@ -0,0 +1,96 @@
+# =============================================================================
+# locator-patterns.yaml — Priority-Ordered Locator Strategies
+# =============================================================================
+
+version: "1.0.0"
+
+priority_order:
+  - priority: 1
+    method: "getByRole()"
+    type: "Semantic (ARIA role)"
+    use_case: "Buttons, links, headings, navigation — preferred for ALL interactive elements"
+    examples:
+      - 'page.getByRole("button", { name: "Submit" })'
+      - 'page.getByRole("link", { name: "Home" })'
+      - 'page.getByRole("heading", { level: 1 })'
+      - 'page.getByRole("navigation")'
+      - 'page.getByRole("dialog")'
+      - 'page.getByRole("combobox")'
+      - 'page.getByRole("menuitem", { name: "Settings" })'
+    why_best: "Matches how users and assistive tech find elements. Resilient to style/class changes."
+    avoid_when: "Element has no ARIA role (rare in modern frameworks)"
+
+  - priority: 2
+    method: "getByLabel()"
+    type: "Form label association"
+    use_case: "Form inputs, textareas, selects — via linked label element"
+    examples:
+      - 'page.getByLabel("Email")'
+      - 'page.getByLabel("Password")'
+      - 'page.getByLabel("Remember me")'
+    why_best: "Matches user-visible label text. Natural and readable."
+    avoid_when: "Element has no associated label"
+
+  - priority: 3
+    method: "getByTestId()"
+    type: "Explicit test marker"
+    use_case: "When no semantic way to identify — use data-testid attribute"
+    examples:
+      - 'page.getByTestId("submit-button")'
+      - 'page.getByTestId("user-avatar")'
+      - 'page.getByTestId("sidebar-nav")'
+    setup: |
+      <!-- HTML -->
+      <button data-testid="submit-button">Submit</button>
+
+      // playwright.config.ts
+      use: { testIdAttribute: 'data-testid' }
+    why_best: "Explicit, stable, won't change with CSS refactors."
+    avoid_when: "Semantic locator available (role or label)"
+
+  - priority: 4
+    method: "getByText()"
+    type: "Visible text content"
+    use_case: "Static text, paragraph content, error messages"
+    examples:
+      - 'page.getByText("Welcome back")'
+      - 'page.getByText("Error: invalid email", { exact: true })'
+      - 'page.getByText(/total: \$[\d.]+/)'
+    why_best: "Simple, matches what user sees."
+    avoid_when: "Text is dynamic or duplicated across elements"
+
+  - priority: 5
+    method: "locator() CSS"
+    type: "CSS selector"
+    use_case: "LAST RESORT — complex DOM traversal, nth-child, attribute selectors"
+    examples:
+      - 'page.locator(".card:first-child .title")'
+      - 'page.locator("[data-status=active]")'
+      - 'page.locator("table >> tr:nth-child(3)")'
+    why_best: "Maximum flexibility for complex structures."
+    avoid_when: "ALWAYS try priorities 1-4 first"
+    warning: "Brittle — breaks on CSS refactors"
+
+anti_patterns:
+  - pattern: 'page.locator("#app > div > div:nth-child(3) > button")'
+    problem: "Fragile path-based selector, breaks on any DOM change"
+    fix: 'page.getByRole("button", { name: "Submit" })'
+
+  - pattern: 'page.locator(".btn-primary.submit-btn")'
+    problem: "CSS class names change during refactors"
+    fix: 'page.getByRole("button", { name: "Submit" })'
+
+  - pattern: 'page.locator("//button[@class=\"submit\"]")'
+    problem: "XPath is verbose and brittle"
+    fix: 'page.getByRole("button", { name: "Submit" })'
+
+# For MCP browser_snapshot:
+# - Snapshot returns refs (e.g., "ref=submit-btn")
+# - Use these refs directly in browser_click, browser_type, etc.
+# - No need to manually construct locators when using MCP tools
+mcp_note: |
+  When using Playwright MCP tools, browser_snapshot returns element refs.
+  Use these refs directly: browser_click(ref="S3E2") instead of constructing locators.
+  The refs are from the accessibility tree — already the best locator strategy.
+
+# _DOMYH Awesome Code • Locator Patterns v1.0.0_

package/.agent/skills/cross-cutting/playwright/data/mcp-tools.yaml

@@ -0,0 +1,153 @@
+# =============================================================================
+# mcp-tools.yaml — Playwright MCP Tool Reference (19 tools)
+# =============================================================================
+
+version: "1.0.0"
+
+navigation:
+  - name: browser_navigate
+    args: { url: "string (required)" }
+    purpose: "Navigate to URL"
+    when: "Opening a page, following a link"
+    example: 'browser_navigate(url="http://localhost:3000/dashboard")'
+
+  - name: browser_navigate_back
+    args: {}
+    purpose: "Go back in history"
+    when: "Testing back navigation, breadcrumb flows"
+    example: "browser_navigate_back()"
+
+  - name: browser_close
+    args: {}
+    purpose: "Close browser/tab"
+    when: "Cleanup after testing, closing popup windows"
+    example: "browser_close()"
+
+  - name: browser_resize
+    args: { width: "number", height: "number" }
+    purpose: "Change viewport size"
+    when: "Testing responsive design, mobile views"
+    example: "browser_resize(width=375, height=812)  # iPhone"
+
+  - name: browser_tabs
+    args: { action: "list|new|close|select", index: "number (optional)" }
+    purpose: "Manage browser tabs"
+    when: "Multi-tab testing, popup handling"
+    example: 'browser_tabs(action="list")'
+
+interaction:
+  - name: browser_click
+    args: { ref: "string", element: "string (description)" }
+    purpose: "Click element"
+    when: "Button clicks, link navigation, tab switching, accordion toggle"
+    critical_for: ["button", "link", "tab", "accordion", "modal trigger"]
+    example: 'browser_click(ref="submit-btn", element="Submit button")'
+
+  - name: browser_type
+    args: { ref: "string", text: "string", submit: "boolean" }
+    purpose: "Type text into element"
+    when: "Form input, search fields, text areas"
+    critical_for: ["input", "textarea", "search"]
+    example: 'browser_type(ref="email-input", text="user@test.com")'
+
+  - name: browser_press_key
+    args: { key: "string" }
+    purpose: "Press keyboard key"
+    when: "Escape to close modal, Enter to submit, Tab to navigate"
+    critical_for: ["modal close", "form submit", "keyboard navigation"]
+    example: 'browser_press_key(key="Escape")  # Close modal'
+
+  - name: browser_hover
+    args: { ref: "string", element: "string" }
+    purpose: "Hover over element"
+    when: "Tooltip display, dropdown menu trigger, hover state change"
+    critical_for: ["tooltip", "dropdown menu", "hover state"]
+    example: 'browser_hover(ref="user-avatar", element="User avatar with tooltip")'
+
+  - name: browser_select_option
+    args: { ref: "string", values: "string[]" }
+    purpose: "Select dropdown option"
+    when: "Native <select> dropdown selection"
+    critical_for: ["dropdown", "select"]
+    example: 'browser_select_option(ref="country-select", values=["vietnam"])'
+
+  - name: browser_drag
+    args: { startRef: "string", endRef: "string" }
+    purpose: "Drag and drop"
+    when: "Reorder items, drag-to-upload, kanban boards"
+    critical_for: ["drag-drop", "reorder", "kanban"]
+    example: 'browser_drag(startRef="task-1", endRef="done-column")'
+
+  - name: browser_file_upload
+    args: { paths: "string[]" }
+    purpose: "Upload files"
+    when: "File input, avatar upload, document attachment"
+    critical_for: ["file input", "upload"]
+    example: 'browser_file_upload(paths=["/tmp/test.png"])'
+
+  - name: browser_handle_dialog
+    args: { accept: "boolean", promptText: "string (optional)" }
+    purpose: "Handle browser dialogs"
+    when: "Alert, confirm, prompt dialogs"
+    critical_for: ["alert", "confirm", "prompt"]
+    example: "browser_handle_dialog(accept=true)"
+
+  - name: browser_fill_form
+    args: { fields: "array of {ref, type, value}" }
+    purpose: "Fill multiple form fields at once"
+    when: "Complex forms with many fields"
+    critical_for: ["form", "registration", "checkout"]
+    example: |
+      browser_fill_form(fields=[
+        { ref: "name", type: "textbox", value: "John" },
+        { ref: "agree", type: "checkbox", value: "true" }
+      ])
+
+observation:
+  - name: browser_snapshot
+    args: {}
+    purpose: "Capture accessibility tree (structured page state)"
+    when: "ALWAYS FIRST — understand page structure before interaction"
+    critical_for: ["page understanding", "element discovery", "LLM context"]
+    note: "PREFERRED over screenshot for LLM — structured, fast, lightweight"
+    example: "browser_snapshot()  # Returns accessibility tree with refs"
+
+  - name: browser_take_screenshot
+    args: { type: "png|jpeg", fullPage: "boolean", ref: "string (optional)" }
+    purpose: "Capture visual screenshot"
+    when: "Visual verification, debugging, evidence collection"
+    critical_for: ["visual verification", "bug evidence", "reporting"]
+    example: 'browser_take_screenshot(type="png", fullPage=true)'
+
+  - name: browser_evaluate
+    args: { function: "string (JS code)" }
+    purpose: "Execute JavaScript in page context"
+    when: "Check CSS computed styles, DOM state, local storage"
+    critical_for: ["DOM inspection", "CSS validation", "state check"]
+    example: |
+      browser_evaluate(function="() => {
+        return document.querySelector('.modal').style.display;
+      }")
+
+  - name: browser_console_messages
+    args: { level: "error|warning|info|debug" }
+    purpose: "Read browser console messages"
+    when: "Error detection, warning check, debugging"
+    critical_for: ["error detection", "warning check"]
+    example: 'browser_console_messages(level="error")'
+
+  - name: browser_network_requests
+    args: { includeStatic: "boolean" }
+    purpose: "List network requests"
+    when: "API call verification, failed request detection"
+    critical_for: ["API verification", "404 detection", "CORS check"]
+    example: "browser_network_requests(includeStatic=false)"
+
+# Usage Strategy
+strategy:
+  always_first: "browser_snapshot — understand page before interacting"
+  for_interaction: "browser_click → browser_snapshot — verify state change"
+  for_debugging: "browser_console_messages + browser_network_requests"
+  for_evidence: "browser_take_screenshot — capture visual proof"
+
+# _DOMYH Awesome Code • Playwright MCP Tools Reference v1.0.0_