Tests

arka-deck utilise deux pipelines de tests : Vitest pour les tests unitaires et d’intégration légers, Playwright pour les tests end-to-end UI.

---

Vitest — unit + integration

Lancer tous les tests

npm test

Mode watch

npm run test:watch

Cibler un fichier

npm test -- core/use-cases/projects/build-for-projects.test.ts

Cibler un pattern

npm test -- --grep "purge"

Coverage

npm test -- --coverage

Couverture v8 produite dans coverage/. Le seuil bloquant en CI est défini dans vitest.config.ts.

---

Convention de placement

Les tests vivent à côté du code testé :

core/use-cases/projects/
├── build-for-projects.ts
├── build-for-projects.test.ts        ← tests unitaires
└── build-for-projects.integration.test.ts  ← tests d'intégration (optionnel)

adapters/inbound/web/server/src/__tests__/
└── projects-routes.test.ts            ← tests serveur

Pour les routes HTTP, les tests vivent dans adapters/inbound/web/server/src/__tests__/.

---

Fakes et test doubles

core/_fakes/ contient les implémentations de ports outbound réutilisables en test :

• InMemoryFilesystem
• InMemoryEventBus (= impl prod et test, pas de fake distinct)
• InMemoryChatSessionStore
• FakeClock ({ now: () => new Date('2026-01-01T00:00:00Z') })
• FakeIdGenerator ({ next: () => 'test-id-N' })
• etc.

Importer depuis les tests :

import { InMemoryFilesystem } from '../../../core/_fakes/in-memory-filesystem.js';

---

Playwright — E2E

Installer Playwright

npm run e2e:install

(Télécharge Chromium et ses dépendances.)

Lancer les E2E

npm run e2e

Le test démarre le serveur arka-deck, ouvre l’UI dans un Chromium headless, et joue les scénarios définis dans e2e/.

Tests E2E disponibles

Fichier	Scénario
e2e/smoke.spec.ts	Lancement serveur + chargement UI + health check
autres	À ajouter selon les flows critiques

---

Anti-patterns à éviter

Mocker globalement fs

❌ Ne pas mocker fs ou node:fs directement. Utilisez InMemoryFilesystem injecté en deps.

Test qui dépend de l’ordre

❌ Vitest peut paralléliser. Les tests doivent être isolés (pas d’état partagé entre tests).

Test qui dépend d’une horloge réelle

❌ Utiliser FakeClock ou vi.useFakeTimers().

Couverture artificielle

❌ Ne pas écrire de test “vide” juste pour couvrir une ligne. Préférer la suppression du code mort.

---

Voir aussi

• Architecture hexagonale (ADR 0001) : ../../adr/0001-architecture-hexagonale.md
• Conventions de contribution : ./conventions (à venir)
• CI gates : ./ci-gates (à venir)