qa360 2.1.7 → 2.2.1

package/docs/USER_GUIDE.md

@@ -0,0 +1,687 @@
+# 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