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 :

// 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 :

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