Wiki/docs/16-plan-tests.md

# Plan de tests

> Strategie de qualite : niveaux de tests, outils, coverage, criteres d'acceptance, regression.
> Audience : Corentin + freelance ponctuel (Phase 2 bridge).

## 1. Strategie globale — Pyramide

```
              /\
             /E2E\        peu nombreux, lents, fragiles, hauts dans la stack
            /------\
           /  INT   \     middle — verifie les contrats Baserow/Docmost/bridge
          /----------\
         /    UNIT    \   nombreux, rapides, isoles — bridge service uniquement
        /--------------\
```

- **Unit tests** : 70% du volume, sur le code custom (bridge)
- **Integration tests** : 25%, sur les vrais clients Baserow/Docmost (containers de test)
- **E2E tests** : 5%, parcours utilisateur complet sur staging
- **UX manuel + NFR** : checklist par release

## 2. Scope du test

Ce qui se teste :
- **Bridge service** (notre seul code custom) : 100% obligatoire
- **Configurations Baserow** (formules, vues) : tests manuels checklist
- **Configurations Docmost** (perms, share links) : tests manuels checklist
- **Workflows metier** : tests E2E des parcours principaux

Ce qui ne se teste pas :
- Code upstream Docmost/Baserow (deja teste par eux)
- Postgres/Redis (assume fonctionnel)

## 3. Niveaux de tests

### 3.1 Unit tests (bridge)

| Aspect | Spec |
|--------|------|
| Outil | Vitest |
| Cible | `bridge/src/**` — domain models, formulas, utils, validators |
| Mock | Pas de Baserow/Docmost reels, mocks via `vi.mock()` |
| Coverage minimum | 80% sur `bridge/src/domain/` et `bridge/src/lib/`, 70% global |
| Exemples a tester | `Personne.heuresRestantesTotal()`, `Module.creerAttribution()` validations RG, parsers d'entree |
| Run | `npm run test:unit` |
| CI | A chaque push + PR |

Pattern :
```typescript
// bridge/src/domain/personne.test.ts
import { describe, it, expect } from 'vitest';
import { Personne } from './personne';
import { Decimal } from 'decimal.js';

describe('Personne.heuresRestantesTotal', () => {
  it('returns capacity - allocated', () => {
    const p = new Personne({
      capaciteAnnuelle: new Decimal(1500),
      heuresAttribueesFormation: new Decimal(400),
      heuresAttribueesAgence: new Decimal(600),
      // ...
    });
    expect(p.heuresRestantesTotal().toNumber()).toBe(500);
  });
  
  it('handles overflow (negative result)', () => {
    // ...
  });
});
```

### 3.2 Integration tests (bridge ↔ services)

| Aspect | Spec |
|--------|------|
| Outil | Vitest + testcontainers (Postgres + Redis reels) |
| Cible | Adapters Baserow/Docmost, webhook handlers, cache Redis |
| Setup | Docker compose `compose.test.yml` lance Baserow et Docmost containers ephemeres |
| Coverage | Tous les endpoints du bridge |
| Run | `npm run test:integration` |
| CI | A chaque push (utilise services Postgres/Redis du runner GitHub Actions) |
| Duree max | 5 min (sinon a optimiser ou move vers nightly) |

Exemples :
- `POST /interventions` cree bien une row dans Baserow, recalcule rollups
- `Webhook row.created` declenche cache invalidation Redis
- Auth `Authorization: Bearer <token>` valide ou refuse correctement

### 3.3 E2E tests (workflows complets)

| Aspect | Spec |
|--------|------|
| Outil | Playwright |
| Cible | Parcours metier complets sur env staging |
| Browsers | Chromium + Firefox (mobile WebKit pour saisie heures) |
| Run | `npm run test:e2e` |
| CI | Apres deploy staging reussi (pas a chaque push) |
| Duree max | 15 min |

Parcours E2E a couvrir (top 5 priorite) :
1. **Admin cree formation → blocs → modules** (UC-01 + UC-02)
2. **Admin attribue module a un formateur** (UC-03)
3. **Formateur saisit heures realisees via mobile** (UC-13)
4. **Admin cree client → projet → taches** (UCA-01 + UCA-02 + UCA-03)
5. **Dev saisit intervention sur tache** (UCA-07)

### 3.4 UX manuel — checklist

Pas automatisable (parle de feel, intuitivite). Pour chaque release :

```
[ ] Login Docmost et Baserow OK
[ ] Saisie d'une formation prend < 30s
[ ] Saisie heures realisees mobile prend < 15s sur smartphone
[ ] Diagrammes Mermaid/Drawio/Excalidraw rendent OK dans une page Docmost
[ ] Share link client fonctionne sans compte
[ ] Recherche full-text Docmost trouve une page recente
[ ] Filtres Baserow sur les vues principales fonctionnent
[ ] Pas de regression visible sur les 3 vues kanban (modules / projets / taches)
```

### 3.5 NFR — tests non-fonctionnels

| Categorie | Test | Cible |
|-----------|------|-------|
| **Performance** | Latence saisie intervention (UCA-07) | p95 < 2s |
| Performance | Recherche full-text Docmost | p95 < 500ms |
| Performance | Recalcul rollup Baserow apres saisie | < 5s |
| **Securite** | Secret scanning (TruffleHog) | Zero hit |
| Securite | SAST (Semgrep) | Zero finding `error` severity |
| Securite | Dependency CVE (npm audit) | Zero `high`/`critical` |
| Securite | Auth bypass tentative (pentest leger) | 401 sur endpoints proteges |
| **Accessibility** | Lighthouse a11y score | >= 90 sur pages publiques |
| **Charge** | 30 users simultanes (k6) | Latence p95 < 3s, error rate < 1% |
| **Backup** | Restore depuis backup recent | RTO < 4h, integrity 100% |

