Automated Self-Healing for Java REST API Tests using Gemini AI
Features • Architecture • Installation • Usage • Examples
The REST Assured Self-Healing MCP Agent is an intelligent automation tool that automatically diagnoses and fixes scripting issues in Java-based REST API test frameworks (RestAssured + TestNG). It leverages Google's Gemini AI to analyze test failures, generate precise code fixes, and verify repairs—all within an isolated Docker environment.
- ⏱️ Save Time: Automatically fix common test failures without manual intervention
- 🔒 Safe: Runs in isolated Docker containers with automatic rollback on failure
- 🧠 Smart: Uses Gemini AI to understand context and generate precise fixes
- 🔄 Iterative: Automatically retries tests after applying fixes (up to 3 attempts)
- 📊 Enterprise-Ready: Handles complex multi-module projects with deep package hierarchies
- ✅ Docker Isolation: Runs tests in clean, ephemeral containers (
eclipse-temurin:17) - ✅ Smart Diagnosis: Distinguishes between scripting issues and system issues
- ✅ Generative Repair: Uses Gemini 2.0 Flash to analyze code and generate Git patches
- ✅ Auto-Verification: Applies patches and re-runs tests automatically
- ✅ Safety First: Reverts changes if patches fail or cause more issues
- ✅ Dual Patch Strategy: Git apply with direct file replacement fallback
Stop worrying about AI breaking your master branch. 🛡️
The agent acts like a responsible developer on your team. When it finds a fix, it follows a strict enterprise workflow:
- Creates a Feature Branch:
fix/self-healing-<test-name>-<timestamp> - Applies the Fix: Safely patches the code in isolation.
- Verifies the Fix: Runs the tests again to ensure it works.
- Pushes & Creates PR: Automatically opens a clear, descriptive Pull Request on GitHub.
You stay in control. You review the PR, approve the changes, and merge when ready. 🤝
The agent can diagnose and fix:
| Failure Type | Example | Fix Strategy |
|---|---|---|
| AssertionError | Status code mismatch (expected 200, got 404) | Update assertion values |
| NullPointerException | Accessing null object | Add null checks |
| NoSuchElementException | Incorrect locators | Update selectors |
| TimeoutException | Insufficient wait times | Increase timeouts |
| JsonParseException | DTO field mismatches | Update DTO fields |
| ArrayIndexOutOfBoundsException | List access errors | Add bounds checks |
See EXAMPLES.md for detailed scenarios and fixes.
graph TB
User([User / CI Pipeline]) -->|1. Triggers| Agent[MCP Agent Orchestrator]
Agent -->|2. Mounts Repo| Docker[Docker Container<br/>eclipse-temurin:17]
Docker -->|3. Runs Tests| Tests[./gradlew test]
Tests -->|4. Produces| Artifacts[JUnit XML + Logs]
Artifacts -->|5. Analyzes| Analyzer[Failure Analyzer]
Analyzer -->|Scripting Issue?| Decision{Issue Type}
Decision -->|Yes| Gemini[Gemini 2.0 Flash API]
Decision -->|No| Stop([Stop: System Issue])
Gemini -->|6. Generates| Fix[Git Patch + Explanation]
Fix -->|7. Applies| Patcher[Patch Applier<br/>Dual Strategy]
Patcher -->|Strategy 1| GitApply[git apply --3way]
Patcher -->|Strategy 2<br/>Fallback| DirectReplace[Direct File Replacement]
GitApply -->|Success?| Verify{Patch Applied?}
DirectReplace -->|Success?| Verify
Verify -->|Yes| Agent
Verify -->|No| Revert[Revert Changes]
Revert --> Stop
Agent -->|8. Re-run Tests| Docker
Docker -->|Max 3 Attempts| Result([✓ Healed!])
style Gemini fill:#8E75B2
style Docker fill:#2496ED
style Result fill:#28a745
style Stop fill:#dc3545
classDiagram
class Main {
+main()
+orchestrate_repair_loop()
-max_attempts: int
}
class DockerManager {
+build_image()
+run_tests(repo_path, command)
+check_docker()
-image_name: str
}
class FailureAnalyzer {
+analyze(artifacts_path)
-_parse_xml()
-_classify_issue()
-_extract_stack_trace()
}
class GeminiClient {
+get_fix_suggestion(failure, code)
-_construct_prompt()
-_parse_response()
-api_key: str
-model: str
}
class PatchApplier {
+apply_patch(patch_content)
+revert_changes()
-_try_git_apply()
-_try_direct_replacement()
-_normalize_paths()
-_create_clean_snapshot()
}
class ConfigLoader {
+load_config()
-config_path: str
}
Main --> DockerManager : manages
Main --> FailureAnalyzer : uses
Main --> GeminiClient : calls
Main --> PatchApplier : uses
Main --> ConfigLoader : loads
GeminiClient --> FixSuggestion : returns
FailureAnalyzer --> FailureContext : returns
class FixSuggestion {
+explanation: str
+diff: str
+confidence: float
}
class FailureContext {
+test_class: str
+test_name: str
+failure_type: str
+message: str
+stack_trace: str
+is_scripting_issue: bool
}
sequenceDiagram
participant User
participant Agent as MCP Agent
participant Docker
participant Analyzer as Failure Analyzer
participant Gemini as Gemini API
participant Patcher as Patch Applier
User->>Agent: ./run_agent.sh --repo test-repo
Agent->>Docker: Build image (if needed)
loop Max 3 Attempts
Agent->>Docker: Run tests (./gradlew test)
Docker-->>Agent: Exit code + logs
alt Tests Pass
Agent-->>User: ✓ All tests passed!
else Tests Fail
Agent->>Analyzer: Analyze failures
Analyzer-->>Agent: Failure contexts
alt Scripting Issue
Agent->>Gemini: Send failure + code context
Gemini-->>Agent: Fix suggestion (patch + confidence)
alt Confidence >= 0.6
Agent->>Patcher: Apply patch
alt Git Apply Success
Patcher-->>Agent: ✓ Patch applied
else Git Apply Fails
Patcher->>Patcher: Try direct replacement
Patcher-->>Agent: ✓ Patch applied (fallback)
end
Agent->>Docker: Re-run tests
else Low Confidence
Agent-->>User: ⚠ Low confidence, skipping
end
else System Issue
Agent-->>User: ⚠ System issue detected, stopping
end
end
end
Agent-->>User: Final result
-
Docker: Must be installed and running
docker info # Verify Docker is running -
Python 3.8+: Installed on your system
python3 --version
-
Gemini API Key: Get your free key from Google AI Studio
-
Clone the Repository
git clone https://github.com/abhi9avx/rest-assured-self-healing-mcp.git cd rest-assured-self-healing-mcp -
Configure Environment
Create a
.envfile from the template:cp .env.example .env
Edit
.envand add your Gemini API key:GEMINI_API_KEY=your_actual_api_key_here
-
Install Python Dependencies
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt
-
Verify Installation
./run_agent.sh --help
Run the agent on your Java test repository:
./run_agent.sh --repo path/to/your/java/repo./run_agent.sh --repo rest-api-test-example --test-filter GetUserTest| Option | Description | Default |
|---|---|---|
--repo <path> |
Path to target repository | Required |
--config <path> |
Custom config file | config.yml |
--no-docker-build |
Skip Docker image rebuild | false |
--test-filter <name> |
Run specific test class/method | All tests |
max_attempts: 3 # Max repair attempts per run
good_confidence_threshold: 0.6 # Minimum confidence to apply fix
allowed_paths:
- src/test # Only allow changes in test directories
gemini_timeout_seconds: 60 # API timeoutrest-assured-self-healing-mcp/
├── .env.example # Environment template
├── .gitignore # Git ignore rules
├── config.yml # Agent configuration
├── run_agent.sh # Entry point script
├── Dockerfile.agent # Docker environment
├── requirements.txt # Python dependencies
├── EXAMPLES.md # Detailed usage examples
├── src/
│ ├── main.py # Orchestrator
│ ├── config_loader.py # Config management
│ ├── docker_manager.py # Docker operations
│ ├── failure_analyzer.py # Log parsing & classification
│ ├── gemini_client.py # Gemini API integration
│ └── patch_applier.py # Patch application (dual strategy)
└── rest-api-test-example/ # Sample test repository
├── src/test/java/ # Test files
└── build.gradle # Gradle config
- Test Execution: Runs your tests in a Docker container
- Failure Detection: Parses JUnit XML reports to identify failures
- Classification: Determines if failure is a scripting issue (fixable) or system issue
- AI Analysis: Sends failure context + code to Gemini for analysis
- Patch Generation: Gemini generates a Git-compatible patch
- Patch Application:
- Strategy 1: Try
git apply --3wayfor complex patches - Strategy 2: Fall back to direct file replacement for simple fixes
- Strategy 1: Try
- Verification: Re-runs tests to verify the fix
- Iteration: Repeats up to 3 times or until tests pass
- ✅
.envfile is gitignored by default - ✅ API keys are never committed to the repository
- ✅ Tests run in isolated Docker containers
- ✅ Changes are automatically reverted on failure
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Abhinav Kumar
- GitHub: @abhi9avx
- LinkedIn: Connect with me
- Google Gemini for the powerful AI capabilities
- RestAssured for the excellent API testing framework
- TestNG for the robust testing framework
⭐ Star this repo if you find it useful!
Made with ❤️ by Abhinav Kumar