# AGENTS.md - Testing Guide for AI Coding Agents
This guide helps AI coding agents run tests for RivalSearchMCP tools efficiently.
## Quick Start
### Test Individual Tools (RECOMMENDED)
Test one tool at a time for focused debugging:
```bash
# Navigate to project root
cd /Users/damionrashford/mcp-expert/servers/RivalSearchMCP
# Test individual tools (run these ONE AT A TIME)
uv run python tests/tools/test_multi_search.py
uv run python tests/tools/test_trends_core.py
uv run python tests/tools/test_trends_export.py
uv run python tests/tools/test_content_operations.py
uv run python tests/tools/test_traverse_website.py
uv run python tests/tools/test_research_topic.py
uv run python tests/tools/test_scientific_research.py
uv run python tests/tools/test_research_workflow.py
```
## Test Structure
```
tests/
├── AGENTS.md # This file
├── mcp_client.py # Reusable MCP client
├── run.py # Helper runner (optional)
└── tools/ # Individual test files
├── test_multi_search.py # Tests multi_search tool
├── test_trends_core.py # Tests trends_core tool
├── test_trends_export.py # Tests trends_export tool
├── test_content_operations.py # Tests content_operations tool
├── test_traverse_website.py # Tests traverse_website tool
├── test_research_topic.py # Tests research_topic tool
├── test_scientific_research.py # Tests scientific_research tool
└── test_research_workflow.py # Tests research_workflow tool
```
## How Tests Work
### 1. MCP Client (`mcp_client.py`)
This file provides a reusable `create_client()` function:
```python
from tests.mcp_client import create_client
async with create_client() as client:
result = await client.call_tool("multi_search", {"query": "Python"})
print(result.content[0].text)
```
### 2. Individual Test Files
Each test file:
- Tests ONE tool comprehensively
- Tests ALL parameters for that tool
- Uses real websites (not example.com)
- Has clear assertions (no cheating!)
- Runs independently with `uv run python tests/tools/test_<tool>.py`
### 3. Simple Execution Model
**No pytest** - Just plain `asyncio.run()`:
```python
async def test_something():
async with create_client() as client:
result = await client.call_tool(...)
assert len(result.content[0].text) > 500
print("✅ Test passed")
if __name__ == "__main__":
asyncio.run(test_something())
```
## For AI Coding Agents
### When User Asks: "Test the tools"
**DO THIS:**
1. Test ONE tool at a time
2. Run: `uv run python tests/tools/test_<tool_name>.py`
3. Read the output carefully
4. If test fails, fix the tool's source code
5. Re-run the same test
6. Move to next tool only when current one passes
**DON'T DO THIS:**
- ❌ Run all tests at once
- ❌ Skip tests that take time
- ❌ Assume tests pass without running them
- ❌ Run tests in parallel
### Example Workflow
```bash
# Test multi_search
cd /Users/damionrashford/mcp-expert/servers/RivalSearchMCP
uv run python tests/tools/test_multi_search.py
# If it passes, move to next tool
uv run python tests/tools/test_trends_core.py
# If it fails, fix the source code, then re-test
# Fix: src/tools/trends.py
uv run python tests/tools/test_trends_core.py # Re-run same test
```
### Reading Test Output
**Successful test:**
```
✅ Default params test passed - 523 chars
✅ num_results=3 test passed
✅ extract_content flag test passed
✅ use_fallback test passed
✅ Quality test passed - 1247 chars
✅ All multi_search tests passed!
```
**Failed test:**
```
Traceback (most recent call last):
...
AssertionError: Search results too short: 234 chars (expected >500)
```
### Understanding Test Coverage
Each test file tests **ALL parameters**:
- **test_multi_search.py** (5 tests)
- query, num_results, extract_content, follow_links, max_depth, use_fallback
- **test_trends_core.py** (6 tests)
- operation (search/related/regional/compare), keywords, timeframe, geo, resolution
- **test_trends_export.py** (6 tests)
- keywords, format (csv/json/sql), timeframe, filename
- **test_content_operations.py** (10 tests)
- operation (retrieve/stream/analyze/extract), url, content, extraction_method, analysis_type, link_type
- **test_traverse_website.py** (7 tests)
- url, mode (research/docs/map), max_pages, max_depth, generate_llms_txt
- **test_research_topic.py** (6 tests)
- topic, sources, max_sources, include_analysis
- **test_scientific_research.py** (9 tests)
- operation (academic_search/dataset_discovery), query, max_results, sources, categories
- **test_research_workflow.py** (10 tests)
- topic, max_sources, include_trends, include_website_analysis, research_depth, ai_model, enable_ai_insights
**Total: 59 test functions across 8 tools**
## Troubleshooting
### "ModuleNotFoundError: No module named 'fastmcp'"
```bash
cd /Users/damionrashford/mcp-expert/servers/RivalSearchMCP
uv sync
```
### "No module named 'tests'"
Make sure you're running from the project root:
```bash
cd /Users/damionrashford/mcp-expert/servers/RivalSearchMCP
uv run python tests/tools/test_multi_search.py
```
### Tests hang or timeout
- Tests make real network requests (search engines, websites)
- Some tests may take 10-30 seconds
- If a test hangs >60 seconds, interrupt and investigate
### "AssertionError: Output too short"
This means the tool isn't returning quality content. Fix the tool's source code in `src/tools/<tool_name>.py`.
## Best Practices for Agents
1. **Always test after making changes**
- Modified `src/tools/trends.py`? → Run `tests/tools/test_trends_core.py`
- Modified `src/tools/analysis.py`? → Run `tests/tools/test_content_operations.py`
2. **Test individual tools, not all at once**
- Easier to debug
- Faster feedback loop
- Can run in any order
3. **Read test output carefully**
- Look for specific assertion messages
- Check character counts (many tests verify content length)
- Review error traces to find root cause
4. **Don't modify tests to make them pass**
- Tests are correct
- If test fails, fix the TOOL, not the TEST
- Tests ensure quality content, not just "no errors"
5. **UV commands**
```bash
uv sync # Install dependencies
uv run <command> # Run in UV environment
uv add <package> # Add dependency
```
## Test Quality Standards
Each test verifies:
- ✅ Tool executes without errors
- ✅ Returns content meeting minimum length (e.g., >500 chars)
- ✅ Contains expected data structures (URLs, markdown, etc.)
- ✅ Matches tool's stated purpose
**These are REAL tests** - they will fail if tools are broken!
## Summary
**For agents:**
- Test one tool at a time: `uv run python tests/tools/test_<tool>.py`
- Fix issues immediately when tests fail
- Re-run same test after fixing
- Move to next tool only when current passes
**Files:**
- `mcp_client.py` - Reusable MCP client
- `tools/test_*.py` - 8 comprehensive test files (59 tests total)
- `run.py` - Optional helper
**Remember:** Test individually, fix iteratively, verify thoroughly!
