proffesor-for-testing__agentic-qe/docs/CONFIGURATION.md

Agentic QE Fleet - Configuration Guide

Overview

Agentic QE Fleet can be configured through multiple methods:

1. Environment Variables - For runtime configuration
2. Configuration File - .agentic-qe/config.json for persistent settings
3. CLI Options - For command-specific overrides
4. Fleet YAML - config/fleet.yaml for advanced fleet coordination

Environment Variables

Core Configuration

# Fleet Identification
FLEET_ID=my-project-fleet              # Unique fleet identifier
FLEET_NAME="My Project QE Fleet"       # Human-readable fleet name

# Fleet Size and Performance
MAX_AGENTS=20                          # Maximum concurrent agents (default: 20)
HEARTBEAT_INTERVAL=30000               # Health check interval in ms (default: 30000)
AGENT_TIMEOUT=300000                   # Agent operation timeout in ms (default: 300000)

# Memory Configuration
MEMORY_PARTITION_SIZE=100MB            # Memory partition size (default: 100MB)
MEMORY_TTL=3600                        # Default memory TTL in seconds (default: 3600)
MEMORY_CLEANUP_INTERVAL=600            # Memory cleanup interval in seconds (default: 600)

Database Configuration

# Database Type (sqlite or postgres)
DB_TYPE=sqlite                         # Database type (default: sqlite)
DB_FILENAME=./data/fleet.db            # SQLite database file (default: ./data/fleet.db)

# PostgreSQL Configuration (if DB_TYPE=postgres)
DB_HOST=localhost                      # PostgreSQL host
DB_PORT=5432                           # PostgreSQL port
DB_NAME=agentic_qe                     # PostgreSQL database name
DB_USER=aqe_user                       # PostgreSQL username
DB_PASSWORD=secure_password            # PostgreSQL password
DB_SSL=true                            # Enable SSL connection

Logging Configuration

# Logging Levels: error, warn, info, debug, verbose
LOG_LEVEL=info                         # Log level (default: info)
LOG_FORMAT=json                        # Log format: json or text (default: json)
LOG_FILE=./logs/aqe.log                # Log file path (default: ./logs/aqe.log)
LOG_MAX_SIZE=10m                       # Max log file size (default: 10m)
LOG_MAX_FILES=5                        # Max number of log files (default: 5)

API Configuration (Optional)

# REST API Server (if enabled)
API_ENABLED=true                       # Enable REST API (default: false)
API_PORT=3000                          # API server port (default: 3000)
API_HOST=localhost                     # API server host (default: localhost)
API_CORS_ENABLED=true                  # Enable CORS (default: false)
API_RATE_LIMIT=100                     # Requests per minute (default: 100)

Test Execution Configuration

# Test Execution Defaults
TEST_TIMEOUT=30000                     # Test timeout in ms (default: 30000)
TEST_RETRY_COUNT=3                     # Number of retries for failed tests (default: 3)
TEST_PARALLEL_WORKERS=4                # Parallel test workers (default: 4)
TEST_COVERAGE_THRESHOLD=80             # Coverage threshold percentage (default: 80)

Security Configuration

# Security Settings
SECURITY_SCAN_ENABLED=true             # Enable security scanning (default: true)
SECURITY_SCAN_DEPTH=standard           # Scan depth: basic, standard, deep (default: standard)
SECURITY_FAIL_ON_HIGH=true             # Fail on high-severity vulnerabilities (default: true)

Example .env File

# .env
# Agentic QE Fleet Configuration

# Fleet Settings
FLEET_ID=my-app-qe-fleet
FLEET_NAME="My Application QE Fleet"
MAX_AGENTS=20
HEARTBEAT_INTERVAL=30000

# Database
DB_TYPE=sqlite
DB_FILENAME=./data/fleet.db

# Logging
LOG_LEVEL=info
LOG_FORMAT=json
LOG_FILE=./logs/aqe.log

# Test Execution
TEST_TIMEOUT=30000
TEST_RETRY_COUNT=3
TEST_PARALLEL_WORKERS=4
TEST_COVERAGE_THRESHOLD=85

# Security
SECURITY_SCAN_ENABLED=true
SECURITY_FAIL_ON_HIGH=true

Configuration File (.agentic-qe/config.json)

Structure

