@hustle-together/api-dev-tools 3.12.3 → 4.5.1

package/.skills/test-all/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: test-all
+description: Run comprehensive test suite - unit, e2e, visual, builds, and code review
+tools: Bash, Read, Glob, TodoWrite, Task
+model: sonnet
+---
+
+# Test All Skill
+
+Run the complete test suite in sequence: unit tests, E2E tests, visual tests, build verification, and code review.
+
+## When to Use
+
+- Before creating a pull request
+- After completing a major feature
+- Before deploying to production
+- As a final verification step
+
+## Execution Sequence
+
+```
+┌──────────────────────────────────────────────────┐
+│                   /test-all                       │
+├──────────────────────────────────────────────────┤
+│                                                  │
+│  1. Unit Tests (/test-unit)                      │
+│     └─→ If fails: Stop and report               │
+│                                                  │
+│  2. E2E Tests (/test-e2e)                        │
+│     └─→ If fails: Stop and report               │
+│                                                  │
+│  3. Visual Tests (/test-visual)                  │
+│     └─→ If fails: Stop and report               │
+│                                                  │
+│  4. Build Verification (/test-builds)            │
+│     └─→ If fails: Stop and report               │
+│                                                  │
+│  5. Code Review (/test-review)                   │
+│     └─→ Report findings (doesn't block)         │
+│                                                  │
+│  ✅ All Passed → Ready for PR                    │
+│                                                  │
+└──────────────────────────────────────────────────┘
+```
+
+## Execution Steps
+
+### Step 1: Unit Tests
+
+```bash
+# Run unit tests with coverage
+pnpm test:coverage
+```
+
+**Gate:** Must pass before continuing.
+
+### Step 2: E2E Tests
+
+```bash
+# Run Playwright tests
+npx playwright test
+```
+
+**Gate:** Must pass before continuing.
+
+### Step 3: Visual Tests
+
+```bash
+# Run visual regression
+pnpm test-storybook
+```
+
+**Gate:** Must pass before continuing.
+
+### Step 4: Build Verification
+
+```bash
+# Verify all platforms build
+pnpm build
+
+# TypeScript check
+pnpm typecheck
+```
+
+**Gate:** Must pass before continuing.
+
+### Step 5: Code Review
+
+Spawn code-reviewer agent for analysis:
+
+```
+Task({
+  subagent_type: "code-reviewer",
+  prompt: "Review recent changes for security, performance, and best practices"
+})
+```
+
+**Note:** Findings are reported but don't block.
+
+## Progress Tracking
+
+Use TodoWrite for visibility:
+
+```
+[ ] Unit Tests
+[ ] E2E Tests
+[ ] Visual Tests
+[ ] Build Verification
+[ ] Code Review
+```
+
+## Report Format
+
+```
+═══════════════════════════════════════════════════════
+                    TEST SUITE RESULTS
+═══════════════════════════════════════════════════════
+
+┌─────────────────┬────────┬──────────┬───────────────┐
+│ Suite           │ Status │ Duration │ Details       │
+├─────────────────┼────────┼──────────┼───────────────┤
+│ Unit Tests      │ ✅     │ 3.2s     │ 42 passed     │
+│ E2E Tests       │ ✅     │ 45s      │ 96 passed     │
+│ Visual Tests    │ ✅     │ 28s      │ 84 screenshots│
+│ Build           │ ✅     │ 12s      │ All platforms │
+│ Code Review     │ ⚠️     │ 5s       │ 2 suggestions │
+└─────────────────┴────────┴──────────┴───────────────┘
+
+Total Duration: 1m 33s
+
+Code Review Findings:
+1. [Minor] Consider memoizing expensive calculation in Dashboard
+2. [Suggestion] Add rate limiting to public API endpoints
+
+═══════════════════════════════════════════════════════
+                  ✅ READY FOR PR
+═══════════════════════════════════════════════════════
+```
+
+## Failure Handling
+
+When a suite fails, stop immediately and report:
+
+```
+═══════════════════════════════════════════════════════
+                    TEST SUITE FAILED
+═══════════════════════════════════════════════════════
+
+Failed at: E2E Tests
+
+✅ Unit Tests     - 42 passed
+❌ E2E Tests      - 1 failed
+
+Failure Details:
+─────────────────────────────────────────────────────
+Test: tests/auth.spec.ts:24
+Name: "should redirect after login"
+Error: Timeout waiting for navigation
+
+Screenshot: test-results/auth-should-redirect.png
+Trace: test-results/auth-should-redirect/trace.zip
+
+Suggested Fix:
+- Check login API response
+- Verify redirect URL configuration
+─────────────────────────────────────────────────────
+
+Remaining suites skipped:
+- Visual Tests
+- Build Verification
+- Code Review
+
+Fix the failure and run /test-all again.
+═══════════════════════════════════════════════════════
+```
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--skip-visual` | Skip visual tests | false |
+| `--skip-review` | Skip code review | false |
+| `--continue-on-fail` | Don't stop on failure | false |
+
+## Examples
+
+```bash
+# Run complete suite
+/test-all
+
+# Skip visual tests (faster)
+/test-all --skip-visual
+
+# Continue even if tests fail
+/test-all --continue-on-fail
+```
+
+## Integration
+
+This is typically the final step before:
+- `/commit` - Create commit
+- `/pr` - Create pull request
+
+## See Also
+
+- `/test-unit` - Unit tests only
+- `/test-e2e` - E2E tests only
+- `/test-visual` - Visual tests only
+- `/test-builds` - Build verification only
+- `/test-review` - Code review only

package/.skills/test-builds/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: test-builds
+description: Verify web builds and cross-browser compatibility (Chrome, Firefox, Safari/WebKit)
+tools: Bash, Read, Glob, TodoWrite
+model: sonnet
+---
+
+# Test Builds Skill
+
+Verify that the application builds successfully and runs correctly across all major browsers.
+
+> **Note:** This skill focuses on **web builds and browser testing**. For native desktop
+> (Tauri/Electron) or mobile (Capacitor) builds, those should be tested separately
+> as they theoretically work with the same web code but require native toolchains.
+
+## Philosophy
+
+If your app works in Chrome, Firefox, and Safari (WebKit), it will work in:
+- **Tauri** - Uses system WebView (WebKit on macOS, Chromium on Windows/Linux)
+- **Capacitor** - Uses WKWebView (iOS) and Android WebView (Chromium)
+- **Electron** - Bundles Chromium
+- **PWA** - Runs in user's browser
+
+Therefore, comprehensive browser testing = comprehensive platform coverage.
+
+## When to Use
+
+- Before releasing a new version
+- After major dependency updates
+- After CSS/layout changes
+- As part of CI/CD pipeline verification
+
+## Execution Steps
+
+### Step 1: Web Build Verification
+
+```bash
+# Build the Next.js/Vite application
+pnpm build
+
+# Verify output exists
+ls -la .next/ || ls -la dist/
+
+# TypeScript check
+pnpm typecheck || npx tsc --noEmit
+```
+
+### Step 2: Cross-Browser Testing with Playwright
+
+```bash
+# Run E2E tests across all 3 browser engines
+npx playwright test --project=chromium
+npx playwright test --project=firefox
+npx playwright test --project=webkit
+
+# Or all at once
+npx playwright test
+```
+
+**Browser Coverage:**
+
+| Browser Engine | Covers | Test Project |
+|----------------|--------|--------------|
+| **Chromium** | Chrome, Edge, Opera, Brave, Android WebView | `--project=chromium` |
+| **Firefox** | Firefox, Firefox ESR | `--project=firefox` |
+| **WebKit** | Safari, iOS Safari, WKWebView | `--project=webkit` |
+
+### Step 3: PWA Compliance Check (if applicable)
+
+```bash
+# Check if manifest.json exists and is valid
+cat public/manifest.json | jq .
+
+# Verify service worker registration
+grep -r "serviceWorker" src/
+
+# Check for required PWA assets
+ls -la public/icon-*.png
+```
+
+### Step 4: Bundle Analysis
+
+```bash
+# Next.js bundle analysis
+ANALYZE=true pnpm build
+
+# Or Vite bundle visualizer
+npx vite-bundle-visualizer
+```
+
+## Report Format
+
+```
+═══════════════════════════════════════════════════════
+                    BUILD RESULTS
+═══════════════════════════════════════════════════════
+
+Web Build:
+┌─────────────┬────────┬──────────┬─────────────────────┐
+│ Step        │ Status │ Duration │ Details             │
+├─────────────┼────────┼──────────┼─────────────────────┤
+│ Build       │ ✅     │ 12.3s    │ .next/ (4.2 MB)     │
+│ TypeScript  │ ✅     │ 3.2s     │ No errors           │
+│ ESLint      │ ✅     │ 5.1s     │ No warnings         │
+└─────────────┴────────┴──────────┴─────────────────────┘
+
+Cross-Browser Testing:
+┌─────────────┬────────┬──────────┬─────────────────────┐
+│ Browser     │ Status │ Tests    │ Coverage            │
+├─────────────┼────────┼──────────┼─────────────────────┤
+│ Chromium    │ ✅     │ 45/45    │ Chrome, Edge, Brave │
+│ Firefox     │ ✅     │ 45/45    │ Firefox             │
+│ WebKit      │ ✅     │ 45/45    │ Safari, iOS Safari  │
+└─────────────┴────────┴──────────┴─────────────────────┘
+
+Bundle Size Analysis:
+───────────────────────────────────────
+Total: 245 KB (gzipped)
+  - First Load JS: 87 KB
+  - Shared Chunks: 158 KB
+
+Platform Compatibility:
+───────────────────────────────────────
+✅ Chromium-based apps (Tauri Win/Linux, Capacitor Android, Electron)
+✅ WebKit-based apps (Tauri macOS, Capacitor iOS)
+✅ PWA (all browsers)
+
+Note: Native builds (Tauri/Capacitor) should be tested separately
+with their respective toolchains if using native features.
+
+═══════════════════════════════════════════════════════
+              ✅ ALL BROWSER TESTS PASSED
+═══════════════════════════════════════════════════════
+```
+
+## Native Platform Notes
+
+### If You Use Tauri (Desktop)
+
+```bash
+# Install Tauri CLI
+pnpm add -D @tauri-apps/cli
+
+# Test desktop build (requires Rust)
+pnpm tauri build --debug
+
+# Platforms:
+# - macOS: Uses WebKit (tested via Playwright webkit)
+# - Windows/Linux: Uses WebView2/Chromium (tested via Playwright chromium)
+```
+
+### If You Use Capacitor (Mobile)
+
+```bash
+# Install Capacitor
+pnpm add @capacitor/core @capacitor/ios @capacitor/android
+
+# Sync web assets to native projects
+npx cap sync
+
+# Platforms:
+# - iOS: Uses WKWebView (tested via Playwright webkit)
+# - Android: Uses Android WebView (tested via Playwright chromium)
+```
+
+### Why We Don't Build These By Default
+
+1. **Requires native toolchains** - Xcode, Android Studio, Rust
+2. **LLM interpretation varies** - Native setup is complex, error-prone
+3. **Web testing is sufficient** - If it works in browsers, it works in webviews
+4. **Separation of concerns** - Web build vs native packaging
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--browsers` | Specific browsers to test | All 3 |
+| `--analyze` | Include bundle analysis | false |
+| `--pwa` | Check PWA compliance | auto-detect |
+
+## Examples
+
+```bash
+# Full build + all browsers
+/test-builds
+
+# Quick check (Chromium only)
+/test-builds --browsers=chromium
+
+# With bundle analysis
+/test-builds --analyze
+
+# PWA compliance check
+/test-builds --pwa
+```
+
+## Integration
+
+This skill is invoked:
+- During `/test-all` as step 4
+- Before release workflows
+- In CI/CD pipelines
+
+## See Also
+
+- `/test-all` - Complete test suite
+- `/test-e2e` - E2E tests (uses same Playwright)
+- `/test-visual` - Visual regression

