agent-skill-kit 3.9.135

package/.agent/skills/e2e-automation/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: e2e-automation
+description: >-
+  End-to-end testing with Playwright, browser automation, and visual regression testing.
+  Use when writing Playwright tests, browser automation scripts, or visual testing.
+  NOT for test architecture decisions (use test-architect) or unit tests.
+category: testing
+triggers: ["E2E test", "Playwright", "browser test", "visual testing", "automation"]
+coordinates_with: ["test-architect", "cicd-pipeline"]
+success_metrics: ["100% stable tests (0 flake)", "100% coverage on critical paths"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# E2E Automation — Playwright Testing
+
+> Behavior-driven E2E tests. `data-testid` selectors. Auto-wait, never sleep. Zero flake tolerance.
+
+---
+
+## Prerequisites
+
+**Required:** Playwright installed with Chromium browser.
+
+```bash
+npm install playwright && npx playwright install chromium
+```
+
+---
+
+## When to Use
+
+| Situation | Action |
+|-----------|--------|
+| Critical user flows | E2E with Playwright runner |
+| Visual regression | Screenshot comparison (`--screenshot`) |
+| Accessibility audit | A11y check (`--a11y`) |
+| Component/unit testing | Use `test-architect` instead |
+| API testing only | Use `test-architect` instead |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Playwright test runner (`scripts/playwright_runner.ts`) | Unit/integration patterns (→ test-architect) |
+| Screenshot capture (on-failure + on-demand) | Performance benchmarking (→ perf-optimizer) |
+| Accessibility audit (axe-core via `--a11y`) | CI/CD pipeline config (→ cicd-pipeline) |
+| ARIA snapshot testing reference | Browser scraping (→ agent-browser) |
+| Test organization structure | Test content authoring |
+
+**Automation skill:** Launches browser, navigates pages, captures screenshots. Session-based with side effects.
+
+---
+
+## Quick Reference
+
+```bash
+# Run Playwright tests
+node .agent/skills/e2e-automation/scripts/playwright_runner.ts https://example.com
+
+# With screenshot
+node .agent/skills/e2e-automation/scripts/playwright_runner.ts <url> --screenshot
+
+# Accessibility check
+node .agent/skills/e2e-automation/scripts/playwright_runner.ts <url> --a11y
+```
+
+---
+
+## Playwright Config (Fixed Recommendations)
+
+| Setting | Value | Rationale |
+|---------|-------|-----------|
+| Retries (CI) | 2 | Flake mitigation |
+| Retries (local) | 0 | Development speed |
+| Trace | on-first-retry | Disk space control |
+| Screenshots | on-failure | Failure diagnosis |
+| Video | retain-on-failure | Complex failure analysis |
+
+---
+
+## E2E Best Practices
+
+| Rule | Enforcement |
+|------|------------|
+| Use `data-testid` selectors | CSS/XPath selectors forbidden |
+| Auto-wait for elements | No `sleep()` or `setTimeout()` |
+| Clean state per test | Fresh browser context each test |
+| Test user behavior | Assert visible outcomes, not DOM structure |
+| Isolate test data | No shared data between tests |
+
+---
+
+## Test Organization
+
+```
+tests/
+├── e2e/           # Full user flows
+├── integration/   # API, data
+├── component/     # UI units
+└── fixtures/      # Shared test data
+```
+
+---
+
+## Session Lifecycle
+
+```
+IDLE → LAUNCHING          [run-tests invoked]
+LAUNCHING → NAVIGATING    [browser started]
+NAVIGATING → EXECUTING    [target loaded]
+EXECUTING → CAPTURING     [screenshot/trace needed]
+CAPTURING → REPORTING     [artifacts saved]
+REPORTING → COMPLETED     [results output]  // terminal
+LAUNCHING → ERROR         [browser launch failed]  // terminal
+NAVIGATING → ERROR        [target unreachable]  // terminal
+```
+
+**Invariant:** Browser process ALWAYS terminated in Report phase. No orphaned processes.
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_PLAYWRIGHT_MISSING` | Yes | Playwright not installed |
+| `ERR_BROWSER_LAUNCH` | Yes | Browser failed to start |
+| `ERR_TARGET_UNREACHABLE` | Yes | Target URL not reachable |
+| `ERR_TIMEOUT` | Yes | Test exceeded timeout |
+| `ERR_SELECTOR_NOT_FOUND` | Yes | Element not found on page |
+| `ERR_ASSERTION_FAILED` | No | Test assertion did not pass |
+| `ERR_A11Y_VIOLATION` | Yes | WCAG violation detected |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Test implementation details | Test user-visible behavior |
+| Hardcode waits (`sleep`) | Use Playwright auto-wait |
+| Skip test cleanup | Isolate with fresh context |
+| Ignore flaky tests | Fix root cause; track flake rate |
+| Use CSS/XPath selectors | Use `data-testid` attributes |
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [aria-snapshot.md](rules/aria-snapshot.md) | ARIA snapshot testing pattern | ARIA-based tests |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec | Architecture review |
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/playwright_runner.ts` | Test execution runner |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `/validate` | Workflow | Run all tests |
+| `test-architect` | Skill | Unit/integration patterns |
+| `cicd-pipeline` | Skill | CI integration |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/e2e-automation/rules/_sections.md

@@ -0,0 +1,20 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Aria (aria)
+
+**Impact:** LOW  
+**Description:** Aria patterns and best practices.
+
+## 2. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/e2e-automation/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/e2e-automation/rules/aria-snapshot.md

@@ -0,0 +1,185 @@
+---
+title: ARIA Snapshot Pattern
+impact: MEDIUM
+tags: e2e-automation
+---
+
+# ARIA Snapshot Pattern
+
+> Element Discovery via Accessibility Tree instead of CSS Selectors.
+
+---
+
+## Why Use ARIA Snapshot?
+
+| CSS Selectors | ARIA Snapshot |
+|---------------|---------------|
+| Easily breaks when markup changes | Resilient based on semantics |
+| Depends on class names | Based on accessibility roles |
+| AI has a hard time inferring correct selector | AI can read page structure |
+
+---
+
+## ARIA Snapshot Format
+
+```yaml
+- banner:
+  - link "Hacker News" [ref=e1]
+- main:
+  - list:
+    - listitem:
+      - link "Show HN: Project" [ref=e8]
+      - text "123 points"
+- footer:
+  - link "Guidelines" [ref=e12]
+```
+
+**Key features:**
+- `[ref=e1]` - ID to interact with
+- Semantic roles: `banner`, `main`, `footer`
+- Nested structure easy to read
+
+---
+
+## Interact By Ref
+
+```bash
+# Get ARIA snapshot first
+node aria-snapshot.ts --url https://example.com
+
+# Then interact by ref
+node select-ref.ts --ref e5 --action click
+node select-ref.ts --ref e10 --action fill --value "text"
+node select-ref.ts --ref e3 --action hover
+```
+
+---
+
+## Supported Actions
+
+| Action | Description |
+|--------|-------------|
+| click | Click element |
+| fill | Type text into input |
+| hover | Hover over element |
+| select | Select dropdown option |
+| check | Check checkbox |
+| press | Press keyboard key |
+
+---
+
+## Sample ARIA Snapshot Script
+
+```javascript
+// aria-snapshot.ts
+import { chromium } from 'playwright';
+
+async function getAriaSnapshot(url) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto(url);
+  
+  // Get accessibility tree
+  const snapshot = await page.accessibility.snapshot();
+  
+  let refId = 1;
+  const formatNode = (node, indent = 0) => {
+    const spaces = '  '.repeat(indent);
+    let result = '';
+    
+    if (node.role !== 'none' && node.role !== 'generic') {
+      const ref = node.focused || node.name ? ` [ref=e${refId++}]` : '';
+      const name = node.name ? ` "${node.name}"` : '';
+      result += `${spaces}- ${node.role}${name}${ref}\n`;
+    }
+    
+    if (node.children) {
+      for (const child of node.children) {
+        result += formatNode(child, indent + 1);
+      }
+    }
+    return result;
+  };
+  
+  console.log(formatNode(snapshot));
+  await browser.close();
+}
+
+getAriaSnapshot(process.argv[2] || 'https://example.com');
+```
+
+---
+
+## Select By Ref Script
+
+```javascript
+// select-ref.ts
+import { chromium } from 'playwright';
+
+async function selectByRef(url, ref, action, value) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto(url);
+  
+  // Build ref selector (simplified)
+  const snapshot = await page.accessibility.snapshot();
+  const element = findByRef(snapshot, ref);
+  
+  if (!element) {
+    console.error(`Ref ${ref} not found`);
+    process.exit(1);
+  }
+  
+  // Get locator by role + name
+  const locator = page.getByRole(element.role, { name: element.name });
+  
+  switch (action) {
+    case 'click':
+      await locator.click();
+      break;
+    case 'fill':
+      await locator.fill(value);
+      break;
+    case 'hover':
+      await locator.hover();
+      break;
+    default:
+      console.error(`Unknown action: ${action}`);
+  }
+  
+  await browser.close();
+}
+```
+
+---
+
+## Best Practices
+
+1. **Always get fresh snapshot** before interacting
+2. **Use semantic roles** not class-based selectors
+3. **Ref IDs are session-specific** - don't hardcode
+4. **Prefer getByRole()** over CSS selectors
+
+---
+
+## Integration with Playwright
+
+```typescript
+// In your test
+test('user can submit form', async ({ page }) => {
+  // Prefer role-based selectors
+  await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  await page.getByRole('button', { name: 'Submit' }).click();
+  
+  // Over CSS selectors
+  // await page.locator('#email').fill('test@example.com');
+});
+```
+
+---
+
+> **Rule:** ARIA Snapshot + Role Selectors = AI-friendly, resilient tests.
+
+---
+
+⚡ PikaKit v3.9.134