@atlashub/smartstack-cli 3.1.0 → 3.3.0

package/.documentation/testing-ba-e2e.md

@@ -0,0 +1,462 @@
+# Business Analyse E2E Testing Infrastructure
+
+## Vue d'ensemble
+
+Infrastructure de tests E2E pour valider le pipeline complet **Business Analyse → Handoff → PRD extraction → Ralph Loop**.
+
+**Garanties :**
+- ✅ Validation déterministe du handoff
+- ✅ Extraction programmatique prd.json (zéro hallucination)
+- ✅ Reproductibilité parfaite
+- ✅ Couverture complète des cas d'usage
+
+---
+
+## Architecture
+
+```
+tests/ba/
+├── fixtures/                     # Test data (feature.json examples)
+│   ├── simple-feature.json       # Module simple (Orders, 1 entity, 2 UCs, 3 BRs)
+│   ├── medium-feature.json       # Module medium (Invoices, lifecycle, 4 entities, 6 UCs)
+│   ├── complex-application.json  # Application multi-modules (3 modules, dépendances)
+│   └── complex-app/              # Modules référencés par complex-application.json
+│       ├── Customers/
+│       ├── Products/
+│       └── Orders/
+│
+└── e2e/                          # Test suites E2E
+    ├── handoff-validation.test.ts       # Validation handoff section
+    ├── prd-extraction-simple.test.ts    # Extraction module simple
+    ├── prd-extraction-medium.test.ts    # Extraction module lifecycle
+    └── full-pipeline.test.ts            # Pipeline complet BA → Ralph Loop
+```
+
+---
+
+## Fixtures
+
+### simple-feature.json
+
+**Module:** Orders
+**Complexité:** Basique CRUD
+**Contenu:**
+- 1 entity (Order)
+- 2 use cases (Create, List)
+- 3 business rules (2 validation, 1 calculation)
+- 2 API endpoints
+- 4 permissions
+- 7 file categories
+
+**Use case:** Tester extraction basique sans lifecycle.
+
+### medium-feature.json
+
+**Module:** Invoices
+**Complexité:** Workflow avec lifecycle
+**Contenu:**
+- 4 entities (Invoice, InvoiceLine, Customer, Payment)
+- 6 use cases (Create, Issue, Pay, List, View, Cancel)
+- 6 business rules (2 validation, 2 workflow, 2 calculation)
+- 3 API endpoints (dont 2 transitions)
+- 1 lifecycle (4 états: draft → issued → paid, cancelled)
+- 2 seedData business (InvoiceStatus, PaymentMethod)
+
+**Use case:** Tester extraction avec lifecycle states et transitions.
+
+### complex-application.json + modules
+
+**Application:** SalesManagement
+**Complexité:** Multi-modules avec dépendances
+**Contenu:**
+- 3 modules: Customers, Products, Orders
+- Dependency graph: Orders → Customers + Products
+- 4 application roles (admin, manager, salesperson, viewer)
+
+**Use case:** Tester mode `--application` et génération multi-prd.json.
+
+---
+
+## Tests E2E
+
+### 1. handoff-validation.test.ts
+
+**Objectif:** Valider la fonction `validateForPrdExtraction()`.
+
+**Scénarios:**
+- ✅ Feature complet simple passe validation
+- ✅ Feature complet medium passe validation
+- ❌ Feature sans `metadata.application` échoue
+- ❌ Feature sans `metadata.module` échoue
+- ❌ Feature avec `status !== "handed-off|approved|consolidated"` échoue
+- ❌ Feature sans use cases échoue
+- ❌ Feature sans business rules échoue
+- ❌ Feature sans `filesToCreate` échoue
+- ✅ Feature avec status "approved" passe
+- ✅ Feature avec status "consolidated" passe
+- ✅ Medium feature a lifecycle défini (4 états)
+- ✅ Medium feature a 7 catégories de fichiers
+- ✅ BR to code mappings complets
+- ✅ CORE seedData obligatoire (NavigationModule, Permission)
+
+### 2. prd-extraction-simple.test.ts
+
+**Objectif:** Tester extraction prd.json pour module simple.
+
+**Scénarios:**
+- Extraction complète sans erreur
+- Metadata projet (application, module, namespace)
+- Use cases (2) avec actor, permission, steps, linkedRules
+- Functional requirements (3) avec priority, linkedUCs
+- Business rules (3) avec category, statement, priority
+- Entities (1) avec attributes, type
+- API endpoints (2) avec method, route, permission, linkedUC
+- Permission matrix (4 permissions) avec scope
+- Sections (1) avec resources
+- FilesToCreate (7 catégories)
+- BrToCodeMapping (2 mappings) avec targetFile, targetMethod, implementationType
+- SeedData (core + business)
+- Implementation strategy ("module-by-module")
+- Source traceability (extractedAt, featureJsonPath)
+
+### 3. prd-extraction-medium.test.ts
+
+**Objectif:** Tester extraction prd.json avec lifecycle.
+
+**Scénarios:**
+- Extraction complète avec lifecycle
+- Multiple entities (4) avec relationships
+- Lifecycle states (4) avec allowedTransitions
+- Lifecycle transitions (2) avec action, permission, guards
+- Terminal states (2: paid, cancelled)
+- Workflow business rules (2) mappés au code
+- Calculation business rules (2) avec formulas
+- Multiple use cases (6) incluant transitions
+- Transition API endpoints (2: /issue, /pay)
+- Multiple seedData business entities (2)
+- Multiple domain files (4 entities)
+- Integration tests en plus des unit tests
+- BR mappings complets pour critical rules
+
+### 4. full-pipeline.test.ts
+
+**Objectif:** Tester pipeline complet BA → Ralph Loop.
+
+**Scénarios:**
+
+**Simple Module Pipeline:**
+1. Load feature.json (status = "handed-off")
+2. Validate handoff section complet
+3. Extract prd.json déterministe
+4. Write prd.json to .ralph/
+5. Read back prd.json (verify integrity)
+6. Verify all required sections for Ralph Loop
+7. Verify prd.json meets Ralph Loop requirements (7 categories, BR mappings, CORE seedData)
+
+**Medium Module Pipeline with Lifecycle:**
+1. Load medium feature with lifecycle
+2. Validate handoff including lifecycle
+3. Extract prd.json with lifecycle preserved
+4. Verify lifecycle transitions mapped to BR
+5. Verify lifecycle states match seedData
+6. Write prd.json to .ralph/
+
+**Reproducibility Test:**
+- Multiple extractions = identical prd.json (sans timestamp)
+
+**Error Handling:**
+- Missing optional namespace handled gracefully
+- Empty arrays handled gracefully
+
+**Integration with Ralph Loop:**
+- All required information present (entities, UCs, BRs, endpoints, permissions, filesToCreate, BR mappings, CORE seedData)
+- Use cases linked to API endpoints
+- Business rules linked to use cases
+
+---
+
+## Exécution des Tests
+
+### Installation
+
+```bash
+# Les dépendances de test sont déjà installées (vitest, @vitest/coverage-v8)
+npm install
+```
+
+### Commandes
+
+```bash
+# Exécuter tous les tests BA E2E
+npm run test:ba
+
+# Exécuter tests BA E2E en mode watch (développement)
+npm run test:ba:watch
+
+# Exécuter tests BA E2E avec couverture
+npm run test:ba:coverage
+
+# Exécuter TOUS les tests (MCP + BA)
+npm run test:all
+```
+
+### Filtrage des Tests
+
+```bash
+# Exécuter un seul fichier de test
+npx vitest run tests/ba/e2e/handoff-validation.test.ts
+
+# Exécuter tests contenant "lifecycle" dans le nom
+npx vitest run --grep lifecycle
+
+# Exécuter tests en mode watch avec filtrage
+npx vitest --grep extraction
+```
+
+### Couverture de Code
+
+```bash
+npm run test:ba:coverage
+
+# Rapport généré dans: coverage/
+# Ouvrir: coverage/index.html
+```
+
+---
+
+## Ajouter de Nouveaux Tests
+
+### 1. Créer une Nouvelle Fixture
+
+Créer `tests/ba/fixtures/my-feature.json` :
+
+```json
+{
+  "id": "FEAT-TEST-XXX",
+  "version": "5.0.0",
+  "status": "handed-off",
+  "metadata": {
+    "application": "MyApp",
+    "module": "MyModule",
+    "context": "business"
+  },
+  "discovery": { ... },
+  "analysis": {
+    "businessRules": [...],
+    "entities": [...]
+  },
+  "specification": {
+    "useCases": [...],
+    "functionalRequirements": [...],
+    "apiEndpoints": [...],
+    "permissionMatrix": { ... },
+    "sections": [...],
+    "seedDataCore": [...]
+  },
+  "handoff": {
+    "implementationStrategy": "module-by-module",
+    "filesToCreate": {
+      "domain": [...],
+      "application": [...],
+      "infrastructure": [...],
+      "api": [...],
+      "frontend": [...],
+      "seedData": [...],
+      "tests": [...]
+    },
+    "brToCodeMapping": [...]
+  }
+}
+```
+
+**Checklist fixture valide:**
+- ✅ `status` = "handed-off" | "approved" | "consolidated"
+- ✅ `metadata.application` et `metadata.module` présents
+- ✅ `specification.useCases[]` non vide
+- ✅ `analysis.businessRules[]` non vide
+- ✅ `handoff.filesToCreate` avec 7 catégories
+- ✅ `specification.seedDataCore` avec NavigationModule + Permission
+
+### 2. Créer un Nouveau Test
+
+Créer `tests/ba/e2e/my-test.test.ts` :
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { extractPrd, validateForPrdExtraction } from '../../../src/utils/prd-extractor.js';
+import type { ModuleFeatureJson } from '../../../src/types/feature-json.js';
+import fs from 'fs-extra';
+import { join } from 'path';
+
+describe('My Test Suite', () => {
+  const fixturesDir = join(__dirname, '../fixtures');
+
+  it('should validate my scenario', async () => {
+    const feature = await fs.readJson(join(fixturesDir, 'my-feature.json')) as ModuleFeatureJson;
+    const errors = validateForPrdExtraction(feature);
+
+    expect(errors).toEqual([]);
+  });
+
+  it('should extract prd.json correctly', () => {
+    const feature = await fs.readJson(join(fixturesDir, 'my-feature.json')) as ModuleFeatureJson;
+    const prd = extractPrd(feature, 'my-feature.json', 'MyCompany.MyApp');
+
+    expect(prd.version).toBe('2.0.0');
+    expect(prd.project.module).toBe('MyModule');
+    // ... more assertions
+  });
+});
+```
+
+### 3. Exécuter le Nouveau Test
+
+```bash
+npx vitest run tests/ba/e2e/my-test.test.ts
+```
+
+---
+
+## Intégration CI/CD
+
+### Azure Pipelines
+
+Ajouter dans `azure-pipelines.yml` :
+
+```yaml
+- stage: Test
+  jobs:
+    - job: UnitTests
+      steps:
+        - task: Npm@1
+          inputs:
+            command: 'custom'
+            customCommand: 'run test:ba'
+          displayName: 'Run BA E2E Tests'
+
+        - task: PublishTestResults@2
+          inputs:
+            testResultsFormat: 'JUnit'
+            testResultsFiles: '**/test-results.xml'
+          displayName: 'Publish Test Results'
+
+        - task: PublishCodeCoverageResults@1
+          inputs:
+            codeCoverageTool: 'Cobertura'
+            summaryFileLocation: '**/coverage/cobertura-coverage.xml'
+          displayName: 'Publish Code Coverage'
+```
+
+### GitHub Actions
+
+```yaml
+name: Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm install
+      - run: npm run test:ba
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/coverage-final.json
+```
+
+---
+
+## Métriques de Qualité
+
+### Objectifs de Couverture
+
+| Fichier | Couverture Cible |
+|---------|-----------------|
+| `src/utils/prd-extractor.ts` | 100% |
+| `src/commands/derive-prd.ts` | 90% |
+| `templates/skills/business-analyse/**/*.md` | N/A (documentation) |
+
+### KPIs Tests
+
+- **Total tests:** ~60 scénarios
+- **Temps d'exécution:** < 10s
+- **Fixtures:** 3 (simple/medium/complex)
+- **Couverture code:** > 95% sur extraction pipeline
+
+---
+
+## Dépannage
+
+### Erreur: "Cannot find module '...'"
+
+**Cause:** Imports relatifs incorrects ou TypeScript non compilé.
+
+**Solution:**
+```bash
+npm run build
+npm run test:ba
+```
+
+### Erreur: "Feature status is X"
+
+**Cause:** Fixture a `status !== "handed-off"`.
+
+**Solution:** Mettre `status: "handed-off"` dans la fixture.
+
+### Erreur: "No use cases found"
+
+**Cause:** `specification.useCases[]` est vide dans la fixture.
+
+**Solution:** Ajouter au moins 1 use case dans la fixture.
+
+### Tests timeouts
+
+**Cause:** Tests E2E dépassent 30s.
+
+**Solution:** Augmenter `testTimeout` dans `vitest.ba.config.ts` :
+
+```typescript
+export default defineConfig({
+  test: {
+    testTimeout: 60000, // 60s
+  },
+});
+```
+
+---
+
+## Roadmap
+
+### Phase 1 ✅ (Implémenté)
+- Infrastructure Vitest
+- 3 fixtures (simple/medium/complex)
+- 4 test suites (handoff-validation, prd-extraction x2, full-pipeline)
+- Scripts npm
+- Documentation
+
+### Phase 2 (Futur)
+- Tests pour mode `--application` (extraction multi-modules)
+- Tests pour mode `--strict`
+- Tests pour cross-module dependencies
+- Performance benchmarks (extraction < 100ms)
+- Tests pour ba-interactive.html extraction
+
+### Phase 3 (Futur)
+- Tests E2E Ralph Loop integration (mock Ralph Loop server)
+- Tests pour step-05-handoff.md (génération handoff)
+- Tests pour derive-prd CLI (end-to-end avec fs.existsSync)
+- Tests pour validation schema (feature-schema.json)
+
+---
+
+## Voir aussi
+
+- [prd-json v2.0.0 Reference](./prd-json-v2.0.0.md)
+- [Feature JSON Schema](../templates/skills/business-analyse/schemas/feature-schema.json)
+- [Business Analyse Skill](../templates/skills/business-analyse/SKILL.md)
+- [Ralph Loop Documentation](../templates/skills/ralph-loop/SKILL.md)