agentic-qe/README.md

Agentic Quality Engineering Fleet System - AI-driven quality management platform

# Agentic Quality Engineering Fleet

<div align="center">

[![npm version](https://img.shields.io/npm/v/agentic-qe.svg)](https://www.npmjs.com/package/agentic-qe)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

**AI-Driven Quality Engineering Automation**

A distributed fleet of specialized AI agents for comprehensive software testing, quality assurance, and continuous validation.

[Quick Start](#quick-start) • [Documentation](docs/) • [Contributing](CONTRIBUTING.md) • [Examples](examples/)

</div>

---

## 🚀 Features

### Autonomous Agent Fleet
- **16 Specialized QE Agents**: Each agent is an expert in specific quality engineering domains
- **Intelligent Coordination**: Event-driven architecture with automatic task distribution
- **Scalable**: From single developer projects to enterprise-scale testing infrastructure
- **Self-Organizing**: Agents autonomously coordinate testing strategies

### Comprehensive Testing
- **AI-Powered Test Generation**: Generate comprehensive test suites automatically
- **Multi-Framework Support**: Jest, Mocha, Cypress, Playwright, and more
- **Parallel Execution**: Execute thousands of tests concurrently with intelligent orchestration
- **Real-Time Coverage Analysis**: O(log n) algorithms for instant coverage gap detection

### Quality Intelligence
- **Smart Quality Gates**: ML-driven quality assessment with risk scoring
- **Security Scanning**: SAST, DAST, dependency analysis, and container security
- **Performance Testing**: Load testing with k6, JMeter, and Gatling integration
- **Visual Regression**: AI-powered screenshot comparison and UI validation

### Advanced Capabilities
- **Flaky Test Detection**: Statistical analysis with automatic stabilization
- **API Contract Validation**: Breaking change detection across versions
- **Test Data Generation**: 10,000+ realistic records per second
- **Production Intelligence**: Convert production incidents into test scenarios
- **Chaos Engineering**: Controlled fault injection for resilience testing

---

## 📦 Prerequisites & Installation

### What's New in v1.0.1

**Patch Release** - October 7, 2025

🔒 **Security Fix**: Removed vulnerable `faker` package (CVE-2022-42003)
✅ **Test Infrastructure**: Fixed async timing and agent lifecycle issues
📚 **Documentation**: Added comprehensive user guides (USER-GUIDE, CONFIGURATION, TROUBLESHOOTING)
🐛 **Bug Fixes**: Improved memory management and test reliability

[View Complete Changelog](./CHANGELOG.md#101---2025-10-07)

### Prerequisites

Before using Agentic QE, you must have:

#### Required
- **Claude Code**: Install from [claude.ai/code](https://claude.ai/code)
- **Node.js**: 18.0 or higher
- **npm**: 8.0 or higher

#### Optional (Advanced Features)
- **Claude Flow**: For advanced coordination
  ```bash
  npm install -g @claude/flow
  # or
  npx claude-flow@alpha init --force
  ```

### Installation Steps

1. **Install Claude Code** globally or in your workspace

2. **Install Agentic QE**

   **Global Installation** (Recommended)
   ```bash
   npm install -g agentic-qe

   # Verify installation
   aqe --version
   ```

   **Project Installation**
   ```bash
   npm install --save-dev agentic-qe

   # Use with npx
   npx aqe init
   ```

3. **Local Development**
   ```bash
   git clone https://github.com/proffesor-for-testing/agentic-qe.git
   cd agentic-qe
   npm install
   npm run build
   npm link
   ```

### System Requirements

- **Memory**: 2GB+ recommended for large test suites
- **OS**: Linux, macOS, Windows (via WSL2)
- **Agent Execution**: Via Claude Code's Task tool or MCP integration

---

## ⚡ Quick Start

### 1. Install & Setup MCP Integration

```bash
# Install Agentic QE
npm install -g agentic-qe

# Add MCP server to Claude Code
claude mcp add agentic-qe npx -y agentic-qe mcp:start

# Verify connection
claude mcp list
```

### 2. Initialize Your Project

```bash
# Initialize AQE Fleet in your project
cd your-project
aqe init
```

**What it does:**
- Creates `.claude/agents/` with 16 specialized QE agent definitions
- Creates `.claude/commands/` with 8 AQE slash commands
- Creates `.agentic-qe/` configuration directory
- Updates or creates `CLAUDE.md` with integration documentation

### 3. Use from Claude Code CLI

```bash
# Ask Claude to generate tests using AQE agents
claude "Initialize AQE fleet and generate comprehensive tests for src/services/user-service.ts with 95% coverage"
```

**Agent Execution Model:**
- Agents are Claude Code agent definitions (markdown files in `.claude/agents/`)
- Executed via Claude Code's Task tool OR MCP tools
- MCP integration enables Claude to orchestrate QE agents directly
- NOT standalone Node.js processes

📖 **[Complete MCP Integration Guide](docs/guides/MCP-INTEGRATION.md)** - Detailed setup, examples, and use cases

### Basic Commands

```bash
# Check fleet status
aqe status

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

# Analyze test coverage
aqe coverage --threshold 95

# Run quality gate validation
aqe quality

# Execute comprehensive test suite
aqe execute --parallel --coverage

# View all commands
aqe help
```

### Programmatic Usage

```typescript
import { FleetManager, QEAgentFactory } from 'agentic-qe';

// Initialize fleet
const fleet = new FleetManager({
  maxAgents: 20,
  topology: 'mesh'
});

await fleet.initialize();

// Spawn test generator agent
const testGen = await fleet.spawnAgent('test-generator', {
  targetCoverage: 95,
  framework: 'jest'
});

// Generate tests for a module
const tests = await testGen.execute({
  sourceFile: 'src/services/user-service.ts',
  testStyle: 'property-based'
});
```

---

## 🤖 Agent Types

### Core Testing Agents

| Agent | Purpose | Key Features |
|-------|---------|-------------|
| **test-generator** | AI-powered test creation | Property-based testing, edge case detection |
| **test-executor** | Multi-framework execution | Parallel processing, retry logic, reporting |
| **coverage-analyzer** | Real-time gap analysis | O(log n) algorithms, trend tracking |
| **quality-gate** | Intelligent validation | ML-driven decisions, risk assessment |
| **quality-analyzer** | Metrics analysis | ESLint, SonarQube, Lighthouse integration |

### Performance & Security

| Agent | Purpose | Key Features |
|-------|---------|-------------|
| **performance-tester** | Load & stress testing | k6, JMeter, Gatling, bottleneck detection |
| **security-scanner** | Vulnerability detection | SAST, DAST, dependency scanning |

### Strategic Planning

| Agent | Purpose | Key Features |
|-------|---------|-------------|
| **requirements-validator** | Testability analysis | INVEST criteria, BDD generation |
| **production-intelligence** | Incident replay | RUM analysis, anomaly detection |
| **fleet-commander** | Hierarchical coordination | 50+ agent orchestration |

### Advanced Testing

| Agent | Purpose | Key Features |
|-------|---------|-------------|
| **regression-risk-analyzer** | Smart test selection | ML patterns, AST analysis |
| **test-data-architect** | Realistic data generation | 10k+ records/sec, GDPR compliant |
| **api-contract-validator** | Breaking change detection | OpenAPI, GraphQL, gRPC |
| **flaky-test-hunter** | Stability analysis | Statistical detection, auto-fix |

### Specialized

| Agent | Purpose | Key Features |
|-------|---------|-------------|
| **deployment-readiness** | Release validation | Multi-factor risk scoring |
| **visual-tester** | UI regression | AI-powered comparison |
| **chaos-engineer** | Resilience testing | Fault injection, blast radius |

---

## 🏗️ Architecture

### Core Components

```
┌─────────────────────────────────────────────┐
│           Fleet Manager                      │
│  (Central Coordination & Task Distribution) │
└─────────────────────────────────────────────┘
                    │
        ┌───────────┼───────────┐
        │           │           │
   ┌────▼────┐ ┌───▼────┐ ┌───▼────┐
   │ Agent 1 │ │ Agent 2│ │ Agent N│
   │  Pool   │ │  Pool  │ │  Pool  │
   └────┬────┘ └───┬────┘ └───┬────┘
        │          │          │
   ┌────▼──────────▼──────────▼────┐
   │        Event Bus               │
   │  (Event-Driven Communication)  │
   └────┬──────────────────────┬────┘
        │                      │
   ┌────▼────┐           ┌────▼────┐
   │  Memory │           │Database │
   │  Store  │           │(SQLite) │
   └─────────┘           └─────────┘
```

### Event-Driven Architecture

- **EventBus**: Real-time communication between agents
- **Task Queue**: Priority-based task scheduling
- **Memory Store**: Shared context and learning
- **Persistence**: SQLite for state, metrics, and audit trails

---

## 📖 Documentation

### Getting Started
- [Quick Start Guide](docs/AQE-CLI.md)
- [User Guide](docs/USER-GUIDE.md) - **NEW!** Comprehensive workflows and examples
- [Agent Types Overview](docs/Agentic-QE-Fleet-Specification.md)
- [Configuration Guide](docs/CONFIGURATION.md) - **NEW!** Complete configuration reference
- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - **NEW!** Common issues and solutions

### User Guides
- [Test Generation](docs/guides/TEST-GENERATION.md)
- [Coverage Analysis](docs/guides/COVERAGE-ANALYSIS.md)
- [Quality Gates](docs/guides/QUALITY-GATES.md)
- [Performance Testing](docs/guides/PERFORMANCE-TESTING.md)

### Advanced Topics
- [API Reference](docs/API.md)
- [Agent Development](docs/AGENT-DEVELOPMENT.md)
- [MCP Integration](docs/CLAUDE-MD-INTEGRATION.md)
- [Best Practices](docs/AI%20%26%20Agentic%20Security%20Best%20Practices.md)

### Commands Reference
- [AQE Commands Overview](docs/QE-COMMANDS-INDEX.md)
- [Command Specifications](docs/QE-SLASH-COMMANDS-SPECIFICATION.md)
- [Hooks Architecture](docs/QE_HOOKS_ARCHITECTURE.md)

---

## 🔧 Configuration

### Environment Variables

Create a `.env` file in your project root:

```bash
# Fleet Configuration
FLEET_ID=my-project-fleet
MAX_AGENTS=20
HEARTBEAT_INTERVAL=30000

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

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

# API (optional)
API_PORT=3000
API_HOST=localhost
```

### Fleet Configuration

Create `config/fleet.yaml`:

```yaml
fleet:
  id: "my-project-fleet"
  name: "My Project QE Fleet"
  maxAgents: 20
  topology: mesh

agents:
  test-executor:
    count: 3
    config:
      frameworks: [jest, cypress, playwright]
      maxParallelTests: 8
      timeout: 300000

  coverage-analyzer:
    count: 2
    config:
      targetCoverage: 95
      optimizationAlgorithm: sublinear

  quality-analyzer:
    count: 2
    config:
      tools: [eslint, sonarqube, lighthouse]
      thresholds:
        coverage: 80
        complexity: 10
        maintainability: 65
```

---

## 🧪 Examples

### Test Generation

```typescript
import { Task, TaskPriority } from 'agentic-qe';

// Generate comprehensive test suite
const generateTests = new Task(
  'test-generation',
  'Generate Tests for User Service',
  {
    sourceFile: './src/services/user-service.ts',
    framework: 'jest',
    coverage: 95,
    testTypes: ['unit', 'integration', 'property-based']
  },
  {},
  TaskPriority.HIGH
);

await fleet.submitTask(generateTests);
```

### Quality Analysis

```typescript
const qualityAnalysis = new Task(
  'quality-analysis',
  'Comprehensive Quality Check',
  {
    sourcePath: './src',
    tools: ['eslint', 'sonarqube', 'lighthouse'],
    thresholds: {
      coverage: 80,
      complexity: 10,
      security: 90
    }
  },
  {},
  TaskPriority.MEDIUM
);
```

### Security Scanning

```typescript
const securityScan = new Task(
  'security-scan',
  'SAST & DAST Security Analysis',
  {
    sourcePath: './src',
    scanTypes: ['sast', 'dast', 'dependency', 'container'],
    severity: 'high',
    compliance: ['OWASP-Top-10', 'CWE-Top-25']
  },
  {},
  TaskPriority.HIGH
);
```

More examples in [examples/](examples/)

---

## 🐳 Docker Deployment

### Quick Start

```bash
# Start with SQLite (development)
docker-compose up -d

# Start with PostgreSQL (production)
docker-compose --profile postgres up -d
```

### Production Deployment

```bash
# Configure production environment
cp .env.example .env.production
# Edit .env.production with secure credentials

# Deploy
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

### Docker Compose Configuration

```yaml
version: '3.8'
services:
  agentic-qe:
    image: agentic-qe:latest
    environment:
      - FLEET_ID=prod-fleet
      - MAX_AGENTS=50
      - DB_TYPE=postgres
    volumes:
      - ./config:/app/config
      - ./data:/app/data
    ports:
      - "3000:3000"
```

---

## 🚀 Development

### Setup

```bash
# Clone repository
git clone https://github.com/proffesor-for-testing/agentic-qe.git
cd agentic-qe

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test
```

### Available Scripts

| Script | Description |
|--------|-------------|
| `npm run build` | Compile TypeScript to JavaScript |
| `npm run dev` | Development mode with hot reload |
| `npm test` | Run all test suites |
| `npm run test:unit` | Unit tests only |
| `npm run test:integration` | Integration tests |
| `npm run test:coverage` | Generate coverage report |
| `npm run lint` | ESLint code checking |
| `npm run lint:fix` | Auto-fix linting issues |
| `npm run typecheck` | TypeScript type checking |

### Project Structure

```
agentic-qe/
├── src/
│   ├── agents/          # 16 agent implementations
│   ├── core/            # Core fleet management
│   │   ├── FleetManager.ts
│   │   ├── Agent.ts
│   │   ├── Task.ts
│   │   ├── EventBus.ts
│   │   └── MemoryManager.ts
│   ├── cli/             # Command-line interface
│   ├── mcp/             # Model Context Protocol server
│   ├── types/           # TypeScript type definitions
│   └── utils/           # Shared utilities
├── tests/               # Comprehensive test suites
│   ├── unit/
│   ├── integration/
│   ├── e2e/
│   └── performance/
├── examples/            # Usage examples
├── docs/                # Documentation
├── .claude/             # Agent & command definitions
│   ├── agents/          # 16 QE agent definitions
│   └── commands/        # 8 AQE slash commands
└── config/              # Configuration files
```

---

## 📊 Performance

- **Test Generation**: 1000+ tests/minute
- **Parallel Execution**: 10,000+ concurrent tests
- **Coverage Analysis**: O(log n) complexity
- **Data Generation**: 10,000+ records/second
- **Agent Spawning**: <100ms per agent
- **Memory Efficient**: <2GB for typical projects

---

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

### Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`npm test`)
6. Commit your changes (`git commit -m 'feat: add amazing feature'`)
7. Push to your branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

### Development Guidelines

- Follow the existing code style
- Write comprehensive tests
- Update documentation
- Use conventional commits
- Ensure TypeScript types are accurate

---

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Built with TypeScript, Node.js, and SQLite
- Inspired by autonomous agent architectures and swarm intelligence
- Integrates with Jest, Cypress, Playwright, k6, SonarQube, and more
- Compatible with Claude Code via Model Context Protocol (MCP)

---

## 📞 Support

- **Documentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/proffesor-for-testing/agentic-qe/issues)
- **Discussions**: [GitHub Discussions](https://github.com/proffesor-for-testing/agentic-qe/discussions)
- **Email**: support@agentic-qe.com

---

## 🗺️ Roadmap

### Current (v1.0)
- ✅ 16 specialized QE agents
- ✅ Multi-framework test execution
- ✅ Real-time coverage analysis
- ✅ MCP integration

### Planned (v1.1)
- 🔄 Cloud deployment support
- 🔄 GraphQL API
- 🔄 Web dashboard
- 🔄 CI/CD integrations (GitHub Actions, GitLab CI)

### Future (v2.0)
- 📋 Machine learning for test prioritization
- 📋 Natural language test generation
- 📋 Self-healing test suites
- 📋 Multi-language support (Python, Java, Go)

---

<div align="center">

**Made with ❤️ by the Agentic QE Team**

[⭐ Star us on GitHub](https://github.com/proffesor-for-testing/agentic-qe) • [🐦 Follow on Twitter](https://twitter.com/agenticqe)

</div>