qa360 2.1.2 → 2.1.4

package/docs/pack-v1.md

@@ -0,0 +1,383 @@
+# QA360 Pack v1 - Configuration Standard
+
+## 🎯 Vue d'ensemble
+
+Le **Pack v1** est le format standardisé de configuration pour QA360 Core. Il définit de manière déterministe et portable tous les aspects d'une suite de tests : cibles, budgets, sécurité, hooks, et observabilité.
+
+**Objectif** : Un même `pack.yml` doit produire la même preuve signée sur n'importe quel environnement.
+
+## 📋 Structure Canonique
+
+### Champs Obligatoires
+
+```yaml
+version: 1                    # Version du schéma (obligatoire)
+name: "my-test-pack"         # Nom du pack (alphanumeric + _ -)
+gates: ["api_smoke", "perf"] # Gates de qualité à exécuter
+```
+
+### Champs Optionnels
+
+```yaml
+description: "Description du pack de tests"
+
+targets:
+  api:
+    baseUrl: "https://api.example.com"
+    smoke:
+      - "GET /health -> 200"
+      - "POST /users -> 201"
+  web:
+    baseUrl: "https://app.example.com"
+    pages:
+      - "/"
+      - "/login"
+      - "/dashboard"
+
+budgets:
+  perf_p95_ms: 800          # Budget performance (P95 en ms)
+  a11y_min: 90              # Score accessibilité minimum
+
+security:
+  sast_max_high: 0          # Vulnérabilités SAST high max
+  secrets_leak: 0           # Fuites de secrets (toujours 0)
+
+data:
+  profile: "demo"           # Profil de données (demo|staging|production)
+  seed: 42                  # Graine pour génération déterministe
+
+hooks:
+  beforeAll:
+    - run: "npx playwright install --with-deps"
+      timeout: 60000
+  afterAll:
+    - run: "docker compose down -v"
+      timeout: 30000
+
+execution:
+  retry_on: ["ECONNRESET", "502"]
+  max_retries: 2
+  fail_on_readiness: true
+  timeout: 30000
+
+observability:
+  metrics: true
+  trace: "basic"            # none|basic|detailed
+
+environment:
+  TARGET_ENV: "staging"
+  API_KEY: "${{ secrets.API_KEY }}"  # Référence secret chiffré
+```
+
+## 🚪 Quality Gates
+
+### Gates Disponibles
+
+| Gate | Description | Adapters | Budgets |
+|------|-------------|----------|---------|
+| `api_smoke` | Tests API de base | Playwright | - |
+| `ui` | Tests interface utilisateur | Playwright, Lighthouse | a11y_min |
+| `perf` | Tests de performance | k6, Lighthouse | perf_p95_ms |
+| `sast` | Analyse statique sécurité | Semgrep | sast_max_high |
+| `dast` | Tests dynamiques sécurité | ZAP | - |
+| `a11y` | Tests accessibilité | Lighthouse, axe | a11y_min |
+
+### Cohérence Gates-Targets
+
+- `api_smoke` → Requiert `targets.api`
+- `ui` → Requiert `targets.web`
+- `perf` → Recommande `budgets.perf_p95_ms`
+- `a11y` → Recommande `budgets.a11y_min`
+- `sast`/`dast` → Recommande `security` section
+
+## 🔐 Gestion des Secrets
+
+### Références de Secrets
+
+```yaml
+environment:
+  API_TOKEN: "${{ secrets.API_TOKEN }}"
+  DB_PASSWORD: "${{ secrets.DB_PASSWORD }}"
+  OAUTH_SECRET: "${{ secrets.OAUTH_SECRET }}"
+```
+
+### Format de Référence
+
+- **Syntaxe** : `${{ secrets.SECRET_NAME }}`
+- **Nom** : MAJUSCULES avec underscores uniquement
+- **Interpolation** : Automatique lors de l'exécution
+- **Sécurité** : Jamais en clair dans logs/rapports
+
+### Commandes Secrets
+
+```bash
+# Ajouter un secret
+qa360 secrets add API_TOKEN
+
+# Lister les secrets (noms uniquement)
+qa360 secrets list
+
+# Supprimer un secret
+qa360 secrets remove API_TOKEN
+
+# Diagnostic des secrets
+qa360 secrets doctor
+
+# Export redacted pour debug
+qa360 secrets export --redacted
+```
+
+## 🔧 Hooks Déclaratifs
+
+### Structure des Hooks
+
+```yaml
+hooks:
+  beforeAll:
+    - run: "command to execute"
+      timeout: 30000          # Optionnel, défaut 30s
+  afterAll:
+    - run: "cleanup command"
+      timeout: 10000
+```
+
+### Bonnes Pratiques Hooks
+
+- **beforeAll** : Installation dépendances, setup environnement
+- **afterAll** : Nettoyage, arrêt services
+- **Timeout** : Toujours spécifier pour commandes longues
+- **Sécurité** : Éviter `sudo`, `rm -rf /`, `curl | sh`
+
+## 📊 Budgets et Métriques
+
+### Types de Budgets
+
+```yaml
+budgets:
+  perf_p95_ms: 800          # Performance P95 ≤ 800ms
+  a11y_min: 90              # Accessibilité ≥ 90%
+```
+
+### Calcul Trust Score
+
+Le Trust Score est calculé selon :
+- **Taux de succès** (50%) : % de tests passés
+- **Respect budgets** (30%) : % de budgets respectés
+- **Couverture gates** (20%) : Nombre de gates exécutés
+
+## 🛠️ Commandes Pack
+
+### Validation
+
+```bash
+# Valider pack.yml
+qa360 pack validate [pack.yml]
+
+# Validation avec détails
+qa360 pack validate examples/httpbin/pack.yml
+```
+
+### Auto-correction
+
+```bash
+# Corriger automatiquement
+qa360 pack lint [pack.yml]
+
+# Ajoute champs manquants, corrige format
+qa360 pack lint .qa360/pack.yml
+```
+
+### Migration
+
+```bash
+# Migrer pack legacy vers v1
+qa360 pack migrate [pack.yml]
+
+# Crée backup automatique (.backup)
+qa360 pack migrate old-pack.yml
+```
+
+## 📝 Exemples Pratiques
+
+### Pack API Simple
+
+```yaml
+version: 1
+name: simple-api-test
+gates: ["api_smoke"]
+
+targets:
+  api:
+    baseUrl: "https://jsonplaceholder.typicode.com"
+    smoke:
+      - "GET /posts -> 200"
+      - "GET /users -> 200"
+
+execution:
+  max_retries: 1
+  timeout: 10000
+
+observability:
+  metrics: true
+  trace: basic
+```
+
+### Pack Complet E-commerce
+
+```yaml
+version: 1
+name: ecommerce-full-suite
+description: "Suite complète e-commerce avec tous les gates"
+
+gates: ["api_smoke", "ui", "perf", "sast", "a11y"]
+
+targets:
+  api:
+    baseUrl: "https://api.shop.example.com"
+    smoke:
+      - "GET /health -> 200"
+      - "GET /products -> 200"
+      - "POST /auth/login -> 200"
+  web:
+    baseUrl: "https://shop.example.com"
+    pages: ["/", "/products", "/cart", "/checkout"]
+
+budgets:
+  perf_p95_ms: 1500
+  a11y_min: 95
+
+security:
+  sast_max_high: 0
+  secrets_leak: 0
+
+data:
+  profile: staging
+  seed: 123
+
+hooks:
+  beforeAll:
+    - run: "docker compose up -d db redis"
+      timeout: 60000
+    - run: "npm run db:migrate"
+      timeout: 30000
+  afterAll:
+    - run: "docker compose down -v"
+      timeout: 30000
+
+execution:
+  retry_on: ["ECONNRESET", "502", "element-detached"]
+  max_retries: 3
+  fail_on_readiness: true
+  timeout: 45000
+
+observability:
+  metrics: true
+  trace: detailed
+
+environment:
+  NODE_ENV: "test"
+  API_KEY: "${{ secrets.SHOP_API_KEY }}"
+  DB_URL: "${{ secrets.DATABASE_URL }}"
+  STRIPE_KEY: "${{ secrets.STRIPE_TEST_KEY }}"
+```
+
+## ⚠️ Codes d'Erreur Pack
+
+### Codes QP### (Pack Validation)
+
+| Code | Erreur | Solution |
+|------|--------|----------|
+| QP001 | API gate sans target api | Ajouter `targets.api` |
+| QP002 | UI gate sans target web | Ajouter `targets.web` |
+| QP003 | Perf gate sans budget | Ajouter `budgets.perf_p95_ms` |
+| QP004 | A11y gate sans budget | Ajouter `budgets.a11y_min` |
+| QP005 | Security gates sans config | Ajouter section `security` |
+| QP006 | Secret en clair détecté | Utiliser `${{ secrets.NAME }}` |
+| QP007 | Commande dangereuse hook | Réviser commande hook |
+
+### Codes QP1## (Schema Validation)
+
+| Code | Erreur | Solution |
+|------|--------|----------|
+| QP100 | Champ requis manquant | Ajouter champ obligatoire |
+| QP101 | Type incorrect | Corriger type de valeur |
+| QP102 | Format invalide | Corriger format (ex: URL) |
+| QP103 | Pattern non respecté | Corriger pattern (ex: nom) |
+| QP104 | Valeur enum invalide | Utiliser valeur autorisée |
+| QP105 | Constante incorrecte | Utiliser valeur exacte |
+
+## 🔄 Migration Legacy
+
+### De v0.9.x vers v1
+
+La migration automatique transforme :
+
+```yaml
+# Legacy v0.9.x
+name: "my-pack"
+adapters: ["playwright", "k6"]
+tests:
+  - name: "API Test"
+    adapter: "playwright"
+    config: { baseURL: "https://api.example.com" }
+environment:
+  API_URL: "https://api.example.com"
+hooks:
+  beforeAll: ["npm install"]
+```
+
+En :
+
+```yaml
+# Pack v1
+version: 1
+name: "my-pack"
+gates: ["api_smoke", "perf"]
+targets:
+  api:
+    baseUrl: "https://api.example.com"
+    smoke: ["GET /health -> 200"]
+hooks:
+  beforeAll:
+    - run: "npm install"
+      timeout: 30000
+execution:
+  retry_on: ["ECONNRESET", "502"]
+  max_retries: 1
+  fail_on_readiness: true
+  timeout: 30000
+observability:
+  metrics: true
+  trace: basic
+environment:
+  API_URL: "https://api.example.com"
+```
+
+## 🏆 Bonnes Pratiques
+
+### Nommage
+- **Pack** : `kebab-case` (ex: `api-smoke-tests`)
+- **Secrets** : `UPPER_SNAKE_CASE` (ex: `API_TOKEN`)
+- **Variables** : `UPPER_SNAKE_CASE` (ex: `TARGET_ENV`)
+
+### Sécurité
+- ✅ Toujours utiliser `${{ secrets.NAME }}` pour credentials
+- ✅ Définir `secrets_leak: 0` dans security
+- ✅ Éviter commandes dangereuses dans hooks
+- ❌ Jamais de secrets en clair dans pack.yml
+
+### Performance
+- ✅ Définir budgets réalistes selon environnement
+- ✅ Configurer timeouts appropriés
+- ✅ Utiliser retry_on pour erreurs réseau
+- ❌ Éviter timeouts trop courts (< 10s)
+
+### Maintenabilité
+- ✅ Description claire du pack
+- ✅ Hooks de cleanup (afterAll)
+- ✅ Profils data selon environnement
+- ✅ Observabilité activée
+
+---
+
+**✅ Pack v1 standardisé - Configuration déterministe et portable pour preuves de qualité reproductibles.**