{
  "version": "1.0",
  "fleet": {
    "id": "my-project-fleet",
    "name": "My Project QE Fleet",
    "maxAgents": 20,
    "topology": "mesh",
    "heartbeatInterval": 30000
  },
  "agents": {
    "test-generator": {
      "count": 2,
      "config": {
        "targetCoverage": 95,
        "framework": "jest",
        "testStyle": "property-based",
        "aiEnhancement": true
      }
    },
    "test-executor": {
      "count": 3,
      "config": {
        "frameworks": ["jest", "cypress", "playwright"],
        "maxParallelTests": 8,
        "timeout": 300000,
        "retryCount": 3
      }
    },
    "coverage-analyzer": {
      "count": 2,
      "config": {
        "targetCoverage": 95,
        "optimizationAlgorithm": "sublinear",
        "gapDetection": true
      }
    },
    "quality-analyzer": {
      "count": 2,
      "config": {
        "tools": ["eslint", "sonarqube", "lighthouse"],
        "thresholds": {
          "coverage": 85,
          "complexity": 10,
          "maintainability": 65,
          "security": 90
        }
      }
    }
  },
  "memory": {
    "partitionSize": "100MB",
    "defaultTTL": 3600,
    "cleanupInterval": 600,
    "encryption": true
  },
  "testing": {
    "defaultTimeout": 30000,
    "retryCount": 3,
    "parallelWorkers": 4,
    "coverageThreshold": 85,
    "reportFormat": "html"
  },
  "security": {
    "scanEnabled": true,
    "scanDepth": "standard",
    "failOnHigh": true,
    "tools": ["eslint-security", "semgrep", "npm-audit"]
  }
}

Agent-Specific Configuration

Each agent type can have custom configuration:

Test Generator Agent

{
  "agents": {
    "test-generator": {
      "config": {
        "targetCoverage": 95,
        "framework": "jest",
        "testStyle": "property-based",
        "aiEnhancement": true,
        "edgeCaseDetection": true,
        "mockGeneration": true,
        "assertionStyle": "expect",
        "testStructure": "describe-it"
      }
    }
  }
}

Test Executor Agent

{
  "agents": {
    "test-executor": {
      "config": {
        "frameworks": ["jest", "cypress", "playwright"],
        "maxParallelTests": 8,
        "timeout": 300000,
        "retryCount": 3,
        "retryDelay": 1000,
        "continueOnFailure": true,
        "collectCoverage": true,
        "loadBalancing": "round-robin"
      }
    }
  }
}

Coverage Analyzer Agent

{
  "agents": {
    "coverage-analyzer": {
      "config": {
        "targetCoverage": 95,
        "optimizationAlgorithm": "sublinear",
        "gapDetection": true,
        "prioritization": "complexity",
        "analysisType": "comprehensive",
        "generateSuggestions": true
      }
    }
  }
}

Fleet Configuration (config/fleet.yaml)

Complete Example

# config/fleet.yaml
fleet:
  id: "my-project-fleet"
  name: "My Project QE Fleet"
  maxAgents: 20
  topology: mesh  # mesh, hierarchical, ring, star

  coordination:
    strategy: adaptive  # adaptive, balanced, specialized
    heartbeatInterval: 30000
    healthCheckTimeout: 10000

  resources:
    maxMemoryPerAgent: 512MB
    maxCPUPerAgent: 1.0
    diskQuota: 10GB

agents:
  # Test Generator Configuration
  test-generator:
    count: 2
    priority: high
    config:
      frameworks: [jest, mocha, vitest]
      targetCoverage: 95
      testTypes: [unit, integration, property-based]
      aiEnhancement: true

  # Test Executor Configuration
  test-executor:
    count: 3
    priority: high
    config:
      frameworks: [jest, cypress, playwright]
      maxParallelTests: 8
      timeout: 300000
      retryLogic:
        enabled: true
        maxRetries: 3
        retryDelay: 1000

  # Coverage Analyzer Configuration
  coverage-analyzer:
    count: 2
    priority: medium
    config:
      targetCoverage: 95
      optimizationAlgorithm: sublinear
      gapDetection:
        enabled: true
        prioritization: complexity

  # Quality Gate Configuration
  quality-gate:
    count: 1
    priority: high
    config:
      thresholds:
        coverage: 85
        complexity: 10
        maintainability: 65
        security: 90
        performance: 85
      blockOnFailure: true

  # Security Scanner Configuration
  security-scanner:
    count: 1
    priority: high
    config:
      scanTypes: [sast, dast, dependency]
      severity: high
      compliance: [OWASP-Top-10, CWE-Top-25]

  # Performance Tester Configuration
  performance-tester:
    count: 1
    priority: medium
    config:
      tools: [k6, jmeter, gatling]
      loadProfiles:
        - name: light
          users: 10
          duration: 60s
        - name: moderate
          users: 50
          duration: 300s
        - name: heavy
          users: 100
          duration: 600s

memory:
  backend: sqlite  # sqlite or postgres
  database:
    type: sqlite
    filename: ./data/memory.db

  partitions:
    aqe: 100MB
    swarm: 50MB
    agent: 200MB

  ttl:
    default: 3600
    temporary: 300
    permanent: 0

  cleanup:
    enabled: true
    interval: 600
    aggressive: false