## 4. Donnees de test (fixtures)

### 4.1 Strategie

- **Unit tests** : objects in-memory crees ad-hoc dans le test
- **Integration tests** : seed Baserow ephemere via API a chaque test (fast)
- **E2E tests** : staging environment avec data realiste anonymisee + reset post-test

### 4.2 Fixtures versionnees

`bridge/tests/fixtures/`
- `personnes.json` : 5 personnes types (admin pur, formateur seul, dev seul, formateur+dev, inactif)
- `formations.json` : 2 formations (1 active, 1 archivee)
- `clients.json` : 3 clients (prospect, actif, archive)
- ...

Chargement : helper `loadFixture('personnes')` dans tests.

## 5. Test environments

| Env | Donnees | Usage |
|-----|---------|-------|
| `local` (dev) | Fixtures seedees a chaque `make up` | Dev quotidien |
| `test` (CI) | Containers ephemeres + fixtures | Integration tests CI |
| `staging` | Data realiste anonymisee | E2E + UX manuel |
| `prod` | Data reelle | Pas de tests destructifs |

## 6. Quality gates

A chaque PR, **bloquant** pour merge si rouge :

| Check | Tool | Critere |
|-------|------|---------|
| Lint | Biome | Zero error |
| Type check | tsc | Zero error |
| Unit tests | Vitest | 100% pass |
| Integration tests | Vitest + testcontainers | 100% pass |
| Coverage unit | Vitest | >= 70% global, 80% sur domain |
| Secret scan | TruffleHog | Zero hit |
| SAST | Semgrep | Zero `error` severity |
| Dep audit | npm audit | Zero `high`/`critical` |
| Docker build | docker compose | OK |

E2E tests **non bloquants pour merge** mais bloquants pour deploy prod (run apres deploy staging).

## 7. Acceptance criteria par feature

Format Gherkin pour les UC principaux :

```gherkin
Feature: Saisir heures realisees (UC-13)
  As a Formateur
  I want to log my actual hours per attribution
  So that the rollups update and admin sees real progress

  Scenario: Formateur saisit ses heures dans la limite
    Given une attribution "Module JS / Pierre" en statut planifie avec 10h attribuees
    When Pierre saisit 3h realisees
    Then attribution.heures_realisees = 3h
    And module.heures_realisees est recalcule
    And personne.heures_attribuees_formation reste a 10h
    And no warning displayed

  Scenario: Formateur saisit en depassement
    Given une attribution avec 10h attribuees, deja 8h realisees
    When Pierre saisit 4h supplementaires (total 12h, depasse de 2h)
    Then warning "Depassement detecte, justification requise"
    And attribution.heures_realisees = 12h apres confirmation justification
```

A faire pour chaque UC critique (UC-01, UC-03, UC-13, UCA-02, UCA-07).

## 8. Plan de regression

Avant chaque release vers prod :

1. Run full test suite (unit + integration + E2E sur staging)
2. UX checklist manuel (cf section 3.4)
3. Smoke test post-deploy prod (verifier 3 endpoints critiques)
4. Verification monitoring (logs / metriques 30 min apres deploy)

Si une regression majeure est detectee : rollback (cf doc 14 section 12).

## 9. Test de migration data

Lors de l'import data initial (formations existantes / formateurs / clients) :

1. **Dry-run** : mapping CSV → Baserow rows en memoire, validation schema, rapport ecarts
2. **Test import** sur env staging avec subset (10 rows)
3. **Verification** integrite : rollups calcules correctement, FK liees
4. **Import prod** apres validation
5. **Reconciliation** : compare nb rows attendus vs imported

## 10. Outils — recap

| Outil | Role | Where |
|-------|------|-------|
| Vitest | Unit + integration tests | bridge/ |
| testcontainers | Postgres/Redis containers ephemeres | bridge/tests/integration |
| Playwright | E2E sur staging | bridge/tests/e2e |
| k6 | Load testing | scripts/load-test.js |
| Lighthouse | A11y + perf web | nightly via CI ou manuel |
| TruffleHog | Secret scanning | CI |
| Semgrep | SAST | CI |
| npm audit / Dependabot | Dep CVE | CI + auto |
| Biome | Lint + format | CI |

## 11. Roadmap tests

| Phase | Couverture |
|-------|-----------|
| Phase 1 (vanilla) | Tests manuels checklist UX, smoke tests, validation post-import data |
| Phase 2 (bridge code) | Unit + integration obligatoires sur le code bridge des le jour 1 |
| Phase 3 (maturite) | Ajouter E2E Playwright sur staging, NFR (perf + a11y), load tests |
| Phase 4 | Test de DR (restauration backup) mensuel |

## 12. Questions ouvertes

- [ ] Coverage minimum exacte ? Le doc 14 propose 70% — a confirmer avec Yan/Ludo
- [ ] Tests d'accessibilite obligatoires ou nice-to-have ? (RGAA conformance pour les pages publiques etudiants ?)
- [ ] Tests de charge : a partir de quelle Phase ? (proba pas avant Phase 3)
- [ ] Outils de monitoring synthetic (UptimeRobot pour healthchecks) — a definir doc 18