qa360 2.2.1 → 2.2.7

package/docs/pack-v1.md

@@ -1,383 +0,0 @@
-# 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.**