logging:
  level: info  # error, warn, info, debug, verbose
  format: json  # json or text
  outputs:
    - type: file
      filename: ./logs/aqe.log
      maxSize: 10m
      maxFiles: 5
    - type: console
      colorize: true

  components:
    fleet: info
    agents: info
    memory: warn
    events: debug

testing:
  defaults:
    timeout: 30000
    retryCount: 3
    parallelWorkers: 4

  coverage:
    enabled: true
    threshold: 85
    reporters: [html, lcov, text]

  reporting:
    format: json
    outputDir: ./reports
    includeSkipped: false

security:
  scanning:
    enabled: true
    schedule: daily
    depth: standard  # basic, standard, deep

  tools:
    - name: eslint-security
      enabled: true
    - name: semgrep
      enabled: true
      config: ./semgrep.yml
    - name: npm-audit
      enabled: true
      severity: moderate

  policies:
    failOnHigh: true
    blockOnCritical: true
    exemptions: []

CLI Configuration Commands

View Current Configuration

# Show all configuration
aqe config show

# Show specific configuration key
aqe config get --key fleet.maxAgents

Update Configuration

# Set configuration value
aqe config set --key fleet.maxAgents --value 30

# Set nested configuration
aqe config set --key agents.test-generator.config.targetCoverage --value 95

Configuration Validation

# Validate configuration file
aqe config validate --file .agentic-qe/config.json

# Validate fleet YAML
aqe config validate --file config/fleet.yaml

Configuration Priority

Configuration is applied in the following order (highest to lowest):

1. CLI Options - Command-line arguments
2. Environment Variables - Runtime environment
3. Configuration File - .agentic-qe/config.json
4. Fleet YAML - config/fleet.yaml
5. Defaults - Built-in default values

Example:

# Coverage threshold resolution:
# 1. CLI: --coverage 90
# 2. ENV: TEST_COVERAGE_THRESHOLD=85
# 3. Config: "testing.coverageThreshold": 80
# 4. YAML: testing.coverage.threshold: 75
# 5. Default: 70

# Result: 90 (from CLI)

Best Practices

1. Use Environment Variables for Secrets

Never commit secrets to configuration files:

# .env (not committed)
DB_PASSWORD=secure_password
API_KEY=secret_key

2. Separate Development and Production Configs

# Development
.env.development

# Production
.env.production

Load based on environment:

NODE_ENV=production aqe execute

3. Version Control Configuration

Commit these files:

• .agentic-qe/config.json (without secrets)
• config/fleet.yaml (without secrets)
• .env.example (template with no values)

Do NOT commit:

• .env (actual secrets)
• .env.local (local overrides)

4. Use Fleet YAML for Complex Setups

For multi-agent coordination and advanced features, use fleet.yaml:

fleet:
  topology: hierarchical
  coordination:
    strategy: adaptive

5. Validate Configuration Before Deployment

# Always validate before deploying
aqe config validate --file config/fleet.yaml
aqe config validate --file .agentic-qe/config.json

Troubleshooting

Configuration Not Loading

Check configuration file location:

ls -la .agentic-qe/config.json
ls -la config/fleet.yaml

Validate JSON syntax:

cat .agentic-qe/config.json | jq .

Environment Variables Not Applied

Check environment variable names:

env | grep AQE
env | grep FLEET

Verify environment file is loaded:

# Load .env explicitly
source .env
aqe execute

Agent Configuration Not Working

Check agent name spelling:

# Correct agent names
aqe config get --key agents.test-generator
aqe config get --key agents.test-executor
aqe config get --key agents.coverage-analyzer

Examples

Minimal Configuration

{
  "version": "1.0",
  "fleet": {
    "maxAgents": 10
  },
  "testing": {
    "coverageThreshold": 80
  }
}

Production Configuration

{
  "version": "1.0",
  "fleet": {
    "id": "production-qe-fleet",
    "name": "Production QE Fleet",
    "maxAgents": 50,
    "topology": "mesh"
  },
  "agents": {
    "test-executor": {
      "count": 10,
      "config": {
        "maxParallelTests": 20,
        "timeout": 600000
      }
    }
  },
  "memory": {
    "encryption": true,
    "partitionSize": "500MB"
  },
  "security": {
    "scanEnabled": true,
    "scanDepth": "deep",
    "failOnHigh": true
  },
  "logging": {
    "level": "warn",
    "format": "json"
  }
}

Related Documentation

• User Guide - Getting started guide
• Troubleshooting - Common issues and solutions
• API Reference - Programmatic API documentation
• MCP Integration - Claude Code integration