Transform API testing with specialized AI agents that generate, execute, and analyze comprehensive test suites automatically.

Sentinel is an enterprise-grade, AI-powered platform that automates the entire API testing lifecycle using specialized agents for functional, security, and performance testing. Built with a modern microservices architecture and hybrid Python/Rust implementation for optimal performance.

📋 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📖 Documentation
• 🏗️ Architecture
• 🤖 AI Agents
• 💻 Usage
• 🧪 Testing
• 🛠️ Development
• 🤝 Contributing
• 📄 License
• 🆘 Support

✨ Features

🎯 Intelligent Test Generation

• AI-Powered Agents: 7 specialized agents for functional, security, and performance testing
• Multi-LLM Support: Anthropic Claude, OpenAI GPT-4, Google Gemini, Mistral, and local Ollama models
• Specification-Driven: Automatic test generation from OpenAPI/Swagger specifications
• Hybrid Architecture: Python + Rust with intelligent routing based on real-time performance metrics

🔒 Comprehensive Testing

• Functional Testing: Positive, negative, and stateful workflow testing
• Security Testing: BOLA, injection attacks (SQL/NoSQL/Command/LLM), authorization testing
• Performance Testing: Load, stress, and spike testing with k6/JMeter/Locust
• 540+ Tests: 97.8% pass rate with comprehensive coverage

🎨 Modern User Interface

• React Dashboard: Real-time metrics and interactive test management
• Specification Management: Upload, parse, and manage OpenAPI specs
• Test Execution: One-click test runs with detailed results
• Analytics: Trend analysis and comprehensive reporting

⚡ Enterprise-Ready

• Microservices Architecture: 10 independent, scalable services
• Docker Deployment: Complete containerization with Docker Compose
• Observability: Prometheus metrics, Jaeger tracing, structured logging
• RBAC: Role-based access control with JWT authentication

🚀 Quick Start

Get Sentinel running in under 5 minutes:

Prerequisites

• Docker and Docker Compose (required)
• Git (required)
• Make (optional, for convenience commands)
• Python 3.10+ (only for local development)
• Node.js 14+ (only for frontend development)

Installation

1. Clone the repository

   git clone https://github.com/proffesor-for-testing/sentinel-api-testing.git
   cd sentinel-api-testing

2. Configure LLM provider (optional but recommended for AI features)

   # Set your API key for AI-powered test generation
   export SENTINEL_APP_ANTHROPIC_API_KEY="your-anthropic-api-key"
   # Or use the configuration script for other providers
   cd sentinel_backend/scripts
   ./switch_llm.sh claude    # Claude (default)
   ./switch_llm.sh openai    # OpenAI GPT-4
   ./switch_llm.sh gemini    # Google Gemini
   ./switch_llm.sh local     # Local Ollama

3. Start the platform

   # Complete setup with one command
   make setup
   # Or manually with Docker Compose
   docker-compose up --build -d
   make init-db

4. Access the platform

   • 🌐 Frontend: http://localhost:3000
   • 🔐 Login: admin@sentinel.com / admin123
   • 📚 API Docs: http://localhost:8000/docs
   • 🧪 Test API: http://localhost:8080 (Petstore demo)

Verify Installation

# Check all services are running
make status
# View service logs
make logs
# Run health checks
curl http://localhost:3000/health
curl http://localhost:8000/health

That's it! You now have a fully functional AI-powered API testing platform running locally.

📖 Documentation

📘 Getting Started

• Quick Start Guide - Detailed setup instructions
• User Guide - Complete platform usage guide
• FAQ - Common questions and solutions

🏗️ Technical Documentation

• Architecture Overview - System design and components
• API Reference - REST API documentation
• Database Schema - Data model design
• Hybrid Python/Rust Architecture - Performance details

🚀 Deployment & Operations

• Deployment Guide - Production deployment
• Docker Guide - Container orchestration
• Troubleshooting - Common issues and solutions
• Observability - Metrics and tracing

🤖 AI Agents

• Agent Specifications - Detailed agent capabilities
• Rust Agents - High-performance implementations
• LLM Configuration - Multi-provider setup

🏗️ Architecture

