proffesor-for-testing__agentic-qe/docs/USER-GUIDE.md

Agentic QE Fleet - User Guide

Getting Started

This guide will help you get up and running with Agentic QE Fleet quickly.

Prerequisites

• Node.js 18.0 or higher
• npm 8.0 or higher
• Claude Code (optional, for MCP integration)

Installation

# Global installation (recommended)
npm install -g agentic-qe

# Verify installation
aqe --version

Initialize Your Project

cd your-project
aqe init

This creates:

• .claude/agents/ - 16 specialized QE agent definitions
• .claude/commands/ - 8 AQE slash commands
• .agentic-qe/ - Configuration directory
• CLAUDE.md - Integration documentation

Basic Workflows

1. Test Generation

Generate comprehensive test suites for your code:

# Generate tests for a single file
aqe test src/services/user-service.ts

# Generate tests with specific coverage target
aqe test src/services/user-service.ts --coverage 95

# Generate tests with specific framework
aqe test src/services/*.ts --framework jest --coverage 90

What happens:

1. The qe-test-generator agent analyzes your code
2. AI-powered test creation identifies edge cases
3. Property-based tests are generated automatically
4. Tests are saved to tests/ directory

2. Test Execution

Run tests with intelligent orchestration:

# Execute all tests
aqe execute

# Execute with parallel processing
aqe execute --parallel --workers 4

# Execute with coverage
aqe execute --coverage --threshold 90

Features:

• Parallel test execution across multiple workers
• Retry logic for flaky tests (3 retries by default)
• Real-time progress reporting
• Comprehensive result summaries

3. Coverage Analysis

Analyze and optimize test coverage:

# Analyze coverage with gap detection
aqe coverage

# Analyze with specific threshold
aqe coverage --threshold 95

# Generate detailed coverage report
aqe coverage --report html

Output includes:

• Overall coverage percentage
• Coverage gaps by file
• Prioritized gap recommendations
• Visual coverage reports

4. Quality Gates

Run comprehensive quality validation:

# Run quality gate check
aqe quality

# With custom thresholds
aqe quality --coverage 90 --complexity 10

# Export quality report
aqe quality --export report.json

Quality checks include:

• Code coverage thresholds
• Cyclomatic complexity
• Security vulnerabilities
• Performance benchmarks
• Test reliability

5. Fleet Management

Monitor and manage your QE agent fleet:

# Check fleet status
aqe status

# View detailed fleet information
aqe fleet status --verbose

# Monitor fleet in real-time
aqe fleet monitor --interval 5s

Common Use Cases

Use Case 1: Adding Tests to Legacy Code

# Step 1: Initialize AQE in your project
cd legacy-project
aqe init

# Step 2: Generate tests for high-risk modules first
aqe test src/core/payment-processor.ts --coverage 95

# Step 3: Review generated tests
cat tests/core/payment-processor.test.ts

# Step 4: Execute tests to verify
aqe execute tests/core/payment-processor.test.ts

# Step 5: Iterate on coverage gaps
aqe coverage src/core/payment-processor.ts

Use Case 2: CI/CD Integration

# .github/workflows/quality-check.yml
name: Quality Check

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install AQE
        run: npm install -g agentic-qe

      - name: Initialize AQE
        run: aqe init

      - name: Run Quality Gate
        run: aqe quality --coverage 90 --exit-code

      - name: Upload Coverage Report
        uses: actions/upload-artifact@v3
        with:
          name: coverage-report
          path: coverage/

Use Case 3: Performance Testing

# Run performance benchmarks
aqe benchmark --suite load-test

# Performance test with custom configuration
aqe benchmark \
  --type load \
  --users 100 \
  --duration 300s \
  --ramp-up 30s

Use Case 4: Security Scanning

# Run comprehensive security scan
aqe security scan --depth deep

# Scan with specific focus
aqe security scan --type sast,dast,dependency

Advanced Features

Multi-Agent Coordination

Use multiple agents for complex workflows:

# Orchestrate comprehensive QE workflow
aqe fleet orchestrate \
  --agents test-generator,test-executor,coverage-analyzer \
  --task "comprehensive-qa-pipeline"

Custom Agent Configuration

Create custom agent configurations in .agentic-qe/config.json:

{
  "fleet": {
    "maxAgents": 20,
    "topology": "mesh"
  },
  "agents": {
    "test-generator": {
      "targetCoverage": 95,
      "framework": "jest",
      "testStyle": "property-based"
    },
    "test-executor": {
      "maxParallelTests": 8,
      "retryCount": 3,
      "timeout": 300000
    }
  }
}

Memory System

Agents share state and learning via the memory system:

# View shared memory
aqe memory query --namespace aqe

# Store custom configuration
aqe memory store --key "aqe/config/coverage-target" --value "95"

# Backup memory state
aqe memory backup --export memory-backup.json

Troubleshooting

Common Issues

Issue: Tests are not being generated

Symptoms:

• aqe test command completes but no tests are created
• Error: "No testable code found"

Solutions:

1. Verify file paths are correct
2. Check that files contain exportable functions/classes
3. Ensure supported file extensions (.ts, .js, .jsx, .tsx)

# Debug mode for more information
aqe test src/service.ts --verbose

Issue: Agent execution failures

Symptoms:

• "Agent failed to start" errors
• Timeout errors

Solutions:

1. Check system resources (memory, CPU)
2. Reduce concurrent agents: aqe config set --key fleet.maxAgents --value 10
3. Increase timeouts: aqe config set --key agent.timeout --value 600000

Issue: MCP connection problems

Symptoms:

• "Cannot connect to MCP server"
• Claude Code integration not working

Solutions:

1. Verify MCP server is added: claude mcp list
2. Restart Claude Code
3. Check MCP server logs: ~/.claude/logs/mcp-agentic-qe.log
4. Re-add MCP server: claude mcp add agentic-qe npx -y agentic-qe mcp:start

Issue: High memory usage

Symptoms:

• Process running out of memory
• "JavaScript heap out of memory" errors

Solutions:

1. Reduce parallel workers: aqe execute --workers 1
2. Execute tests in batches: aqe execute tests/unit/ && aqe execute tests/integration/
3. Increase Node.js memory: NODE_OPTIONS="--max-old-space-size=4096" aqe execute

Best Practices

1. Start with Critical Modules

Focus test generation on high-risk code first:

• Payment processing
• Authentication/authorization
• Data validation
• API endpoints

2. Set Realistic Coverage Targets

Don't aim for 100% coverage immediately:

• Critical modules: 95%+
• Business logic: 85%+
• Utilities: 80%+
• UI components: 70%+

3. Use Quality Gates in CI/CD

Enforce quality standards automatically:

aqe quality --coverage 85 --exit-code

4. Monitor Fleet Health

Regularly check agent performance:

aqe fleet status --export metrics.json

5. Leverage AI Insights

Review AI-generated recommendations:

• Test case suggestions
• Coverage gap priorities
• Security vulnerability patterns

Next Steps

• Configuration Guide: CONFIGURATION.md
• Troubleshooting Guide: TROUBLESHOOTING.md
• API Reference: API.md
• MCP Integration: guides/MCP-INTEGRATION.md

Getting Help

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions and share experiences
• Documentation: Complete docs

Quick Reference

Essential Commands

aqe init                    # Initialize AQE in project
aqe test <file>             # Generate tests
aqe execute                 # Run tests
aqe coverage                # Analyze coverage
aqe quality                 # Run quality gate
aqe status                  # Check fleet status
aqe help                    # Show all commands

Common Options

--verbose                   # Detailed output
--coverage <number>         # Coverage target (0-100)
--parallel                  # Enable parallel execution
--workers <number>          # Number of parallel workers
--timeout <ms>              # Operation timeout
--exit-code                 # Exit with code 1 on failure