qa360 2.1.7 → 2.2.0

package/docs/hooks.md

@@ -0,0 +1,304 @@
+# QA360 Hooks - Déclaratifs et Robustes
+
+## Vue d'ensemble
+
+Les hooks QA360 Phase 3 permettent d'orchestrer des actions avant et après l'exécution des gates de qualité. Ils supportent les commandes shell, Docker Compose, et la synchronisation de services.
+
+## Syntaxe Pack.yml
+
+```yaml
+hooks:
+  beforeAll:
+    - run: "npm install"
+      timeout: 60000
+    - compose: up
+      timeout: 120000
+    - wait_on: "http://localhost:8080/healthz"
+      timeout: 30000
+      method: http
+  
+  beforeEach:
+    - run: "echo 'Starting gate'"
+  
+  afterEach:
+    - run: "echo 'Gate completed'"
+  
+  afterAll:
+    - run: "docker system prune -f"
+    - compose: down
+      timeout: 30000
+
+execution:
+  hook_timeout_ms: 180000
+  on_failure: stop  # stop | continue
+  compose_file: "services.yml"
+```
+
+## Types d'Actions
+
+### 1. Commandes Shell (`run`)
+
+```yaml
+- run: "npm test"
+  timeout: 30000
+```
+
+**Caractéristiques :**
+- Exécution dans le répertoire de travail du pack
+- Variables d'environnement héritées
+- Redirection automatique des secrets
+- Support timeout individuel
+
+### 2. Docker Compose (`compose`)
+
+```yaml
+- compose: up
+  timeout: 120000
+- compose: down
+  timeout: 60000
+```
+
+**Fonctionnalités :**
+- Opérations idempotentes (up multiple = safe)
+- Détection automatique du fichier compose
+- Health checks intégrés
+- Nettoyage automatique des volumes
+
+### 3. Attente de Services (`wait_on`)
+
+```yaml
+- wait_on: "http://localhost:3000/healthz"
+  timeout: 30000
+  method: http  # http | tcp
+
+- wait_on: "localhost:5432"
+  timeout: 15000
+  method: tcp
+```
+
+**Méthodes supportées :**
+- **HTTP** : Attente d'un endpoint (status 200)
+- **TCP** : Attente d'ouverture de port
+
+## Lifecycle Hooks
+
+### `beforeAll`
+Exécuté une fois avant tous les gates.
+**Usage typique :** Setup infrastructure, démarrage services.
+
+### `beforeEach`
+Exécuté avant chaque gate individuel.
+**Usage typique :** Préparation données, nettoyage cache.
+
+### `afterEach`
+Exécuté après chaque gate individuel.
+**Usage typique :** Collecte métriques, nettoyage temporaire.
+
+### `afterAll`
+Exécuté une fois après tous les gates.
+**Usage typique :** Cleanup infrastructure, archivage logs.
+
+## Configuration Execution
+
+### Timeouts
+
+```yaml
+execution:
+  hook_timeout_ms: 180000  # Timeout global par hook (3 min)
+```
+
+**Priorité des timeouts :**
+1. Timeout individuel du hook
+2. `hook_timeout_ms` global
+3. Défaut : 180000ms (3 minutes)
+
+### Gestion d'Échecs
+
+```yaml
+execution:
+  on_failure: stop     # Arrêt immédiat si échec
+  on_failure: continue # Poursuite malgré les échecs
+```
+
+**Comportements :**
+- **`stop`** : Premier échec → arrêt complet
+- **`continue`** : Échecs → warnings, poursuite workflow
+
+### Fichier Compose
+
+```yaml
+execution:
+  compose_file: "docker-compose.yml"  # Défaut: services.yml
+```
+
+## Exemples Concrets
+
+### Setup API + Base de Données
+
+```yaml
+hooks:
+  beforeAll:
+    - compose: up
+    - wait_on: "localhost:5432"
+      method: tcp
+      timeout: 30000
+    - wait_on: "http://localhost:3000/healthz"
+      method: http
+      timeout: 45000
+    - run: "npm run db:migrate"
+  
+  afterAll:
+    - run: "npm run db:cleanup"
+    - compose: down
+```
+
+### Tests avec Services Externes
+
+```yaml
+hooks:
+  beforeAll:
+    - run: "docker pull redis:alpine"
+    - run: "docker run -d --name qa360-redis -p 6379:6379 redis:alpine"
+    - wait_on: "localhost:6379"
+      method: tcp
+  
+  afterAll:
+    - run: "docker stop qa360-redis"
+    - run: "docker rm qa360-redis"
+```
+
+### Préparation Données par Gate
+
+```yaml
+hooks:
+  beforeEach:
+    - run: "npm run test:seed"
+  
+  afterEach:
+    - run: "npm run test:cleanup"
+```
+
+## Sécurité et Limitations
+
+### Redaction Automatique
+- Secrets automatiquement masqués dans les logs
+- Variables d'environnement sensibles protégées
+- Outputs des commandes filtrés
+
+### Commandes Dangereuses
+**Détection automatique :**
+- `rm -rf`
+- `sudo rm`
+- `format`
+- `mkfs`
+
+**Recommandation :** Éviter les commandes destructives.
+
+### Resource Limits
+
+```yaml
+execution:
+  limits:
+    cpu: "1"      # Limite CPU (optionnel)
+    memory: "1Gi" # Limite mémoire (optionnel)
+```
+
+**Note :** Limites appliquées uniquement en environnement conteneurisé.
+
+## Troubleshooting
+
+### Hook Timeout
+```
+❌ Hook failed after 180000ms (timeout)
+```
+**Solution :** Augmenter `timeout` individuel ou `hook_timeout_ms`.
+
+### Compose File Not Found
+```
+QH001: Compose file not found: services.yml
+```
+**Solution :** Créer le fichier ou définir `compose_file`.
+
+### Service Not Ready
+```
+❌ HTTP endpoint http://localhost:3000/healthz not ready after 30000ms
+```
+**Solutions :**
+- Augmenter timeout `wait_on`
+- Vérifier health check du service
+- Ajouter délai dans le service
+
+### Docker Not Available
+```
+QH004: Docker not available
+```
+**Solution :** Installer Docker Desktop ou démarrer le daemon.
+
+## Bonnes Pratiques
+
+### 1. Timeouts Appropriés
+```yaml
+# Services légers
+- wait_on: "http://localhost:3000/healthz"
+  timeout: 15000
+
+# Bases de données
+- wait_on: "localhost:5432"
+  timeout: 45000
+
+# Services complexes
+- compose: up
+  timeout: 120000
+```
+
+### 2. Idempotence
+```yaml
+# ✅ Bon : idempotent
+- compose: up
+- run: "mkdir -p /tmp/qa360"
+
+# ❌ Éviter : non-idempotent
+- run: "docker run -d redis"  # Peut échouer si déjà lancé
+```
+
+### 3. Cleanup Garanti
+```yaml
+afterAll:
+  - compose: down  # Toujours nettoyer
+  - run: "rm -rf /tmp/qa360-*"
+```
+
+### 4. Health Checks Robustes
+```yaml
+# ✅ Endpoint dédié
+- wait_on: "http://localhost:3000/healthz"
+
+# ❌ Endpoint métier (peut être lent)
+- wait_on: "http://localhost:3000/api/users"
+```
+
+## Intégration CI/CD
+
+### GitHub Actions
+```yaml
+- name: Run QA360 with hooks
+  run: |
+    qa360 run --pack pack.yml
+    
+- name: Upload artifacts
+  uses: actions/upload-artifact@v4
+  with:
+    path: .qa360/runs/
+```
+
+### Variables d'Environnement
+```yaml
+hooks:
+  beforeAll:
+    - run: "echo $CI_COMMIT_SHA > version.txt"
+    
+environment:
+  CI_COMMIT_SHA: "${{ github.sha }}"
+```
+
+Les hooks QA360 Phase 3 offrent une orchestration robuste et sécurisée pour des workflows de test complexes avec infrastructure éphémère.