Sentinel uses a modern microservices architecture with 10 independent services:

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (React + nginx)                 │
│                     http://localhost:3000                   │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                   API Gateway (FastAPI)                     │
│                     http://localhost:8000                   │
└─────┬────────┬────────┬────────┬────────┬──────────────────┘
      │        │        │        │        │
┌─────▼────┐ ┌▼──────┐ ┌▼──────┐ ┌▼─────┐ ┌▼────────────────┐
│   Auth   │ │ Spec  │ │ Orch. │ │ Exec.│ │  Data Service   │
│ Service  │ │Service│ │Service│ │Service│ │   (Analytics)   │
│  :8005   │ │ :8001 │ │ :8002 │ │ :8003│ │      :8004      │
└──────────┘ └───────┘ └───┬───┘ └──────┘ └─────────────────┘
                            │
                   ┌────────▼────────┐
                   │  Rust Core      │
                   │  (ruv-swarm)    │
                   │     :8088       │
                   └────────┬────────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
    ┌────▼─────┐     ┌─────▼──────┐    ┌─────▼──────┐
    │PostgreSQL│     │  RabbitMQ  │    │ Prometheus │
    │  +vector │     │   :5672    │    │   :9090    │
    │  :5432   │     └────────────┘    └────────────┘
    └──────────┘

Core Services

🤖 AI Agents

Sentinel employs 7 specialized AI agents with both Python and Rust implementations:

Functional Testing Agents

• 🟢 Functional-Positive-Agent: Valid "happy path" test generation with schema-based data
• 🔴 Functional-Negative-Agent: Boundary value analysis and creative negative testing
• 🔄 Functional-Stateful-Agent: Complex multi-step workflows with dependency graphs

Security Testing Agents

• 🔒 Security-Auth-Agent: BOLA, authorization bypass, authentication vulnerabilities
• 💉 Security-Injection-Agent: SQL/NoSQL/Command/LLM injection attack testing

Performance Testing Agents

• ⚡ Performance-Planner-Agent: Load, stress, spike testing with k6/JMeter/Locust scripts

Data Generation Agents

• 📊 Data-Mocking-Agent: Intelligent, schema-aware test data generation

Performance

Intelligent Routing: System selects optimal implementation based on real-time performance metrics. Benchmark testing shows Python and Rust implementations have comparable performance with different strengths - Python excels at LLM-integrated workflows while Rust provides consistent performance for high-volume generation.

Performance Note: Early claims of "18-21x" Rust performance advantage have been revised after comprehensive benchmarking. Actual performance varies by workload - see docs/BENCHMARK_RESULTS.md for detailed metrics.

💻 Usage

1️⃣ Upload API Specification

# Via UI: Navigate to Specifications → Upload
# Or via API:
curl -X POST http://localhost:8000/api/v1/specifications \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@petstore.yaml"

2️⃣ Generate Tests with AI

# Via UI: Click "Generate Tests" → Select agents
# Or via API:
curl -X POST http://localhost:8000/api/v1/test-generation \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "specification_id": "spec-123",
    "agents": ["functional-positive", "security-auth"],
    "options": {
      "max_tests_per_agent": 50,
      "use_rust": true
    }
  }'

3️⃣ Execute Test Suites

# Via UI: Test Suites → Click "Run"
# Or via API:
curl -X POST http://localhost:8000/api/v1/test-runs \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "test_suite_id": "suite-456",
    "target_environment": "http://api.example.com"
  }'

4️⃣ View Results & Analytics

• Dashboard: Real-time metrics at http://localhost:3000/dashboard
• Test Runs: Detailed results at http://localhost:3000/test-runs
• Analytics: Trend analysis at http://localhost:3000/analytics

Example Workflow

# 1. Start the platform
make setup
# 2. Login to the UI
# Visit http://localhost:3000
# Login: admin@sentinel.com / admin123
# 3. Upload Petstore specification
# Navigate to Specifications → Upload → Choose petstore.yaml
# 4. Generate tests with multiple agents
# Click "Generate Tests" → Select all agents → Generate
# 5. Create test suite
# Navigate to Test Cases → Select tests → "Create Suite"
# 6. Run tests
# Navigate to Test Suites → Select suite → "Run Tests"
# Target: http://localhost:8080 (Petstore API)
# 7. View results
# Navigate to Test Runs → Click latest run → View detailed results

