@nextsparkjs/ai-workflow 0.1.0-beta.86

package/claude/commands/session/test-fix.md

@@ -0,0 +1,221 @@
+# /session:test:fix
+
+Fix failing Cypress tests iteratively until all pass.
+
+**Aliases:** Wrapper for `/session:fix:test` focused on Cypress
+
+---
+
+## Syntax
+
+```
+/session:test:fix [--spec <pattern>] [--max-retries <n>]
+```
+
+---
+
+## Behavior
+
+Runs Cypress tests, analyzes failures, applies fixes, and retries until all pass.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:test:fix                                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Run Cypress tests                                           │
+│     ↓                                                           │
+│  2. Identify failures                                           │
+│     ↓                                                           │
+│  3. For each failure:                                           │
+│     │                                                           │
+│     ├─► Selector issue?                                         │
+│     │   - Update data-cy in component                           │
+│     │   - Update selector in test                               │
+│     │                                                           │
+│     ├─► Timing issue?                                           │
+│     │   - Add cy.wait or cy.intercept                           │
+│     │                                                           │
+│     ├─► Assertion issue?                                        │
+│     │   - Update expected value                                 │
+│     │                                                           │
+│     └─► Implementation bug?                                     │
+│         - Fix source code                                       │
+│     ↓                                                           │
+│  4. Re-run failed tests                                         │
+│     │                                                           │
+│     ├─► Still failing: Go to step 3                             │
+│     │                                                           │
+│     └─► All pass: Run full suite                                │
+│     ↓                                                           │
+│  5. Report final status                                         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🔧 FIX CYPRESS TESTS
+
+─────────────────────────────────────────
+
+📋 ITERATION 1
+
+Running Cypress tests...
+❌ 3 tests failing
+
+Failures:
+1. [UAT] products.cy.ts:45 - "should upload images"
+   Error: Element [data-cy=image-upload] not found
+
+2. [UAT] products.cy.ts:78 - "should filter by category"
+   Error: Expected 5, got 3
+
+3. [API] products.cy.ts:23 - "should create with category"
+   Error: Expected 201, got 400
+
+─────────────────────────────────────────
+
+🔍 ANALYZING FAILURE 1/3
+
+Test: should upload images
+Type: Selector not found
+
+Analysis:
+- Component uses: data-cy="upload-image"
+- Test expects: data-cy="image-upload"
+
+Action: Update test selector
+
+Fix applied:
+```typescript
+// Before
+cy.get('[data-cy=image-upload]')
+
+// After
+cy.get('[data-cy=upload-image]')
+```
+
+✓ Test file updated
+
+─────────────────────────────────────────
+
+🔍 ANALYZING FAILURE 2/3
+
+Test: should filter by category
+Type: Assertion mismatch
+
+Analysis:
+- Sample data has 3 products in "Electronics"
+- Test expects 5
+
+Action: Update test data or assertion
+
+Options:
+[1] Update assertion to match data (3)
+[2] Add more sample data
+[3] The data is wrong - fix sample
+
+> 1
+
+Fix applied:
+```typescript
+// Before
+pom.verifyProductCount(5);
+
+// After
+pom.verifyProductCount(3);
+```
+
+✓ Test file updated
+
+─────────────────────────────────────────
+
+🔍 ANALYZING FAILURE 3/3
+
+Test: should create with category
+Type: Implementation bug
+
+Analysis:
+- API returns 400: "categoryId required"
+- Test sends categoryId correctly
+- Bug: API validation not reading categoryId
+
+Action: Fix API implementation
+
+Fix applied in: core/api/v1/products/route.ts:34
+```typescript
+// Before
+const { name, price } = await req.json();
+
+// After
+const { name, price, categoryId } = await req.json();
+```
+
+✓ Implementation fixed
+
+─────────────────────────────────────────
+
+📋 ITERATION 2
+
+Re-running failed tests...
+✓ All 3 previously failed tests now pass
+
+Running full suite...
+✓ 20/20 tests passing
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Iterations: 2
+Tests fixed: 3
+  - 1 selector fix (test)
+  - 1 assertion fix (test)
+  - 1 implementation fix (source)
+
+Files modified:
+├─ cypress/e2e/uat/products.cy.ts (2 changes)
+└─ core/api/v1/products/route.ts (1 change)
+
+All tests passing.
+```
+
+---
+
+## Fix Categories
+
+| Category | Fix Location | Common Causes |
+|----------|--------------|---------------|
+| Selector | Test or Component | Changed markup, typo |
+| Timing | Test | Async operations, loading |
+| Assertion | Test | Changed behavior, data |
+| Implementation | Source | Bug in code |
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--spec <pattern>` | Fix specific spec |
+| `--max-retries <n>` | Max fix iterations (default: 5) |
+| `--test-only` | Only fix test code, not source |
+| `--source-only` | Only fix source code |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:test:write` | Write new tests |
+| `/session:test:run` | Run tests |
+| `/session:fix:build` | Fix build errors |

package/claude/commands/session/test-run.md

@@ -0,0 +1,203 @@
+# /session:test:run
+
+Execute Cypress test suite with options for specific tests or full run.
+
+---
+
+## Syntax
+
+```
+/session:test:run [--spec <pattern>] [--tags <tags>]
+```
+
+---
+
+## Behavior
+
+Runs Cypress tests and reports results with detailed analysis.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:test:run                                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Determine tests to run                                      │
+│     - All tests, or filtered                                    │
+│     ↓                                                           │
+│  2. Start dev server (if not running)                           │
+│     ↓                                                           │
+│  3. Execute Cypress tests                                       │
+│     ↓                                                           │
+│  4. Collect results                                             │
+│     - Passed/Failed/Skipped                                     │
+│     - Screenshots on failure                                    │
+│     ↓                                                           │
+│  5. Analyze failures (if any)                                   │
+│     ↓                                                           │
+│  6. Report summary                                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🧪 RUN TESTS
+
+─────────────────────────────────────────
+
+🚀 STARTING TEST RUN
+
+Server: http://localhost:3000 ✓
+Browser: Chrome (headless)
+Spec pattern: cypress/e2e/**/*.cy.ts
+
+─────────────────────────────────────────
+
+📋 EXECUTING TESTS
+
+API Tests:
+├─ products.cy.ts
+│  ├─ ✓ should create a product (1.2s)
+│  ├─ ✓ should get product by ID (0.8s)
+│  ├─ ✓ should update product (0.9s)
+│  ├─ ✓ should delete product (0.7s)
+│  ├─ ✓ should work with API key (1.1s)
+│  └─ ✓ should reject unauthenticated (0.5s)
+
+UAT Tests:
+├─ products.cy.ts
+│  ├─ ✓ should create a new product (3.2s)
+│  ├─ ❌ should upload product images (timeout)
+│  ├─ ✓ should assign categories (2.1s)
+│  ├─ ✓ should display with pagination (2.5s)
+│  └─ ✓ should show for team members (1.8s)
+
+─────────────────────────────────────────
+
+❌ FAILURE ANALYSIS
+
+Test: should upload product images
+File: cypress/e2e/uat/products.cy.ts:45
+
+Error:
+Timed out waiting for element: [data-cy=image-upload]
+
+Screenshot: cypress/screenshots/products-upload-fail.png
+
+Possible causes:
+1. Element not rendered (check component)
+2. Selector changed (verify data-cy)
+3. Async loading issue (add wait)
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Passed:  10
+Failed:  1
+Skipped: 0
+
+Duration: 14.8s
+
+Coverage:
+├─ API: 100% (6/6)
+└─ UAT: 80% (4/5)
+
+─────────────────────────────────────────
+
+Options:
+[1] Fix failing test (/session:test:fix)
+[2] View failure screenshot
+[3] Re-run failed test only
+```
+
+---
+
+## Run with Tags
+
+```
+/session:test:run --tags @api
+```
+
+Output:
+
+```
+🧪 RUN TESTS
+
+Filter: @api tag only
+
+─────────────────────────────────────────
+
+📋 EXECUTING TESTS
+
+Specs matching @api: 3 files
+Tests matching @api: 18 tests
+
+├─ products.cy.ts (6 tests)
+│  ├─ ✓ @api @crud should create
+│  ├─ ✓ @api @crud should read
+│  └─ ...
+├─ categories.cy.ts (6 tests)
+└─ users.cy.ts (6 tests)
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Passed:  18
+Failed:  0
+
+Duration: 8.2s
+
+All @api tests passing.
+```
+
+---
+
+## Run Specific Spec
+
+```
+/session:test:run --spec "cypress/e2e/uat/products.cy.ts"
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--spec <pattern>` | Run specific spec files |
+| `--tags <tags>` | Filter by grep tags |
+| `--headed` | Run with visible browser |
+| `--record` | Record to Cypress Cloud |
+| `--parallel` | Run in parallel |
+
+---
+
+## Test Tags Reference
+
+| Tag | Description |
+|-----|-------------|
+| `@api` | API tests |
+| `@uat` | UAT tests |
+| `@crud` | CRUD operations |
+| `@auth` | Authentication tests |
+| `@smoke` | Smoke tests (critical path) |
+| `@regression` | Full regression suite |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:test:write` | Write new tests |
+| `/session:test:fix` | Fix failing tests |
+| `/session:validate` | Full validation |

package/claude/commands/session/test-write.md

@@ -0,0 +1,242 @@
+# /session:test:write
+
+Write or update Cypress tests (API and UAT) for a feature.
+
+---
+
+## Required Skills
+
+**[MANDATORY]** Read these skills before executing:
+- `.claude/skills/cypress-api/SKILL.md` - API testing patterns
+- `.claude/skills/cypress-e2e/SKILL.md` - E2E/UAT testing patterns
+- `.claude/skills/cypress-selectors/SKILL.md` - data-cy selector conventions
+- `.claude/skills/pom-patterns/SKILL.md` - Page Object Model patterns
+
+---
+
+## Syntax
+
+```
+/session:test:write [--type <api|uat|both>]
+```
+
+---
+
+## Behavior
+
+Generates Cypress tests based on session requirements and existing patterns.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:test:write                                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load session context                                        │
+│     - Read requirements.md (ACs)                                │
+│     - Read plan.md (entities)                                   │
+│     ↓                                                           │
+│  2. Check for existing POMs                                     │
+│     - Reuse if available                                        │
+│     - Create if needed                                          │
+│     ↓                                                           │
+│  3. Generate API tests                                          │
+│     - CRUD operations                                           │
+│     - Auth scenarios                                            │
+│     - Error cases                                               │
+│     ↓                                                           │
+│  4. Generate UAT tests                                          │
+│     - User flows from ACs                                       │
+│     - Visual verification                                       │
+│     ↓                                                           │
+│  5. Validate selectors exist                                    │
+│     ↓                                                           │
+│  6. Create test files                                           │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🧪 WRITE TESTS
+
+Session: stories/2026-01-11-new-products-entity
+Type: both (API + UAT)
+
+─────────────────────────────────────────
+
+📋 ANALYZING REQUIREMENTS
+
+ACs to cover:
+├─ AC1: Admin can create a new product
+├─ AC2: Admin can upload product images
+├─ AC3: Admin can assign products to categories
+├─ AC4: Products are listed with pagination
+└─ AC5: Team members can view products
+
+Entity: products
+API Endpoints: 5 (CRUD + list)
+
+─────────────────────────────────────────
+
+🔍 CHECKING EXISTING POMs
+
+├─ DashboardPOM: exists ✓
+├─ EntityFormPOM: exists ✓
+└─ ProductsPOM: not found
+
+Creating ProductsPOM...
+✓ Created: cypress/support/pom/ProductsPOM.ts
+
+─────────────────────────────────────────
+
+📝 GENERATING API TESTS
+
+File: cypress/e2e/api/products.cy.ts
+
+```typescript
+import { BaseAPIController } from '@/cypress/support/api/BaseAPIController';
+
+describe('@api @products Products API', () => {
+  const api = new ProductsAPIController();
+
+  describe('@crud CRUD Operations', () => {
+    it('@create should create a product', () => {
+      api.create({
+        name: 'Test Product',
+        price: 99.99,
+        categoryId: fixtures.categoryId
+      }).then((response) => {
+        expect(response.status).to.eq(201);
+        expect(response.body.name).to.eq('Test Product');
+      });
+    });
+
+    it('@read should get product by ID', () => {
+      api.getById(fixtures.productId).then((response) => {
+        expect(response.status).to.eq(200);
+      });
+    });
+
+    it('@update should update product', () => {
+      api.update(fixtures.productId, { name: 'Updated' })
+        .then((response) => {
+          expect(response.status).to.eq(200);
+        });
+    });
+
+    it('@delete should delete product', () => {
+      api.delete(fixtures.productId).then((response) => {
+        expect(response.status).to.eq(200);
+      });
+    });
+  });
+
+  describe('@auth Authentication', () => {
+    it('@apikey should work with API key', () => {
+      // API key authentication test
+    });
+
+    it('@session should work with session', () => {
+      // Session authentication test
+    });
+
+    it('@unauthorized should reject unauthenticated', () => {
+      api.unauthorized().create({}).then((response) => {
+        expect(response.status).to.eq(401);
+      });
+    });
+  });
+});
+```
+
+─────────────────────────────────────────
+
+📝 GENERATING UAT TESTS
+
+File: cypress/e2e/uat/products.cy.ts
+
+```typescript
+import { ProductsPOM } from '@/cypress/support/pom/ProductsPOM';
+
+describe('@uat @products Products Management', () => {
+  const pom = new ProductsPOM();
+
+  beforeEach(() => {
+    cy.login('admin@test.com');
+  });
+
+  describe('@ac1 Create Product', () => {
+    it('should create a new product', () => {
+      pom.navigateToList();
+      pom.clickNewProduct();
+      pom.fillForm({
+        name: 'New Product',
+        price: '49.99',
+        description: 'Test description'
+      });
+      pom.submitForm();
+      pom.verifySuccessToast('Product created');
+    });
+  });
+
+  describe('@ac4 List Products', () => {
+    it('should display products with pagination', () => {
+      pom.navigateToList();
+      pom.verifyProductsDisplayed();
+      pom.verifyPaginationControls();
+      pom.goToNextPage();
+      pom.verifyPageChanged();
+    });
+  });
+});
+```
+
+─────────────────────────────────────────
+
+✅ SELECTOR VALIDATION
+
+- [x] data-cy="products-list" exists
+- [x] data-cy="new-product-btn" exists
+- [x] data-cy="product-form" exists
+- [x] data-cy="submit-btn" exists
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Files created:
+├─ cypress/e2e/api/products.cy.ts (12 tests)
+├─ cypress/e2e/uat/products.cy.ts (8 tests)
+└─ cypress/support/pom/ProductsPOM.ts
+
+Total tests: 20
+ACs covered: 5/5
+
+Next: /session:test:run to execute tests
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--type <type>` | api, uat, or both (default: both) |
+| `--ac <number>` | Generate for specific AC |
+| `--from-pom` | Use existing POM without changes |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:test:run` | Run the tests |
+| `/session:test:fix` | Fix failing tests |