# 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)
