claude-flow-novice 2.18.5 → 2.18.6

package/.claude/skills/cfn-test-framework/lib/webapp/SCREENSHOT_NAMING_CONVENTION.md

@@ -0,0 +1,547 @@
+# Screenshot Naming Convention & Storage Strategy
+
+**Version:** 1.0.0
+**Last Updated:** 2025-10-24
+**Purpose:** Robust, hierarchical naming for visual regression testing
+
+---
+
+## Naming Convention
+
+### Primary Pattern
+
+```
+{project}/{component}/{viewport}/{state}/{variant}_{timestamp}.png
+```
+
+### Components Breakdown
+
+| Component | Description | Format | Example |
+|-----------|-------------|--------|---------|
+| **project** | Application/feature namespace | `kebab-case` | `auth-system`, `dashboard` |
+| **component** | UI component or page | `kebab-case` | `login-form`, `user-profile` |
+| **viewport** | Screen size | `{width}x{height}` | `1920x1080`, `375x667` |
+| **state** | Interaction state | `kebab-case` | `default`, `hover`, `error`, `loading` |
+| **variant** | A/B test or theme | `kebab-case` | `dark-mode`, `variant-a` |
+| **timestamp** | Capture time | `YYYYMMDDHHmmss` | `20251024143022` |
+
+### Full Examples
+
+```
+# Desktop login form default state
+auth-system/login-form/1920x1080/default/light-mode_20251024143022.png
+
+# Mobile navigation hover state
+dashboard/nav-menu/375x667/hover/dark-mode_20251024143535.png
+
+# Tablet checkout error state
+e-commerce/checkout-flow/768x1024/error/default_20251024144101.png
+
+# Desktop modal loading state with A/B variant
+user-profile/settings-modal/1920x1080/loading/variant-b_20251024144500.png
+```
+
+---
+
+## Storage Strategy
+
+### 1. SQLite Metadata Storage
+
+**Table: `webapp_screenshots`**
+
+```sql
+CREATE TABLE IF NOT EXISTS webapp_screenshots (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  screenshot_key TEXT UNIQUE NOT NULL,  -- Full path without extension
+  project TEXT NOT NULL,
+  component TEXT NOT NULL,
+  viewport TEXT NOT NULL,
+  state TEXT NOT NULL,
+  variant TEXT NOT NULL DEFAULT 'default',
+  file_path TEXT NOT NULL,              -- Filesystem location
+  file_hash TEXT NOT NULL,              -- SHA256 of image content
+  baseline BOOLEAN DEFAULT 0,           -- Is this the baseline for comparison?
+  captured_at INTEGER NOT NULL,         -- Unix timestamp
+  task_id TEXT,                         -- Associated CFN task
+  agent_id TEXT,                        -- Agent that captured it
+  metadata TEXT,                        -- JSON: browser, OS, user, etc.
+  UNIQUE(project, component, viewport, state, variant, baseline)
+);
+
+CREATE INDEX idx_baseline ON webapp_screenshots(project, component, viewport, state, variant, baseline);
+CREATE INDEX idx_task ON webapp_screenshots(task_id);
+CREATE INDEX idx_component ON webapp_screenshots(project, component);
+CREATE INDEX idx_captured ON webapp_screenshots(captured_at DESC);
+```
+
+### 2. Filesystem Organization
+
+```
+/mnt/c/Users/masha/Documents/claude-flow-novice/
+└── .screenshots/
+    ├── baselines/                    # Reference images (version controlled)
+    │   ├── auth-system/
+    │   │   ├── login-form/
+    │   │   │   ├── 1920x1080/
+    │   │   │   │   ├── default/
+    │   │   │   │   │   └── light-mode.png
+    │   │   │   │   └── hover/
+    │   │   │   │       └── light-mode.png
+    │   │   │   └── 375x667/
+    │   │   │       └── default/
+    │   │   │           └── light-mode.png
+    │   │   └── signup-form/
+    │   │       └── [...]
+    │   └── dashboard/
+    │       └── [...]
+    │
+    ├── current/                      # Latest test captures (ephemeral)
+    │   └── [same structure as baselines]
+    │
+    ├── diffs/                        # Visual diff outputs (ephemeral)
+    │   └── {task_id}/
+    │       └── {screenshot_key}_diff.png
+    │
+    └── archive/                      # Historical captures (TTL: 90 days)
+        └── {YYYY-MM}/
+            └── [same structure]
+```
+
+### 3. Redis Storage (Ephemeral Metadata)
+
+**Use for:**
+- Current test run progress
+- Agent coordination signals
+- Temporary diff results
+
+**Keys:**
+
+```bash
+# Test run metadata
+screenshot:test:{task_id}:metadata
+  → JSON: { started_at, agent_id, total_screenshots, completed, failed }
+
+# Screenshot capture queue
+screenshot:queue:{task_id}
+  → LIST: ["auth-system/login-form/1920x1080/default/light-mode", ...]
+
+# Comparison results (TTL: 1 hour)
+screenshot:diff:{task_id}:{screenshot_key}
+  → JSON: { similarity_score, diff_pixels, status, diff_path }
+
+# Baseline registry (TTL: 24 hours, cache)
+screenshot:baseline:{project}:{component}:{viewport}:{state}:{variant}
+  → STRING: file_hash
+```
+
+---
+
+## Screenshot Key Format
+
+### Primary Key (Unique Identifier)
+
+```
+{project}/{component}/{viewport}/{state}/{variant}
+```
+
+**Example:** `auth-system/login-form/1920x1080/default/light-mode`
+
+### Lookup Pattern
+
+```bash
+# Get baseline for a specific configuration
+SELECT * FROM webapp_screenshots
+WHERE project = 'auth-system'
+  AND component = 'login-form'
+  AND viewport = '1920x1080'
+  AND state = 'default'
+  AND variant = 'light-mode'
+  AND baseline = 1;
+
+# Get all baselines for a component
+SELECT * FROM webapp_screenshots
+WHERE project = 'auth-system'
+  AND component = 'login-form'
+  AND baseline = 1;
+
+# Get recent captures for comparison
+SELECT * FROM webapp_screenshots
+WHERE project = 'auth-system'
+  AND component = 'login-form'
+  AND baseline = 0
+ORDER BY captured_at DESC
+LIMIT 10;
+```
+
+---
+
+## Naming Conventions
+
+### Project Names
+
+**Format:** `kebab-case`, descriptive
+
+**Examples:**
+- `auth-system` - Authentication flows
+- `dashboard` - Main dashboard UI
+- `e-commerce` - Shopping/checkout
+- `admin-panel` - Admin interface
+- `marketing-site` - Public website
+
+### Component Names
+
+**Format:** `kebab-case`, specific UI element
+
+**Examples:**
+- `login-form` - Login page/modal
+- `nav-menu` - Navigation component
+- `user-profile` - User profile page
+- `settings-modal` - Settings dialog
+- `checkout-flow` - Multi-step checkout
+
+### Viewport Sizes
+
+**Standard Sizes:**
+
+| Name | Dimensions | Use Case |
+|------|------------|----------|
+| `1920x1080` | Desktop HD | Default desktop |
+| `1366x768` | Laptop | Common laptop |
+| `375x667` | iPhone SE | Small mobile |
+| `390x844` | iPhone 12/13 | Modern mobile |
+| `768x1024` | iPad | Tablet portrait |
+| `1024x768` | iPad Landscape | Tablet landscape |
+
+**Custom:** `{width}x{height}` for specific needs
+
+### State Names
+
+**Standard States:**
+
+| State | Description | When to Use |
+|-------|-------------|-------------|
+| `default` | Initial render | Baseline state |
+| `hover` | Mouse over | Interactive elements |
+| `focus` | Keyboard focus | Form inputs, buttons |
+| `active` | Mouse down | Button press |
+| `disabled` | Non-interactive | Disabled state |
+| `error` | Validation error | Form errors |
+| `loading` | Async operation | Spinners, skeletons |
+| `success` | Successful action | Confirmation states |
+| `empty` | No data | Empty states |
+| `populated` | With data | Data-rich states |
+
+### Variant Names
+
+**Standard Variants:**
+
+| Variant | Description | When to Use |
+|---------|-------------|-------------|
+| `default` | Default theme | Baseline |
+| `light-mode` | Light theme | Explicit light mode |
+| `dark-mode` | Dark theme | Dark theme support |
+| `variant-a` | A/B test version A | A/B testing |
+| `variant-b` | A/B test version B | A/B testing |
+| `high-contrast` | Accessibility mode | High contrast |
+| `rtl` | Right-to-left | i18n support |
+
+---
+
+## File Naming Rules
+
+### 1. Baseline Files (Version Controlled)
+
+**Pattern:** `{variant}.png`
+
+**Location:** `.screenshots/baselines/{project}/{component}/{viewport}/{state}/{variant}.png`
+
+**Example:** `.screenshots/baselines/auth-system/login-form/1920x1080/default/light-mode.png`
+
+**Commit Policy:**
+- ✅ Commit baseline changes with PR
+- ✅ Include visual review in PR
+- ✅ Tag with `[visual-update]` in commit message
+
+### 2. Current Test Files (Ephemeral)
+
+**Pattern:** `{variant}_{timestamp}.png`
+
+**Location:** `.screenshots/current/{project}/{component}/{viewport}/{state}/{variant}_{timestamp}.png`
+
+**Example:** `.screenshots/current/auth-system/login-form/1920x1080/default/light-mode_20251024143022.png`
+
+**Retention:** Delete after comparison (not version controlled)
+
+### 3. Diff Files (Ephemeral)
+
+**Pattern:** `{screenshot_key}_diff.png`
+
+**Location:** `.screenshots/diffs/{task_id}/{screenshot_key}_diff.png`
+
+**Example:** `.screenshots/diffs/task-123/auth-system_login-form_1920x1080_default_light-mode_diff.png`
+
+**Retention:** Keep for task duration, delete after task complete
+
+### 4. Archive Files (Historical)
+
+**Pattern:** `{variant}_{timestamp}.png`
+
+**Location:** `.screenshots/archive/{YYYY-MM}/{project}/{component}/{viewport}/{state}/{variant}_{timestamp}.png`
+
+**Example:** `.screenshots/archive/2025-10/auth-system/login-form/1920x1080/default/light-mode_20251024143022.png`
+
+**Retention:** 90 days (configurable)
+
+---
+
+## Metadata Storage
+
+### Screenshot Metadata (JSON in SQLite)
+
+```json
+{
+  "browser": "chromium",
+  "browser_version": "119.0.6045.105",
+  "os": "linux",
+  "os_version": "Ubuntu 22.04",
+  "playwright_version": "1.40.0",
+  "viewport_actual": { "width": 1920, "height": 1080 },
+  "device_scale_factor": 1,
+  "user_agent": "Mozilla/5.0...",
+  "url": "http://localhost:3000/login",
+  "test_name": "Login form renders correctly",
+  "git_commit": "4fb837c7",
+  "git_branch": "main",
+  "captured_by": "playwright-tester-agent-123"
+}
+```
+
+---
+
+## Baseline Management
+
+### Setting a Baseline
+
+```bash
+# Via skill
+./.claude/skills/webapp-testing/set-baseline.sh \
+  --project "auth-system" \
+  --component "login-form" \
+  --viewport "1920x1080" \
+  --state "default" \
+  --variant "light-mode" \
+  --file ".screenshots/current/auth-system/login-form/1920x1080/default/light-mode_20251024143022.png"
+
+# Result:
+# 1. Copy to baselines directory (remove timestamp)
+# 2. Update SQLite: set baseline=1, copy metadata
+# 3. Update Redis cache
+# 4. Return baseline record
+```
+
+### Updating a Baseline
+
+```bash
+# Automatically when visual changes are approved
+./.claude/skills/webapp-testing/update-baseline.sh \
+  --screenshot-key "auth-system/login-form/1920x1080/default/light-mode" \
+  --new-file ".screenshots/current/auth-system/login-form/1920x1080/default/light-mode_20251024150000.png" \
+  --reason "Updated button style per design review"
+
+# Result:
+# 1. Archive old baseline to archive/
+# 2. Copy new file to baselines/
+# 3. Update SQLite record
+# 4. Clear Redis cache
+# 5. Log change to audit trail
+```
+
+---
+
+## Query Examples
+
+### Get All Baselines for Component
+
+```sql
+SELECT
+  screenshot_key,
+  viewport,
+  state,
+  variant,
+  file_path,
+  captured_at
+FROM webapp_screenshots
+WHERE project = 'auth-system'
+  AND component = 'login-form'
+  AND baseline = 1
+ORDER BY viewport, state, variant;
+```
+
+### Find Screenshots Needing Baselines
+
+```sql
+-- Captures without corresponding baselines
+SELECT DISTINCT
+  c.project,
+  c.component,
+  c.viewport,
+  c.state,
+  c.variant
+FROM webapp_screenshots c
+LEFT JOIN webapp_screenshots b
+  ON c.project = b.project
+  AND c.component = b.component
+  AND c.viewport = b.viewport
+  AND c.state = b.state
+  AND c.variant = b.variant
+  AND b.baseline = 1
+WHERE c.baseline = 0
+  AND b.id IS NULL;
+```
+
+### Get Recent Test Results for Task
+
+```sql
+SELECT
+  screenshot_key,
+  file_path,
+  captured_at,
+  metadata
+FROM webapp_screenshots
+WHERE task_id = 'cfn-task-456'
+  AND baseline = 0
+ORDER BY captured_at DESC;
+```
+
+---
+
+## Best Practices
+
+### 1. Screenshot Organization
+
+✅ **DO:**
+- Use consistent naming across projects
+- Group by project → component → viewport → state
+- Version control baselines
+- Clean up ephemeral files after tests
+
+❌ **DON'T:**
+- Mix baseline and test captures in same directory
+- Use timestamps in baseline filenames
+- Version control current/diff/archive directories
+- Use spaces or special characters in names
+
+### 2. Baseline Management
+
+✅ **DO:**
+- Review visual changes in PR
+- Update baselines with design changes
+- Archive old baselines before updating
+- Document baseline change reasons
+
+❌ **DON'T:**
+- Auto-approve baseline changes
+- Update baselines without review
+- Delete old baselines immediately
+- Skip metadata/audit trail
+
+### 3. Storage Efficiency
+
+✅ **DO:**
+- Compress PNGs (pngquant, oxipng)
+- Set TTLs on ephemeral data
+- Archive old screenshots periodically
+- Use file hashes to detect duplicates
+
+❌ **DON'T:**
+- Store uncompressed screenshots
+- Keep all test runs indefinitely
+- Duplicate baselines across branches
+- Store screenshots in git unnecessarily
+
+### 4. Search & Discovery
+
+✅ **DO:**
+- Index by project, component, viewport
+- Use consistent component naming
+- Tag screenshots with git metadata
+- Enable full-text search on metadata
+
+❌ **DON'T:**
+- Use cryptic component names
+- Skip metadata fields
+- Mix naming conventions
+- Rely solely on filesystem search
+
+---
+
+## Integration Points
+
+### CFN Loop Integration
+
+**Loop 3 (Implementation):**
+- Capture screenshots during frontend development
+- Store in `current/` with task_id
+
+**Loop 2 (Validation):**
+- Compare current captures to baselines
+- Generate diffs for reviewers
+- Store comparison results in Redis
+
+**Product Owner Decision:**
+- Review visual diffs
+- Approve/reject baseline updates
+- Document visual changes
+
+### Git Integration
+
+```gitignore
+# .gitignore
+.screenshots/current/
+.screenshots/diffs/
+.screenshots/archive/
+
+# Version control baselines only
+!.screenshots/baselines/
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/visual-regression.yml
+- name: Run Visual Regression Tests
+  run: |
+    npx claude-flow-novice skill webapp-testing \
+      --project "auth-system" \
+      --component "login-form" \
+      --task-id "${{ github.sha }}"
+
+- name: Upload Diffs as Artifacts
+  uses: actions/upload-artifact@v3
+  with:
+    name: visual-diffs
+    path: .screenshots/diffs/
+```
+
+---
+
+## Future Enhancements
+
+### Phase 2: Advanced Features
+- [ ] Responsive screenshot matrices (auto-generate all viewports)
+- [ ] Animation frame capture (multi-frame GIF/video)
+- [ ] Component isolation (auto-detect and crop component bounds)
+- [ ] Smart diff highlighting (ML-based change detection)
+- [ ] Baseline branching (per-branch baselines for feature work)
+
+### Phase 3: AI Integration
+- [ ] Auto-suggest baseline updates based on design intent
+- [ ] Anomaly detection (unexpected visual changes)
+- [ ] Visual test generation from designs (Figma → screenshots)
+- [ ] Natural language screenshot queries ("show me all error states")
+
+---
+
+**Last Updated:** 2025-10-24
+**Version:** 1.0.0
+**Status:** Ready for Implementation