🧪 Testing

Sentinel includes 540+ comprehensive tests with 97.8% pass rate:

Run All Tests

# Recommended: Run tests in Docker for consistency
cd sentinel_backend
./run_tests.sh -d
# Run specific test categories
./run_tests.sh -d -t unit          # Unit tests (456 tests)
./run_tests.sh -d -t integration   # Integration tests (20 tests)
./run_tests.sh -d -t e2e           # End-to-end tests (30 tests)
./run_tests.sh -d -t agents        # AI agent tests (184 tests)

Test Coverage

Frontend E2E Tests (Playwright)

cd sentinel_frontend
npm test                           # Run all Playwright tests
npm test -- auth.spec.ts          # Run authentication tests
npm test -- --headed              # Run with browser UI

Performance Tests

cd sentinel_backend
pytest tests/performance/ -v       # Run all performance tests
pytest tests/performance/test_load_performance.py -v  # Load testing

🛠️ Development

Local Development Setup

Backend Services

1. Install dependencies

   cd sentinel_backend
   poetry install

2. Run individual services

   # Example: API Gateway
   cd api_gateway
   poetry run uvicorn main:app --reload --port 8000

Frontend Application

1. Install dependencies

   cd sentinel_frontend
   npm install

2. Start development server

   npm start  # Runs on port 3000 with hot reload

Configuration

All configuration is centralized in sentinel_backend/config/settings.py:

from config.settings import get_settings, get_service_settings
# Get configuration
settings = get_settings()
service_settings = get_service_settings()
# Use configuration
database_url = settings.database.url
timeout = service_settings.service_timeout

Environment Variables: All settings can be overridden with SENTINEL_* prefix:

export SENTINEL_DB_URL="postgresql+asyncpg://user:pass@host/db"
export SENTINEL_APP_LOG_LEVEL="DEBUG"
export SENTINEL_SECURITY_JWT_SECRET_KEY="your-secret-key"

Database Management

make init-db       # Initialize or repair database
make reset-db      # Complete reset (WARNING: data loss)
make backup-db     # Backup to timestamped file
make restore-db    # Restore from backup

Useful Commands

make help          # Show all available commands
make start         # Start all services
make stop          # Stop all services
make restart       # Restart services
make status        # Check service health
make logs          # View service logs
make clean         # Clean up containers and volumes

🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Quick Start

1. Fork the repository and clone your fork

   git clone https://github.com/YOUR_USERNAME/sentinel-api-testing.git
   cd sentinel-api-testing

2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes

   • Follow the project's coding standards
   • Write tests for new features
   • Update documentation as needed

4. Run tests

   cd sentinel_backend
   ./run_tests.sh -d

5. Commit and push

   git add .
   git commit -m "feat: add your feature description"
   git push origin feature/your-feature-name

6. Create a Pull Request

   • Go to the repository on GitHub
   • Click "New Pull Request"
   • Select your branch
   • Fill in the PR template

Development Guidelines

• Code Style: Follow PEP 8 for Python, ESLint for JavaScript/React
• Testing: Maintain 90%+ test coverage for new code
• Documentation: Update relevant docs for new features
• Commits: Use conventional commits (feat:, fix:, docs:, etc.)

Resources

• Contributing Guide - Detailed contribution instructions
• Code of Conduct - Community standards
• Development Setup - Technical documentation

Report Issues

• Report a Bug
• Request a Feature

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

📚 Documentation

• Complete Documentation - Full documentation portal
• FAQ - Frequently asked questions
• Troubleshooting Guide - Common issues and solutions

💬 Community

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas

🔧 Common Issues

# Fix database issues
make init-db
# Or complete reset
make reset-db

# Check service status
make status
# View logs for errors
make logs
# Restart all services
make restart

# Ensure backend is running
make status
# Check frontend logs
docker-compose logs frontend
# Restart frontend
docker-compose restart frontend

• Ensure target API URL is valid (starts with http:// or https://)
• Check target API is accessible: curl http://your-api-url
• Verify test suite has test cases assigned

📧 Contact

For additional support or questions:

• Open an issue on GitHub
• Check our documentation