# Business Analyse E2E Testing Infrastructure

## Vue d'ensemble

Infrastructure de tests E2E pour valider le pipeline complet **Business Analyse → Handoff → PRD extraction → `/business-analyse-develop`**.

**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/
│
├── chain-integrity.test.ts              # Intégrité chaîne BA → Handoff → PRD (55 tests)
│
└── 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 → PRD → develop
    ├── task-generation.test.ts          # Génération de tâches depuis PRD
    └── unified-prd.test.ts             # Extraction PRD unifié (dual-mode v2/v3)
```

---

## 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 → Handoff → PRD → `/business-analyse-develop`.

**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 .prd/
5. Read back prd.json (verify integrity)
6. Verify all required sections for `/business-analyse-develop`
7. Verify prd.json meets requirements (8 categories incl. `documentation`, 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 .prd/

**Reproducibility Test:**
- Multiple extractions = identical prd.json (sans timestamp)

**Error Handling:**
- Missing optional namespace handled gracefully
- Empty arrays handled gracefully

**Integration with `/business-analyse-develop`:**
- 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

### 5. chain-integrity.test.ts

**Objectif:** Valider l'intégrité de la chaîne complète BA → Handoff → PRD.

**Scénarios (55 tests, 9 parties):**
- Part 1: Fichiers skill BA existent et sont structurés correctement
- Part 2: Fichiers skill handoff existent et sont structurés correctement
- Part 3: Cohérence des références inter-steps (next_step valides)
- Part 4: Schémas JSON valides et présents
- Part 5: POST-CHECKs exécutables dans les steps critiques
- Part 6: Références aux fonctions d'extraction (extractPrd, extractUnifiedPrd)
- Part 7: Cohérence fixtures ↔ schéma feature-json
- Part 8: Imports et exports du module prd-extractor
- Part 9: Silent failure guards (détection parse-error avant fallback)

### 6. task-generation.test.ts

**Objectif:** Tester la génération de tâches depuis le PRD.

**Scénarios (26 tests):**
- Génération de tâches depuis PRD simple (module Orders)
- Génération de tâches depuis PRD medium (module Invoices avec lifecycle)
- Validation intégrité des tâches (`validateTaskIntegrity()`)
- Tâches couvrent toutes les entités
- Tâches couvrent tous les use cases
- Tâches ont des dépendances valides (pas de cycles)
- Ordre topologique respecté
- Tâches lifecycle incluent les transitions

### 7. unified-prd.test.ts

**Objectif:** Tester `extractUnifiedPrd()` — extraction PRD dual-mode v2/v3.

**Scénarios (24 tests):**
- Extraction PRD v3.0 (task-oriented) depuis feature simple
- Extraction PRD v3.0 depuis feature medium avec lifecycle
- Structure v3.0 : `$version: "3.0.0"`, tâches intégrées
- `validatePrdCompleteness()` : PRD complet passe
- `validatePrdCompleteness()` : PRD incomplet signale erreurs
- `getPrdFileCounts()` : comptage correct par catégorie
- Fallback v2.0 quand extractPrd() appelé directement
- Cohérence entre v2 et v3 (mêmes données source)
- Metadata préservé (application, module, namespace)
- Traçabilité source (extractedAt, featureJsonPath)

---

## 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).toBeDefined();
    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` — `extractPrd()` | 100% |
| `src/utils/prd-extractor.ts` — `extractUnifiedPrd()` | 100% |
| `src/utils/prd-extractor.ts` — `validatePrdCompleteness()` | 100% |
| `src/utils/prd-extractor.ts` — `validateTaskIntegrity()` | 100% |
| `src/utils/prd-extractor.ts` — `getPrdFileCounts()` | 100% |
| `src/commands/business-analyse-handoff.ts` | 90% |
| `templates/skills/business-analyse/**/*.md` | N/A (documentation) |

### KPIs Tests

- **Total tests:** 168 scénarios (7 test suites)
- **Temps d'exécution:** < 2s
- **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)
- 7 test suites (handoff-validation, prd-extraction x2, full-pipeline, chain-integrity, task-generation, unified-prd)
- Scripts npm
- Documentation

### Phase 2 (À planifier)
- Tests pour mode `--application` (extraction multi-modules)
- Tests pour flag `--v4` (PRD spec-oriented)
- Tests pour `extractUnifiedPrd()` edge cases
- Performance benchmarks (extraction < 100ms)

### Phase 3 (Futur)
- Tests E2E `/business-analyse-develop` integration (mock `/apex -d`)
- Tests pour `/business-analyse-handoff` CLI (end-to-end avec fs)
- Tests pour validation schema v5.0 (`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)
- [Business Analyse Develop](../templates/skills/business-analyse-develop/SKILL.md)
- [Business Analyse Handoff](../templates/skills/business-analyse-handoff/SKILL.md)
