qa360 2.1.2 → 2.1.4

package/docs/examples/history-export-gc.md

@@ -0,0 +1,285 @@
+# QA360 History Export & Garbage Collection Examples
+
+This guide demonstrates how to use the `export` and `gc` subcommands of `qa360 history`.
+
+## Table of Contents
+- [Exporting Proof Bundles](#exporting-proof-bundles)
+- [Garbage Collection](#garbage-collection)
+- [Workflow Examples](#workflow-examples)
+
+## Exporting Proof Bundles
+
+The `export` command packages a complete test run into a portable ZIP archive for sharing or archival.
+
+### Basic Export
+
+```bash
+# Export the latest run
+qa360 history list --limit 1      # Get the run ID
+qa360 history export abc123 --bundle my-proof.zip
+```
+
+### What's Inside the Bundle?
+
+The exported ZIP contains:
+
+```
+my-proof.zip
+├── abc123-proof.json           # Cryptographically signed proof
+├── abc123-report.pdf           # PDF report (if generated)
+├── abc123-run.json             # Complete run metadata
+├── artifacts/                  # All test artifacts
+│   ├── screenshot1.png
+│   ├── screenshot2.png
+│   └── trace.json
+└── VERIFICATION.json           # Instructions for verification
+```
+
+### Use Cases
+
+**1. Share proof with stakeholders:**
+```bash
+# Export critical production run
+qa360 history pin def456          # Pin to protect from GC
+qa360 history export def456 --bundle production-v1.2.0.zip
+
+# Send to stakeholders
+# Recipient can verify:
+unzip production-v1.2.0.zip
+qa360 verify def456-proof.json
+```
+
+**2. Archive important releases:**
+```bash
+# Export all pinned runs
+for run_id in $(qa360 history list --json | jq -r '.[] | select(.pinned == 1) | .id'); do
+  qa360 history export $run_id --bundle "archive-${run_id}.zip"
+done
+```
+
+**3. CI/CD artifact preservation:**
+```bash
+# In your CI pipeline
+qa360 run pack.yml
+LATEST_RUN=$(qa360 history list --json --limit 1 | jq -r '.[0].id')
+qa360 history export $LATEST_RUN --bundle build-${CI_COMMIT_SHA}.zip
+# Upload to artifact storage
+```
+
+## Garbage Collection
+
+The `gc` command removes old runs and orphaned artifacts to free disk space.
+
+### Basic Garbage Collection
+
+```bash
+# Preview what will be deleted (safe)
+qa360 history gc --dry-run
+
+# Actually delete (keeps last 10 unpinned runs)
+qa360 history gc
+
+# Keep more runs
+qa360 history gc --keep-last 50
+```
+
+### How GC Works
+
+1. **Identifies runs to delete**: All unpinned runs beyond `--keep-last` threshold
+2. **Protects pinned runs**: Pinned runs are NEVER deleted
+3. **Tracks artifact references**: Scans all kept runs to find referenced artifacts
+4. **Removes orphaned artifacts**: Deletes artifacts no longer referenced by any run
+5. **Reports space freed**: Shows how much disk space was reclaimed
+
+### Example Output
+
+```bash
+$ qa360 history gc --keep-last 10
+
+🧹 Starting garbage collection...
+
+📊 Total runs: 45
+📌 Pinned runs: 3
+📦 Unpinned runs: 42
+
+🗑️  Runs to delete: 32 (keeping last 10)
+🔗 Referenced artifacts: 127
+🗑️  Orphaned artifacts: 48 (342.5 MB)
+
+✅ Garbage collection completed!
+   Deleted: 32 runs
+   Freed: 342.5 MB
+```
+
+### Dry Run Mode
+
+Always preview before deleting:
+
+```bash
+$ qa360 history gc --keep-last 5 --dry-run
+
+⚠️  DRY RUN MODE - No changes will be made
+
+📊 Total runs: 20
+📌 Pinned runs: 2
+📦 Unpinned runs: 18
+
+⚠️  DRY RUN - Would delete:
+   13 runs
+   25 orphaned artifacts (128.3 MB)
+```
+
+### Pinning Important Runs
+
+```bash
+# Pin production releases
+qa360 history list --limit 20
+qa360 history pin abc123          # v1.0.0 release
+qa360 history pin def456          # v1.1.0 release
+qa360 history pin ghi789          # v1.2.0 release
+
+# Now GC will never delete these
+qa360 history gc --keep-last 5
+
+# Unpin when no longer needed
+qa360 history unpin abc123
+```
+
+## Workflow Examples
+
+### Scenario 1: Regular Maintenance
+
+```bash
+# Weekly cleanup task
+qa360 history gc --keep-last 20
+
+# Before cleanup, export important runs
+qa360 history list --status passed --limit 5
+qa360 history export abc123 --bundle weekly-backup.zip
+```
+
+### Scenario 2: Release Management
+
+```bash
+# After deploying v2.0.0
+qa360 run production-pack.yml
+RELEASE_RUN=$(qa360 history list --limit 1 --json | jq -r '.[0].id')
+
+# Pin and export
+qa360 history pin $RELEASE_RUN
+qa360 history export $RELEASE_RUN --bundle release-v2.0.0.zip
+
+# Archive previous release
+qa360 history unpin <previous-release-id>
+
+# Clean up old runs
+qa360 history gc --keep-last 10
+```
+
+### Scenario 3: Compliance & Audit
+
+```bash
+# Export all passing runs from last month
+qa360 history list --status passed --since 2025-01-01 --json | \
+  jq -r '.[].id' | \
+  while read run_id; do
+    qa360 history export $run_id --bundle "compliance/${run_id}.zip"
+  done
+
+# Pin audit runs permanently
+qa360 history pin audit-2025-q1
+qa360 history pin audit-2025-q2
+```
+
+### Scenario 4: Disk Space Management
+
+```bash
+# Check vault size
+du -sh .qa360/
+
+# Preview GC impact
+qa360 history gc --dry-run --keep-last 5
+
+# Aggressive cleanup (keep only last 3 runs)
+qa360 history gc --keep-last 3
+
+# Check space freed
+du -sh .qa360/
+```
+
+## Best Practices
+
+### 1. Pin Before GC
+Always pin important runs before running garbage collection:
+```bash
+qa360 history pin <release-run-id>
+qa360 history gc
+```
+
+### 2. Export Before Cleanup
+For critical runs, export before aggressive cleanup:
+```bash
+qa360 history export <run-id> --bundle backup.zip
+qa360 history gc --keep-last 5
+```
+
+### 3. Use Dry Run First
+Always preview with `--dry-run` before actual deletion:
+```bash
+qa360 history gc --dry-run
+# Review output
+qa360 history gc
+```
+
+### 4. Automate with Cron
+```bash
+# Add to crontab (weekly cleanup)
+0 2 * * 0 cd /path/to/project && qa360 history gc --keep-last 20
+```
+
+### 5. CI/CD Integration
+```yaml
+# .github/workflows/qa360.yml
+- name: Export proof bundle
+  run: |
+    LATEST_RUN=$(qa360 history list --json --limit 1 | jq -r '.[0].id')
+    qa360 history export $LATEST_RUN --bundle proof-${{ github.sha }}.zip
+
+- name: Upload artifact
+  uses: actions/upload-artifact@v3
+  with:
+    name: qa360-proof
+    path: proof-${{ github.sha }}.zip
+```
+
+## Troubleshooting
+
+### Export Fails: Run Not Found
+```bash
+$ qa360 history export abc123 --bundle proof.zip
+❌ Run not found: abc123
+
+# Solution: Check run ID
+qa360 history list
+```
+
+### GC Deletes Too Much
+```bash
+# Solution: Increase --keep-last or pin important runs
+qa360 history gc --keep-last 50
+```
+
+### Bundle Too Large
+```bash
+# Solution: Artifacts are large, consider selective export
+# (Future feature: --exclude-artifacts flag)
+```
+
+## Summary
+
+- **Export**: Create portable ZIP bundles for sharing and archival
+- **GC**: Free disk space by removing old runs and orphaned artifacts
+- **Pin**: Protect important runs from garbage collection
+- **Dry Run**: Always preview before deletion with `--dry-run`
+
+For more information, see the [main documentation](../README.md).

package/docs/examples/pack-v2-complete.yaml

@@ -0,0 +1,158 @@
+# QA360 Pack v2 - Complete Example
+#
+# This example demonstrates all major features of Pack v2:
+# - Authentication profiles (bearer, ui_login)
+# - Dynamic gate naming
+# - Per-gate auth override
+# - Budgets and execution options
+# - Hooks for setup/teardown
+
+version: 2
+name: "example-ecommerce-tests"
+description: "Complete e-commerce platform testing with auth"
+
+# ============================================================
+# Authentication Profiles
+# ============================================================
+auth:
+  # Default auth for API gates
+  api: "customer-bearer"
+  # Default auth for UI gates
+  ui: "customer-login"
+
+  profiles:
+    # Bearer token for API calls
+    customer-bearer:
+      type: bearer
+      config:
+        token: "${CUSTOMER_API_TOKEN}"
+      cache:
+        enabled: true
+        ttl: 3600  # Cache for 1 hour
+
+    # UI form login for browser tests
+    customer-login:
+      type: ui_login
+      config:
+        url: "https://shop.example.com/login"
+        username: "${TEST_USER_EMAIL}"
+        password: "${TEST_USER_PASSWORD}"
+        username_selector: "input[name='email']"
+        password_selector: "input[name='password']"
+        submit_selector: "button[type='submit']"
+      cache:
+        enabled: true
+        ttl: 86400  # Cache for 24 hours
+
+    # Admin API with different token
+    admin-bearer:
+      type: bearer
+      config:
+        token: "${ADMIN_API_TOKEN}"
+
+# ============================================================
+# Quality Gates
+# ============================================================
+gates:
+  # API Health Check
+  api-health:
+    adapter: playwright-api
+    enabled: true
+    auth: "customer-bearer"
+    config:
+      baseUrl: "https://api.shop.example.com"
+      smoke:
+        - "GET /health -> 200"
+        - "GET /v1/products -> 200"
+        - "GET /v1/categories -> 200"
+      timeout: 10000
+      retries: 2
+    budgets:
+      p95_ms: 500
+      max_duration_ms: 15000
+
+  # UI Smoke Tests
+  ui-smoke:
+    adapter: playwright-ui
+    enabled: true
+    auth: "customer-login"
+    config:
+      baseUrl: "https://shop.example.com"
+      pages:
+        - "https://shop.example.com/products"
+        - "https://shop.example.com/categories"
+        - "https://shop.example.com/cart"
+        - "https://shop.example.com/profile"
+      timeout: 30000
+    budgets:
+      a11y_min: 85
+      max_duration_ms: 45000
+
+  # Accessibility Focused Tests
+  a11y-check:
+    adapter: playwright-ui
+    enabled: true
+    auth: "customer-login"
+    config:
+      baseUrl: "https://shop.example.com"
+      pages:
+        - "https://shop.example.com/checkout"
+        - "https://shop.example.com/payment"
+    budgets:
+      a11y_min: 95  # Strict accessibility requirement
+
+  # Admin API (different auth)
+  admin-api:
+    adapter: playwright-api
+    enabled: true
+    auth: "admin-bearer"
+    config:
+      baseUrl: "https://admin.shop.example.com"
+      smoke:
+        - "GET /admin/dashboard -> 200"
+        - "GET /admin/orders -> 200"
+        - "GET /admin/users -> 200"
+
+  # Public endpoints (no auth)
+  public-pages:
+    adapter: playwright-ui
+    enabled: true
+    # No auth specified - runs without authentication
+    config:
+      baseUrl: "https://shop.example.com"
+      pages:
+        - "https://shop.example.com/"
+        - "https://shop.example.com/about"
+        - "https://shop.example.com/contact"
+
+# ============================================================
+# Lifecycle Hooks
+# ============================================================
+hooks:
+  beforeAll:
+    - name: "Wait for API"
+      run: "npx wait-on https://api.shop.example.com/health -t 30000"
+      timeout: 35000
+
+    - name: "Log start"
+      run: "echo 'Starting QA360 test run: ${QA360_PACK_NAME}'"
+
+  afterAll:
+    - name: "Log completion"
+      run: "echo 'QA360 test run completed'"
+
+# ============================================================
+# Execution Options
+# ============================================================
+execution:
+  timeout: 60000
+  max_retries: 2
+  on_failure: continue
+
+# ============================================================
+# Variables
+# ============================================================
+variables:
+  ENVIRONMENT: "production"
+  API_TIMEOUT: "10000"
+  UI_TIMEOUT: "30000"

package/docs/examples/pack-v2-quickstart.yaml

@@ -0,0 +1,24 @@
+# QA360 Pack v2 - Quickstart Example
+#
+# Minimal pack file for API testing with authentication
+
+version: 2
+name: "api-quickstart"
+
+auth:
+  profiles:
+    my-api:
+      type: bearer
+      config:
+        token: "${API_TOKEN}"
+
+gates:
+  health-check:
+    adapter: playwright-api
+    enabled: true
+    auth: "my-api"
+    config:
+      baseUrl: "https://api.example.com"
+      smoke:
+        - "GET /health -> 200"
+        - "GET /users -> 200"

package/docs/examples/pack-v2-ui-login.yaml

@@ -0,0 +1,81 @@
+# QA360 Pack v2 - UI Login Example
+#
+# This example demonstrates UI-based authentication using Playwright.
+# The UI login provider automates form filling and submission.
+
+version: 2
+name: "ui-login-example"
+description: "E2E tests with UI-based authentication"
+
+auth:
+  ui: "my-app-login"
+
+  profiles:
+    # UI Login configuration
+    my-app-login:
+      type: ui_login
+      config:
+        # The login page URL
+        url: "https://example.com/login"
+
+        # Credentials (use environment variables!)
+        username: "${TEST_USER_EMAIL}"
+        password: "${TEST_USER_PASSWORD}"
+
+        # CSS selectors for form elements
+        username_selector: "input[name='email'], #email"
+        password_selector: "input[name='password'], #password"
+        submit_selector: "button[type='submit']"
+
+        # Optional: Save session for faster subsequent runs
+        session_file: ".qa360/session.json"
+
+        # Optional: Cache credentials (default: 24 hours)
+        cache:
+          enabled: true
+          ttl: 86400
+
+gates:
+  # These gates will automatically use the UI login credentials
+  dashboard-check:
+    adapter: playwright-ui
+    enabled: true
+    config:
+      baseUrl: "https://example.com"
+      pages:
+        - "https://example.com/dashboard"
+        - "https://example.com/profile"
+        - "https://example.com/settings"
+
+  products-check:
+    adapter: playwright-ui
+    enabled: true
+    config:
+      baseUrl: "https://example.com"
+      pages:
+        - "https://example.com/products"
+        - "https://example.com/products/category-1"
+
+# ============================================================
+# Advanced: UI Login with TOTP (2FA)
+# ============================================================
+# Uncomment this section for apps using two-factor authentication
+#
+# auth:
+#   profiles:
+#     login-with-totp:
+#       type: ui_login
+#       config:
+#         url: "https://example.com/login"
+#         username: "${TEST_USER_EMAIL}"
+#         password: "${TEST_USER_PASSWORD}"
+#         username_selector: "#email"
+#         password_selector: "#password"
+#         submit_selector: "button[type='submit']"
+#
+#         # TOTP configuration for 2FA
+#         totp_secret: "${TOTP_SECRET}"  # Base32 encoded secret
+#         totp_selector: "input[name='code'], input[placeholder*='code' i]"
+#
+#         # Wait for TOTP input to appear
+#         totp_wait_ms: 1000

package/docs/examples/qa360-report.json

@@ -0,0 +1,50 @@
+{
+  "version": "2.7.0",
+  "generated_at": "2025-09-08T11:29:03.886Z",
+  "summary": {
+    "status": "failure",
+    "globalSuccess": false,
+    "totalDuration": 25471,
+    "originalFramework": "playwright",
+    "finalFramework": "playwright",
+    "fallbackUsed": false,
+    "cookiesHandled": false,
+    "url": "https://demoqa.com/login",
+    "siteName": "demoqa",
+    "timestamp": "2025-09-08T11:29:03.859Z",
+    "confidenceBadge": {
+      "level": "critical-failure",
+      "score": null,
+      "label": "Échec Critique",
+      "icon": "🔴",
+      "color": "#dc3545",
+      "description": "Tests échoués, intervention requise"
+    }
+  },
+  "detailed_steps": [],
+  "screenshots": [],
+  "metrics": {
+    "pagesVisited": 1,
+    "linksDetected": 0,
+    "imagesLoaded": 0,
+    "formsFound": 0,
+    "buttonsFound": 0,
+    "filesUploaded": 0,
+    "cookiesHandled": false,
+    "interactionsPerformed": 0,
+    "estimatedCoverage": 100
+  },
+  "threshold": null,
+  "technical": {
+    "errors": [
+      "Authentification échouée: Authentification échouée - credentials invalides ou page d'erreur"
+    ],
+    "warnings": []
+  },
+  "url": "https://demoqa.com/login",
+  "framework": "playwright",
+  "fallback_used": false,
+  "cookies_handled": false,
+  "success": false,
+  "duration": 25471
+}