# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Overview
This is a local testing agent MCP server that automates test discovery, generation, and execution for multi-language projects. The project provides MCP tools for Claude to scan repositories, generate unit tests, run test suites, and produce coverage reports.
**Supported Languages**: Python, JavaScript/TypeScript, Go, Rust, Java, Ruby
**Test Coverage**: 91% (120 tests passing)
**Quality**: Production-ready with comprehensive test suite
## Architecture
### Two Main Entry Points
1. **testing_agent.py** - Phase 2 MCP server (latest version)
- Provides four MCP tools: `scan_repository`, `run_all_tests`, `run_all_tests_parallel`, `full_phase2_pipeline`
- **New in Session 4**: Parallel test execution with configurable concurrency
- Detects source and test files for 6 languages:
- **Python**: `*.py` files, pytest framework
- **JavaScript/TypeScript**: `*.js`, `*.jsx`, `*.ts`, `*.tsx` files, jest framework
- **Go**: `*.go` files, `go test` framework
- **Rust**: `*.rs` files, `cargo test` framework
- **Java**: `*.java` files, Maven/Gradle test frameworks
- **Ruby**: `*.rb` files, RSpec/Minitest frameworks
- Generates AI test plans and coverage maps
- Runs language-specific test suites automatically
- Outputs: `.mcp_scan_snapshot.json`, `.mcp_test_report.json`, `TEST_COVERAGE_MAP.md`, `TEST_PLAN_AI.md`
2. **testing_engine/** - Phase 1 implementation (older version)
- Python package with modular components
- `file_scanner.py`: Discovers Python source files, excluding venvs and cache dirs
- `unit_test_generator.py`: Auto-generates pytest stubs by parsing AST for public functions/methods
- `pipeline.py`: Orchestrates scanning → generation → pytest execution with coverage
- Outputs to `.mcp/test_output.log`
### Key Differences
- **Phase 2** (testing_agent.py): Multi-language support (6 languages), language-specific test framework execution, structured JSON reports, comprehensive detection patterns
- **Phase 1** (testing_engine/): Python-only, always generates tests, simpler pipeline
## Development Commands
### Running Tests
```bash
# Activate virtual environment first
source .venv/bin/activate
# Run all tests (note: pytest-cov not installed, so remove --cov flags)
pytest
# Run specific test file
pytest tests/unit/test_testing_agent.py
# Run with verbose output
pytest -v
# Run specific test directory
pytest tests/unit/
pytest tests/integration/
```
### MCP Server Execution
```bash
# Run Phase 2 MCP server
python testing_agent.py
# The MCP server exposes four tools:
# - scan_repository(project_root=".") - Scan and detect languages only
# - run_all_tests(project_root=".") - Scan, plan, and run tests sequentially
# - run_all_tests_parallel(project_root=".", max_workers=4) - Scan, plan, and run tests in parallel
# - full_phase2_pipeline(project_root=".") - Alias for run_all_tests
```
### Parallel Test Execution (New in Session 4)
The `run_all_tests_parallel` tool executes tests for different languages concurrently:
```python
# Execute tests with default parallelism (4 workers)
run_all_tests_parallel(project_root=".")
# Execute tests with custom parallelism (e.g., 8 workers)
run_all_tests_parallel(project_root=".", max_workers=8)
```
**Benefits:**
- Faster test execution for multi-language projects
- Configurable concurrency to match system resources
- Same output format as sequential execution
- Gracefully handles skipped and failed tests
### Testing the Pipeline
```bash
# The test_script.sh validates the testing_engine package structure and imports
./test_script.sh
```
## Important Patterns
### File Exclusions
Both Phase 1 and 2 exclude these directories when scanning:
- **Virtual Environments**: `.venv`, `venv`, `site-packages`
- **Version Control**: `.git`
- **Build Artifacts**: `dist`, `build`, `out`
- **Caches**: `__pycache__`, `.cache`, `.pytest_cache`, `.playwright`, `coverage`
- **IDE/Editor**: `.vscode`, `.idea`
- **Framework Specific**: `node_modules`, `.next`, `.turbo`, `.mcp`
### Test File Detection (Updated Dec 2025)
The detector now uses comprehensive patterns to find test files across all supported languages:
**Python tests**:
- Files starting with `test_` (e.g., `test_auth.py`)
- Files ending with `_test.py` (e.g., `auth_test.py`)
- Files in `tests/` or `__tests__/` directories
- Test framework: **pytest**
**JavaScript/TypeScript tests**:
- Files ending with `.test.js`, `.test.jsx`, `.test.ts`, `.test.tsx`
- Files ending with `.spec.js`, `.spec.jsx`, `.spec.ts`, `.spec.tsx`
- Files in `tests/` or `__tests__/` directories
- Test framework: **jest**
**Go tests**:
- Files ending with `_test.go` (standard Go convention)
- Test framework: **go test**
**Rust tests**:
- Files ending with `_test.rs`
- Files in `tests/` or `test/` directories
- Test framework: **cargo test**
**Java tests**:
- Files ending with `Test.java` or `Tests.java`
- Files in `test/` or `tests/` directories
- Test frameworks: **Maven** (`mvn test`) or **Gradle** (`gradle test`)
**Ruby tests**:
- Files ending with `_test.rb` (Minitest convention)
- Files ending with `_spec.rb` (RSpec convention)
- Files in `test/`, `tests/`, or `spec/` directories
- Test frameworks: **RSpec** or **Minitest**
This ensures all test files are detected regardless of project structure conventions.
### Test File Naming
- Generated test files go to `tests/unit/`
- Naming convention: source `foo/bar.py` → test `tests/unit/test_foo_bar.py`
- Auto-generated tests include header comment to prevent manual edits
### AST Parsing Logic
The unit_test_generator extracts public API by:
- Finding top-level functions that don't start with `_`
- Finding classes with public methods (not starting with `_`)
- Generating pytest stubs that skip by default (Phase 1) or assert not None (file mcp_generate_unit_tests)
### Test Execution Policy (Updated Dec 2025)
**Thresholds Removed**: Tests now run as long as test files exist, regardless of count.
Skipped only when:
- No source files detected (language not present in project)
- No test files found (nothing to execute)
This ensures tests always run when they exist, providing useful feedback even for minimal test suites.
## Configuration
### Gravity (Google Antigravity) Integration
The MCP server is configured for Gravity at `~/.gemini/antigravity/mcp_config.json`:
```json
{
"mcpServers": {
"local-testing-agent": {
"command": "/Users/marcelkurvers/Development/local-testing-agent/.venv/bin/python",
"args": [
"/Users/marcelkurvers/Development/local-testing-agent/testing_agent.py"
],
"env": {}
}
}
}
```
After modifying this file, completely restart Gravity to register the MCP server.
### Claude Code Integration
Claude Code auto-discovers MCP servers. The server should appear in the MCP Servers list with four tools:
- `scan_repository` - Detect languages and scan files
- `run_all_tests` - Run tests sequentially
- `run_all_tests_parallel` - Run tests in parallel (NEW)
- `full_phase2_pipeline` - Full pipeline alias
## Dependencies
Install with: `pip install -r requirements.txt`
- `mcp[cli]` - MCP server framework
- `pytest` - Test framework
- `playwright` - Browser automation (likely for future e2e tests)
Note: `pytest-cov` is referenced in pipeline.py but not in requirements.txt. Remove `--cov` flags if coverage reporting is not needed.
## File Structure Context
```
/
├── testing_agent.py # Phase 2 MCP server (primary)
├── testing_engine/ # Phase 1 package (legacy)
│ ├── file_scanner.py
│ ├── unit_test_generator.py
│ └── pipeline.py
├── tests/
│ ├── unit/ # Auto-generated unit tests
│ ├── integration/ # (empty placeholder)
│ ├── e2e/ # (empty placeholder)
│ └── snapshots/ # (empty placeholder)
├── .mcp/ # Output directory for test logs
└── mcp_generate_unit_tests # Standalone unit test generator script
```
## Testing Strategy
The agent creates test folder structure automatically:
- `tests/unit/` for unit tests
- `tests/integration/` for integration tests
- `tests/e2e/` for end-to-end tests
- `tests/snapshots/` for snapshot tests
Only `tests/unit/` is actively used by the auto-generation system.