package/.skills/test-debug/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: test-debug
+description: Analyze Playwright test failures with screenshots, DOM snapshots, and root cause diagnosis
+tools: Bash, Read, Glob, Grep, Task
+model: sonnet
+---
+
+# Test Debug Skill
+
+Diagnose and debug test failures by analyzing error messages, screenshots, traces, and DOM snapshots to identify root causes.
+
+## When to Use
+
+- When tests fail and you don't know why
+- After seeing a failing test report
+- When tests pass locally but fail in CI
+- To understand flaky test behavior
+
+## Execution Steps
+
+### Step 1: Identify Failed Tests
+
+```bash
+# Find recent test failures
+ls -la test-results/
+
+# Or parse last test run
+cat test-results/.last-run.json 2>/dev/null
+
+# Find Playwright traces
+find test-results -name "trace.zip"
+```
+
+### Step 2: Gather Failure Context
+
+For each failed test, collect:
+
+1. **Error Message**
+   ```bash
+   cat test-results/test-name/error.txt
+   ```
+
+2. **Screenshot** (if available)
+   ```bash
+   ls test-results/test-name/*.png
+   ```
+
+3. **Trace File** (for Playwright)
+   ```bash
+   ls test-results/test-name/trace.zip
+   ```
+
+4. **Console Logs**
+   ```bash
+   cat test-results/test-name/console.log
+   ```
+
+### Step 3: Analyze Failure
+
+Present structured analysis:
+
+```
+═══════════════════════════════════════════════════════
+                    TEST FAILURE ANALYSIS
+═══════════════════════════════════════════════════════
+
+Test: tests/dashboard.spec.ts:42
+Name: "should display user stats after login"
+
+Error Type: TimeoutError
+Message: Timeout 30000ms exceeded waiting for selector "[data-testid='stats-card']"
+
+Timeline:
+───────────────────────────────────────
+00:00 - Navigation to /login
+00:02 - Fill email input
+00:03 - Fill password input
+00:04 - Click submit button
+00:05 - Wait for redirect to /dashboard
+00:08 - ❌ TIMEOUT waiting for stats-card
+───────────────────────────────────────
+
+Screenshot Analysis:
+───────────────────────────────────────
+The page shows an error message:
+"Failed to load user data. Please try again."
+
+This indicates the API call failed, not a selector issue.
+───────────────────────────────────────
+
+Root Cause: API Error
+───────────────────────────────────────
+The test failed because the backend API returned an error,
+preventing the stats-card component from rendering.
+
+Likely Causes:
+1. Backend server not running during test
+2. Test database not seeded with user data
+3. API rate limiting triggered during test run
+4. Authentication token expired
+
+Suggested Fixes:
+1. Ensure test backend is running:
+   pnpm test:backend &
+
+2. Seed test database before tests:
+   pnpm db:seed:test
+
+3. Check API mock configuration:
+   tests/mocks/handlers.ts
+
+4. Add retry logic for flaky API calls:
+   await expect(page.getByTestId('stats-card'))
+     .toBeVisible({ timeout: 60000 });
+
+═══════════════════════════════════════════════════════
+```
+
+### Step 4: Provide Actionable Fix
+
+Based on root cause, suggest specific code changes:
+
+```typescript
+// Before (failing)
+await expect(page.getByTestId('stats-card')).toBeVisible();
+
+// After (fixed)
+// Wait for loading to complete first
+await page.waitForLoadState('networkidle');
+await expect(page.getByTestId('stats-card')).toBeVisible({ timeout: 60000 });
+```
+
+## Failure Categories
+
+| Category | Symptoms | Common Causes |
+|----------|----------|---------------|
+| Timeout | "Timeout exceeded" | Slow API, missing element |
+| Selector | "Cannot find element" | Wrong selector, dynamic ID |
+| Assertion | "Expected X, got Y" | Logic error, race condition |
+| Network | "NetworkError" | Backend down, CORS |
+| Authentication | "401 Unauthorized" | Token expired, wrong env |
+
+## Debug Commands
+
+```bash
+# View Playwright trace in browser
+npx playwright show-trace test-results/test-name/trace.zip
+
+# Open HTML report
+npx playwright show-report
+
+# Run specific test with debug mode
+npx playwright test tests/failing.spec.ts --debug
+
+# Run with headed browser to see what's happening
+npx playwright test tests/failing.spec.ts --headed
+```
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `[test-name]` | Specific test to debug | Latest failed |
+| `--trace` | Open trace viewer | false |
+| `--headed` | Re-run in headed mode | false |
+| `--step` | Step through test | false |
+
+## Examples
+
+```bash
+# Debug latest failure
+/test-debug
+
+# Debug specific test
+/test-debug dashboard-login
+
+# Open trace viewer
+/test-debug --trace
+
+# Re-run with visible browser
+/test-debug --headed
+```
+
+## Output Format
+
+```
+═══════════════════════════════════════
+Debug Analysis: 🔍 Complete
+═══════════════════════════════════════
+Failed Test:  dashboard-login
+Root Cause:   API Error (backend not running)
+Confidence:   High (screenshot shows error message)
+Fix Applied:  No (waiting for approval)
+
+Next Steps:
+1. Start test backend: pnpm test:backend
+2. Re-run test: pnpm test dashboard
+═══════════════════════════════════════
+```
+
+## Integration
+
+This skill is useful after:
+- `/test-e2e` fails
+- `/test-all` stops on failure
+- CI pipeline fails
+
+## See Also
+
+- `/test-e2e` - Run E2E tests
+- `/test-all` - Complete test suite
+- `/test-visual` - Visual tests