qa360 2.2.1 → 2.2.13

package/docs/USER_GUIDE.md

@@ -1,687 +0,0 @@
-# Guide de Test QA360 - Pour Utilisateurs
-
-Ce guide vous aide à tester QA360 de manière complète, de l'installation à l'utilisation avancée.
-
-> **🚀 Beta Testing (15 Jan - 26 Fév 2025)** - Rejoignez le programme beta ! Voir [BETA_TESTING.md](./BETA_TESTING.md)
-
-## 📋 Table des Matières
-
-1. [Installation et Configuration](#1-installation-et-configuration)
-2. [Premier Test Simple](#2-premier-test-simple)
-3. [Tests Avancés](#3-tests-avancés)
-4. [Monitoring en Temps Réel](#4-monitoring-en-temps-réel)
-5. [Vérification des Preuves](#5-vérification-des-preuves)
-6. [Gestion des Secrets](#6-gestion-des-secrets)
-7. [Historique et Reporting](#7-historique-et-reporting)
-8. [Résolution de Problèmes](#8-résolution-de-problèmes)
-
----
-
-## 1. Installation et Configuration
-
-### Installation
-
-**Option 1 : Depuis npm (Recommandé)**
-
-```bash
-# Installation globale via npm
-npm install -g qa360
-
-# OU installation locale dans un projet
-npm install --save-dev qa360
-```
-
-**Option 2 : Depuis les sources (développeurs)**
-
-```bash
-git clone https://github.com/xyqotech/qa360.git
-cd qa360
-pnpm install
-pnpm build
-```
-
-### Vérification de l'installation
-
-```bash
-# Afficher la version
-qa360 --version
-
-# Afficher l'aide
-qa360 --help
-
-# Vérifier la santé du système
-qa360 doctor
-```
-
-### Configuration initiale
-
-```bash
-# Initialiser les clés cryptographiques
-qa360 doctor --init-keys
-
-# Vérifier que tout est OK
-qa360 doctor --fix
-```
-
-**✅ Résultat attendu**: Le système doit générer les clés Ed25519 dans `~/.qa360/keys/`
-
----
-
-## 2. Premier Test Simple
-
-### Étape 1: Créer votre premier pack de tests
-
-#### Option A: Mode interactif (recommandé pour débuter)
-
-```bash
-qa360 init
-```
-
-Suivez les prompts:
-- **Pack name**: `mon-premier-test`
-- **Template**: Choisir "API Basic - Simple API smoke tests"
-- **Customize gates**: Non (pour commencer)
-- **API base URL**: `https://httpbin.org`
-- **Smoke test endpoints**: `GET /get -> 200, GET /status/200 -> 200`
-
-**✅ Résultat attendu**: Création de `qa360.yml` dans le répertoire courant
-
-#### Option B: Utiliser un template
-
-```bash
-qa360 init --template api-basic --yes
-```
-
-#### Option C: Créer manuellement
-
-Créez un fichier `pack.yaml`:
-
-```yaml
-version: 1
-name: test-api-httpbin
-gates:
-  - api_smoke
-
-targets:
-  api:
-    baseUrl: https://httpbin.org
-    smoke:
-      - GET /get -> 200
-      - GET /status/200 -> 200
-      - POST /post -> 200
-```
-
-### Étape 2: Exécuter le pack
-
-```bash
-qa360 run pack.yaml
-```
-
-**✅ Résultat attendu**:
-- Affichage de l'exécution en temps réel
-- Trust Score de 100% si tous les tests passent
-- Création d'un fichier proof dans `.qa360/runs/`
-
-### Étape 3: Vérifier la preuve générée
-
-```bash
-# Vérifier la dernière preuve
-qa360 verify .qa360/runs/
-
-# Ou vérifier un fichier spécifique
-qa360 verify .qa360/runs/proof-<timestamp>.json
-```
-
-**✅ Résultat attendu**:
-```
-✅ Proof verified: OK
-
-🔏 Signer: qa360-system
-🔐 Hash: abc123...
-📦 Artifacts: 0 (all verified)
-🎯 Trust Score: 100/100
-```
-
----
-
-## 3. Tests Avancés
-
-### Test API avec authentification
-
-```yaml
-version: 1
-name: test-api-auth
-gates:
-  - api_smoke
-
-targets:
-  api:
-    baseUrl: https://api.github.com
-    headers:
-      Authorization: "Bearer ${GITHUB_TOKEN}"
-    smoke:
-      - GET /user -> 200
-      - GET /repos -> 200
-
-execution:
-  timeout: 10000
-```
-
-**Note**: Configurez le secret `GITHUB_TOKEN` avec `qa360 secrets add GITHUB_TOKEN`
-
-### Test UI/E2E
-
-```yaml
-version: 1
-name: test-ui-example
-gates:
-  - ui
-
-targets:
-  web:
-    baseUrl: https://example.com
-    pages:
-      - https://example.com
-      - https://example.com/about
-
-execution:
-  timeout: 30000
-```
-
-Exécution:
-```bash
-qa360 run pack-ui.yaml --verbose
-```
-
-### Test avec Hooks (Docker Compose)
-
-```yaml
-version: 1
-name: test-local-api
-gates:
-  - api_smoke
-
-targets:
-  api:
-    baseUrl: http://localhost:3000
-    smoke:
-      - GET /health -> 200
-      - GET /api/users -> 200
-
-hooks:
-  beforeAll:
-    - compose: up
-      timeout: 30000
-    - wait_on: http://localhost:3000/health
-
-  afterAll:
-    - compose: down
-
-execution:
-  timeout: 60000
-```
-
-**Pré-requis**: Avoir un fichier `docker-compose.yml` dans le même répertoire
-
-### Test Full-Stack (API + UI + Performance)
-
-```yaml
-version: 1
-name: test-fullstack
-gates:
-  - api_smoke
-  - ui
-  - perf
-
-targets:
-  api:
-    baseUrl: https://api.example.com
-    smoke:
-      - GET /health -> 200
-      - GET /status -> 200
-
-  web:
-    baseUrl: https://example.com
-    pages:
-      - https://example.com
-
-  perf:
-    scenarios:
-      - name: load_test
-        vus: 10
-        duration: 30s
-        url: https://api.example.com/health
-
-budgets:
-  perf_p95_ms: 2000
-
-execution:
-  timeout: 90000
-  on_failure: continue
-```
-
-Exécution:
-```bash
-qa360 run pack-fullstack.yaml --json > results.json
-```
-
----
-
-## 4. Monitoring en Temps Réel
-
-### Terminal UI (TUI)
-
-QA360 offre une interface terminal pour visualiser l'exécution des tests en temps réel:
-
-```bash
-# Exécuter avec monitoring TUI
-qa360 monitor pack.yaml
-```
-
-**Fonctionnalités**:
-- Barre de progression globale
-- État de chaque gate en temps réel
-- Compteurs de tests (passés/échoués)
-- Temps écoulé et ETA
-- Mise à jour automatique toutes les 100ms
-
-### Dashboard Web
-
-Pour une expérience plus visuelle, utilisez le dashboard web:
-
-```bash
-# Démarrer le dashboard (auto-ouverture du navigateur)
-qa360 dashboard pack.yaml
-
-# Spécifier un port personnalisé
-qa360 dashboard pack.yaml --port 4000
-
-# Désactiver l'ouverture automatique
-qa360 dashboard pack.yaml --no-auto-open
-```
-
-**Fonctionnalités**:
-- Visualisation en temps réel avec Server-Sent Events
-- Graphiques de progression
-- Détails des gates et tests
-- Compatible tous navigateurs modernes
-
----
-
-## 5. Vérification des Preuves
-
-### Vérifier une seule preuve
-
-```bash
-qa360 verify .qa360/runs/proof-1234567890.json
-```
-
-### Vérifier toutes les preuves d'un répertoire
-
-```bash
-qa360 verify .qa360/runs/
-```
-
-### Vérification en mode JSON
-
-```bash
-qa360 verify proof.json --json
-```
-
-**Sortie JSON**:
-```json
-{
-  "valid": true,
-  "code": "OK",
-  "message": "Proof signature valid",
-  "details": {
-    "signerId": "qa360-system",
-    "hash": "abc123...",
-    "trustScore": 100,
-    "artifactsTotal": 5,
-    "artifactsVerified": 5
-  }
-}
-```
-
-### Cas d'usage: CI/CD
-
-```bash
-#!/bin/bash
-# Script de CI
-
-qa360 run pack.yaml --json > result.json
-
-# Vérifier la preuve
-qa360 verify .qa360/runs/ --json > verification.json
-
-# Extraire le trust score
-TRUST_SCORE=$(jq -r '.details.trustScore' verification.json)
-
-if [ "$TRUST_SCORE" -lt 80 ]; then
-  echo "❌ Trust score trop faible: $TRUST_SCORE"
-  exit 1
-fi
-
-echo "✅ Trust score OK: $TRUST_SCORE"
-```
-
----
-
-## 6. Gestion des Secrets
-
-### Ajouter un secret
-
-```bash
-qa360 secrets add API_KEY
-# Entrez la valeur: ********
-```
-
-### Lister les secrets
-
-```bash
-qa360 secrets list
-```
-
-**Sortie**:
-```
-📋 Configured secrets:
-  • API_KEY (added 2025-12-29)
-  • GITHUB_TOKEN (added 2025-12-28)
-```
-
-### Supprimer un secret
-
-```bash
-qa360 secrets remove API_KEY
-```
-
-### Utiliser les secrets dans un pack
-
-```yaml
-version: 1
-name: test-with-secrets
-gates:
-  - api_smoke
-
-targets:
-  api:
-    baseUrl: https://api.example.com
-    headers:
-      Authorization: "Bearer ${API_KEY}"
-      X-Custom-Header: "${CUSTOM_VALUE}"
-    smoke:
-      - GET /protected -> 200
-```
-
----
-
-## 7. Historique et Reporting
-
-### Voir l'historique des runs
-
-```bash
-qa360 history list
-```
-
-**Sortie**:
-```
-📊 Test Run History
-
-Run ID: abc123    Date: 2025-12-29 10:30    Status: ✅ Success    Score: 100/100
-Run ID: def456    Date: 2025-12-29 09:15    Status: ❌ Failed     Score: 75/100
-```
-
-### Voir les détails d'un run
-
-```bash
-qa360 history show abc123
-```
-
-### Générer un rapport
-
-```bash
-# Rapport JSON
-qa360 report --format json > report.json
-
-# Rapport PDF (si supporté)
-qa360 report --format pdf --sign --output qa360-report.pdf
-```
-
----
-
-## 8. Résolution de Problèmes
-
-### Diagnostic système
-
-```bash
-# Vérifier toutes les dépendances
-qa360 doctor
-
-# Auto-réparation
-qa360 doctor --fix
-
-# Vérification verbose
-qa360 doctor --verbose
-```
-
-### Problèmes courants
-
-#### 1. "Pack file validation failed"
-
-**Cause**: Schéma YAML invalide
-
-**Solution**:
-```bash
-# Valider le pack
-qa360 verify pack.yaml
-
-# Voir les erreurs détaillées
-qa360 run pack.yaml --verbose
-```
-
-#### 2. "Proof verification FAILED"
-
-**Cause**: Clés cryptographiques manquantes ou corrompues
-
-**Solution**:
-```bash
-# Régénérer les clés
-qa360 doctor --init-keys
-
-# Vérifier à nouveau
-qa360 verify proof.json
-```
-
-#### 3. "Command not found: qa360"
-
-**Cause**: Installation incomplète
-
-**Solution**:
-```bash
-# Réinstaller
-npm install -g qa360
-
-# Vérifier le PATH
-echo $PATH
-
-# Ou utiliser npx
-npx qa360 run pack.yaml
-```
-
-#### 4. Tests timeout
-
-**Cause**: Timeout trop court ou service lent
-
-**Solution**:
-```yaml
-execution:
-  timeout: 60000  # Augmenter à 60 secondes
-  max_retries: 3
-```
-
-#### 5. "Port already in use" avec Docker
-
-**Cause**: Conteneurs Docker déjà en cours
-
-**Solution**:
-```bash
-# Arrêter tous les conteneurs
-docker compose down
-
-# Ou forcer l'arrêt
-docker compose down --volumes --remove-orphans
-
-# Ré-exécuter
-qa360 run pack.yaml
-```
-
----
-
-## 📚 Scénarios de Test Complets
-
-### Scénario 1: Test d'une API REST publique
-
-```bash
-# 1. Créer le pack
-cat > test-public-api.yaml << EOF
-version: 1
-name: test-public-api
-gates:
-  - api_smoke
-
-targets:
-  api:
-    baseUrl: https://jsonplaceholder.typicode.com
-    smoke:
-      - GET /posts -> 200
-      - GET /posts/1 -> 200
-      - GET /users -> 200
-      - POST /posts -> 201
-EOF
-
-# 2. Exécuter
-qa360 run test-public-api.yaml
-
-# 3. Vérifier
-qa360 verify .qa360/runs/
-```
-
-### Scénario 2: Test Full-Stack avec Docker
-
-```bash
-# 1. Créer docker-compose.yml
-cat > docker-compose.yml << EOF
-version: '3.8'
-services:
-  api:
-    image: nginx:alpine
-    ports:
-      - "8080:80"
-EOF
-
-# 2. Créer le pack
-cat > test-docker.yaml << EOF
-version: 1
-name: test-docker-api
-gates:
-  - api_smoke
-
-targets:
-  api:
-    baseUrl: http://localhost:8080
-    smoke:
-      - GET / -> 200
-
-hooks:
-  beforeAll:
-    - compose: up
-      timeout: 15000
-    - wait_on: http://localhost:8080
-
-  afterAll:
-    - compose: down
-
-execution:
-  timeout: 30000
-EOF
-
-# 3. Exécuter
-qa360 run test-docker.yaml --verbose
-
-# 4. Vérifier les logs
-qa360 history show $(qa360 history list --json | jq -r '.[0].runId')
-```
-
-### Scénario 3: Pipeline CI/CD complet
-
-```bash
-#!/bin/bash
-# ci-pipeline.sh
-
-set -e  # Exit on error
-
-echo "🚀 Starting QA360 CI Pipeline"
-
-# 1. Build
-echo "📦 Building application..."
-npm run build
-
-# 2. Run tests
-echo "🧪 Running QA360 tests..."
-qa360 run pack.yaml --json > qa360-result.json
-
-# 3. Verify proof
-echo "🔐 Verifying cryptographic proof..."
-qa360 verify .qa360/runs/ --json > verification.json
-
-# 4. Extract metrics
-TRUST_SCORE=$(jq -r '.details.trustScore' verification.json)
-GATES_PASSED=$(jq -r '.summary.passed' qa360-result.json)
-GATES_TOTAL=$(jq -r '.summary.total' qa360-result.json)
-
-echo "📊 Results:"
-echo "  Trust Score: $TRUST_SCORE/100"
-echo "  Gates: $GATES_PASSED/$GATES_TOTAL passed"
-
-# 5. Gate on trust score
-if [ "$TRUST_SCORE" -lt 80 ]; then
-  echo "❌ Trust score below threshold (80)"
-  exit 1
-fi
-
-echo "✅ QA360 Pipeline passed!"
-```
-
----
-
-## 🎯 Checklist de Test Complet
-
-Utilisez cette checklist pour valider votre installation QA360:
-
-- [ ] Installation réussie (`qa360 --version`)
-- [ ] Clés cryptographiques générées (`qa360 doctor --init-keys`)
-- [ ] Création d'un pack simple (`qa360 init`)
-- [ ] Exécution d'un test API public (httpbin.org)
-- [ ] Vérification de la preuve générée
-- [ ] Ajout/suppression de secrets
-- [ ] Test avec Docker Compose hooks
-- [ ] Génération d'un rapport
-- [ ] Consultation de l'historique
-- [ ] Mode JSON pour CI/CD
-- [ ] Test de timeout et retry
-- [ ] Test de détection d'erreurs (pack invalide)
-
----
-
-## 📞 Support
-
-- **Documentation complète**: [README.md](./README.md)
-- **Architecture**: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
-- **Issues GitHub**: https://github.com/xyqotech/qa360/issues
-- **Exemples**: [examples/](./examples/)
-
----
-
-**Dernière mise à jour**: 2026-01-01
-**Version QA360**: 1.4.8