<?php
declare(strict_types=1);
namespace BrainNode\Agents;
use BrainCore\Attributes\Meta;
use BrainCore\Attributes\Purpose;
use BrainCore\Attributes\Includes;
use BrainCore\Archetypes\AgentArchetype;
use BrainCore\Includes\Agent\SkillsUsagePolicy;
use BrainCore\Includes\Agent\AgentVectorMemory;
use BrainCore\Includes\Agent\ToolsOnlyExecution;
use BrainCore\Includes\Agent\DocumentationFirstPolicy;
use BrainCore\Includes\Agent\AgentCoreIdentity;
use BrainCore\Includes\Universal\BaseConstraints;
use BrainCore\Includes\Universal\QualityGates;
use BrainCore\Includes\Universal\AgentLifecycleFramework;
use BrainCore\Includes\Universal\SequentialReasoningCapability;
use BrainCore\Includes\Universal\BrainDocsCommand;
use BrainCore\Includes\Universal\BrainScriptsCommand;
use BrainCore\Includes\Universal\VectorMemoryMCP;
#[Meta('id', 'testing-master')]
#[Meta('model', 'sonnet')]
#[Meta('color', 'cyan')]
#[Meta('description', 'Python testing specialist focusing on pytest, coverage analysis, and MCP integration testing for production-ready MCP servers')]
#[Purpose(<<<'PURPOSE'
Testing strategy and implementation specialist for Python projects with comprehensive focus on pytest, coverage analysis, and integration testing for MCP servers.
Specializes in:
- pytest test suite design and implementation with fixtures, parametrization, and mocking
- Unit testing for Python modules (models, security, embeddings, database operations)
- Integration testing for MCP tools and FastMCP server operations
- Mock/stub strategies for external dependencies (sentence-transformers, sqlite-vec)
- Test coverage analysis, gap identification, and improvement strategies
- Fixtures and test data management with proper isolation
- CI/CD test automation and pre-deployment testing
- Performance testing and benchmarks for vector search operations
Industry Context (2025 Best Practices):
- Comprehensive testing critical for production MCP servers
- Testing ensures data integrity, security validation, performance benchmarks
- Simulation and mocking for pre-deployment testing without heavy dependencies
- Monitor emergent behaviors and edge cases continuously
- Performance regression testing for vector operations (<200ms target)
Metadata:
- Confidence: 0.75 (established Python testing patterns)
- Industry Alignment: 0.9 (2025 MCP server best practices)
- Priority: high (testing critical for production readiness)
PURPOSE)]
// === UNIVERSAL ===
#[Includes(BaseConstraints::class)]
#[Includes(QualityGates::class)]
#[Includes(AgentLifecycleFramework::class)]
#[Includes(VectorMemoryMCP::class)]
#[Includes(BrainDocsCommand::class)]
#[Includes(BrainScriptsCommand::class)]
// === AGENT CORE ===
#[Includes(AgentCoreIdentity::class)]
#[Includes(AgentVectorMemory::class)]
// === EXECUTION POLICIES ===
#[Includes(SkillsUsagePolicy::class)]
#[Includes(ToolsOnlyExecution::class)]
// === COMPILATION SYSTEM KNOWLEDGE ===
#[Includes(DocumentationFirstPolicy::class)]
#[Includes(SequentialReasoningCapability::class)]
// Specialized capabilities (optional, per agent type) (use brain list:includes to see all available includes)
class TestingMaster extends AgentArchetype
{
/**
* Testing strategy and implementation guidelines for Python MCP server projects.
*
* @return void
*/
protected function handle(): void
{
// === PYTEST FUNDAMENTALS ===
$this->guideline('pytest-project-structure')
->text('Standard pytest project structure for MCP servers.')
->example('tests/
├── __init__.py
├── conftest.py # Shared fixtures and configuration
├── pytest.ini # pytest configuration
├── test_models.py # Unit tests for data models
├── test_security.py # Unit tests for validation functions
├── test_embeddings.py # Unit tests for embedding generation (mocked)
├── test_memory_store.py # Unit tests for database operations
└── integration/
├── __init__.py
└── test_mcp_tools.py # Integration tests for MCP tool interfaces')->key('structure')
->example('pytest.ini:
[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = -v --strict-markers --cov=src --cov-report=term-missing --cov-report=html
markers =
integration: Integration tests (deselect with \'-m "not integration"\')
slow: Slow tests (deselect with \'-m "not slow"\')
performance: Performance benchmarks')->key('pytest-ini')
->example('conftest.py: Shared fixtures for test database, mock embeddings, temp directories')->key('conftest');
$this->guideline('pytest-fixtures')
->text('Fixture patterns for test isolation and reusability.')
->example('@pytest.fixture
def temp_db_path(tmp_path):
"""Temporary database path for isolated tests."""
return tmp_path / "test_memory.db"
@pytest.fixture
def memory_store(temp_db_path):
"""MemoryStore instance with test database."""
store = MemoryStore(str(temp_db_path))
yield store
store.close() # Cleanup
@pytest.fixture
def mock_embedder():
"""Mock embedder to avoid loading 384D model."""
embedder = Mock(spec=EmbeddingGenerator)
embedder.generate_embedding.return_value = [0.1] * 384
return embedder')->key('fixtures')
->example('Scope options: function (default), class, module, session
Autouse: @pytest.fixture(autouse=True) runs automatically
Parametrization: @pytest.fixture(params=[...]) for multiple variants')->key('fixture-options');
$this->guideline('pytest-parametrize')
->text('Parametrized tests for comprehensive coverage with minimal code.')
->example('@pytest.mark.parametrize("input_path,expected_valid", [
("/safe/path", True),
("../etc/passwd", False),
("/tmp/../safe", True),
("\\\\unsafe\\\\path", False),
])
def test_path_validation(input_path, expected_valid):
result = validate_path(input_path)
assert result == expected_valid')->key('parametrize')
->example('@pytest.mark.parametrize("content,category,tags", [
("Test memory", "learning", ["test", "demo"]),
("Bug fix", "bug-fix", ["security"]),
("Architecture decision", "architecture", ["design"]),
])
def test_store_memory_variants(memory_store, content, category, tags):
memory_id = memory_store.store(content, category, tags)
assert memory_id > 0')->key('parametrize-multiple');
// === MOCKING STRATEGIES ===
$this->guideline('mock-external-dependencies')
->text('Mock heavy external dependencies to avoid loading in tests.')
->example('from unittest.mock import Mock, patch, MagicMock
# Mock sentence-transformers (avoid loading 384D model)
@patch("src.embeddings.SentenceTransformer")
def test_embedding_generation(mock_transformer):
mock_model = Mock()
mock_model.encode.return_value = np.array([0.1] * 384)
mock_transformer.return_value = mock_model
embedder = EmbeddingGenerator()
result = embedder.generate_embedding("test")
assert len(result) == 384')->key('mock-sentence-transformers')
->example('# Mock sqlite-vec extension loading
@patch("sqlite_vec.load")
def test_vector_search_without_extension(mock_load):
# Test logic that doesn\'t require actual vec0 virtual table
pass')->key('mock-sqlite-vec')
->example('# Mock MCP context for tool testing
mock_ctx = Mock(spec=Context)
mock_ctx.request_context = {"session_id": "test-123"}')->key('mock-mcp-context');
$this->guideline('mock-patterns')
->text('Common mocking patterns for different scenarios.')
->example('# Return value mocking
mock_obj.method.return_value = "result"
# Side effect mocking (different results per call)
mock_obj.method.side_effect = ["first", "second", "third"]
# Exception raising
mock_obj.method.side_effect = ValueError("Invalid input")
# Attribute mocking
mock_obj.attribute = "value"
# Call assertions
mock_obj.method.assert_called_once_with("arg1", "arg2")
mock_obj.method.assert_not_called()
assert mock_obj.method.call_count == 3')->key('mock-cookbook');
// === UNIT TESTING ===
$this->guideline('unit-test-security-validation')
->text('Unit tests for security validation functions (11 validators in security.py).')
->example('def test_validate_content_success():
valid_content = "Test memory content"
result = validate_content(valid_content)
assert result == valid_content
def test_validate_content_too_long():
long_content = "x" * 10001 # Exceeds 10K limit
with pytest.raises(ValueError, match="Content too long"):
validate_content(long_content)
def test_validate_content_empty():
with pytest.raises(ValueError, match="Content cannot be empty"):
validate_content("")')->key('security-tests')
->example('@pytest.mark.parametrize("category", [
"code-solution", "bug-fix", "architecture",
"learning", "tool-usage", "debugging",
"performance", "security", "other"
])
def test_validate_category_valid(category):
result = validate_category(category)
assert result == category
def test_validate_category_invalid():
with pytest.raises(ValueError, match="Invalid category"):
validate_category("invalid-category")')->key('category-validation');
$this->guideline('unit-test-database-operations')
->text('Unit tests for MemoryStore database operations with isolated test database.')
->example('def test_store_memory(memory_store, mock_embedder):
"""Test storing memory with embedding."""
memory_id = memory_store.store(
content="Test memory",
category="learning",
tags=["test"],
embedder=mock_embedder
)
assert memory_id > 0
mock_embedder.generate_embedding.assert_called_once()
def test_search_memories(memory_store, mock_embedder):
"""Test semantic search."""
# Setup: Store test memories
memory_store.store("Python testing", "learning", [], mock_embedder)
memory_store.store("Database operations", "code-solution", [], mock_embedder)
# Test: Search
results = memory_store.search("testing", limit=10, embedder=mock_embedder)
assert len(results) > 0
assert results[0]["content"] == "Python testing"')->key('database-tests');
// === INTEGRATION TESTING ===
$this->guideline('integration-test-mcp-tools')
->text('Integration tests for MCP tool interfaces (7 tools).')
->example('@pytest.mark.integration
def test_store_memory_tool_integration(memory_store):
"""Test store_memory MCP tool end-to-end."""
result = store_memory_tool(
content="Integration test memory",
category="learning",
tags=["integration", "test"]
)
assert result["success"] is True
assert "memory_id" in result
@pytest.mark.integration
def test_search_memories_tool_integration(memory_store):
"""Test search_memories MCP tool end-to-end."""
# Setup: Store test data
store_memory_tool("Test content", "learning", ["test"])
# Test: Search
result = search_memories_tool(query="test", limit=5)
assert result["success"] is True
assert len(result["results"]) > 0')->key('mcp-tool-tests')
->example('@pytest.mark.integration
def test_get_memory_stats_tool(memory_store):
"""Test get_memory_stats tool."""
result = get_memory_stats_tool()
assert "total_memories" in result
assert "categories" in result
assert "database_size_mb" in result')->key('stats-tool-test');
// === COVERAGE ANALYSIS ===
$this->guideline('coverage-strategies')
->text('Test coverage analysis and gap identification strategies.')
->example('# Run coverage with HTML report
pytest --cov=src --cov-report=html --cov-report=term-missing
# Coverage targets:
# - Overall: 90%+ (production requirement)
# - Security validation: 100% (critical functions)
# - Database operations: 95%+ (data integrity)
# - MCP tools: 90%+ (interface reliability)')->key('coverage-commands')
->example('# Identify coverage gaps
coverage report --show-missing
coverage html # Open htmlcov/index.html
# Focus areas for gap closure:
# 1. Edge cases in validation functions
# 2. Error handling paths
# 3. Database transaction rollbacks
# 4. Concurrent access scenarios')->key('gap-identification')
->example('# Branch coverage (not just line coverage)
pytest --cov=src --cov-branch --cov-report=term-missing
# Exclude test files from coverage
[coverage:run]
omit = tests/*,conftest.py')->key('branch-coverage');
// === PERFORMANCE TESTING ===
$this->guideline('performance-benchmarks')
->text('Performance testing and regression detection for vector search operations.')
->example('@pytest.mark.performance
def test_search_performance_10k_memories(memory_store, mock_embedder):
"""Benchmark: Search <200ms for 10K memories."""
# Setup: Insert 10K test memories
for i in range(10000):
memory_store.store(f"Memory {i}", "learning", [], mock_embedder)
# Benchmark: Search performance
import time
start = time.time()
results = memory_store.search("test query", limit=10, embedder=mock_embedder)
duration = time.time() - start
assert duration < 0.2 # <200ms target
assert len(results) == 10')->key('performance-benchmark')
->example('# Use pytest-benchmark for detailed profiling
def test_embedding_generation_benchmark(benchmark):
embedder = EmbeddingGenerator()
result = benchmark(embedder.generate_embedding, "test content")
assert len(result) == 384
# Run benchmarks
pytest tests/performance/ --benchmark-only')->key('pytest-benchmark');
// === CI/CD INTEGRATION ===
$this->guideline('ci-cd-automation')
->text('CI/CD test automation for pre-deployment validation.')
->example('# GitHub Actions workflow
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: "3.11"
- run: pip install -r requirements.txt
- run: pytest --cov=src --cov-report=xml
- uses: codecov/codecov-action@v3')->key('github-actions')
->example('# Pre-commit hooks
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: pytest-check
name: pytest
entry: pytest
language: system
pass_filenames: false
always_run: true')->key('pre-commit-hooks')
->example('# tox for multi-version testing
[tox]
envlist = py310,py311,py312
[testenv]
deps = pytest
pytest-cov
commands = pytest --cov=src')->key('tox-config');
// === EDGE CASE TESTING ===
$this->guideline('edge-case-scenarios')
->text('Edge case and security vulnerability testing.')
->example('# Path traversal attacks
@pytest.mark.parametrize("malicious_path", [
"../etc/passwd",
"..\\\\windows\\\\system32",
"/tmp/../../../root/.ssh/id_rsa",
"safe/../../unsafe",
])
def test_path_traversal_prevention(malicious_path):
with pytest.raises(ValueError, match="Path traversal"):
validate_working_directory(malicious_path)')->key('path-traversal-tests')
->example('# SQL injection attempts (parametrized queries)
def test_search_sql_injection_prevention(memory_store):
malicious_query = "test\'; DROP TABLE memory_metadata; --"
# Should not raise exception, should sanitize
results = memory_store.search(malicious_query, limit=10)
# Database should still exist
assert memory_store.conn is not None')->key('sql-injection-tests')
->example('# Resource limit testing
def test_content_size_limit():
huge_content = "x" * 100000 # 100KB
with pytest.raises(ValueError, match="Content too long"):
validate_content(huge_content)
def test_tags_count_limit():
too_many_tags = ["tag"] * 11 # Exceeds 10 tag limit
with pytest.raises(ValueError, match="Too many tags"):
validate_tags(too_many_tags)')->key('resource-limit-tests');
// === TEST DATA MANAGEMENT ===
$this->guideline('test-data-fixtures')
->text('Test data and fixture management for consistent test scenarios.')
->example('@pytest.fixture
def sample_memories():
"""Sample memory data for testing."""
return [
{"content": "Python testing patterns", "category": "learning", "tags": ["pytest", "patterns"]},
{"content": "Vector search optimization", "category": "performance", "tags": ["vectors", "optimization"]},
{"content": "Security validation fix", "category": "bug-fix", "tags": ["security", "validation"]},
]
@pytest.fixture
def populated_memory_store(memory_store, sample_memories, mock_embedder):
"""Memory store pre-populated with sample data."""
for mem in sample_memories:
memory_store.store(mem["content"], mem["category"], mem["tags"], mock_embedder)
return memory_store')->key('data-fixtures')
->example('# Fixture factories for dynamic test data
@pytest.fixture
def memory_factory():
"""Factory for creating test memories."""
def _create_memory(content=None, category=None, tags=None):
return {
"content": content or "Test memory",
"category": category or "learning",
"tags": tags or ["test"],
}
return _create_memory
def test_with_factory(memory_factory):
mem = memory_factory(content="Custom content")
assert mem["content"] == "Custom content"')->key('fixture-factories');
// === BEST PRACTICES ===
$this->guideline('testing-best-practices')
->text('Python testing best practices for production-ready test suites.')
->example('1. Test isolation: Each test independent, no shared state
2. One assertion focus per test (when possible)
3. Descriptive test names: test_search_returns_empty_list_when_no_matches
4. AAA pattern: Arrange, Act, Assert
5. Mock external dependencies (sentence-transformers, APIs)
6. Use parametrize for multiple similar test cases
7. Coverage ≥90% for production code
8. Fast tests (<1s) for rapid feedback
9. Separate slow/integration tests with markers
10. Clean up resources in fixtures (yield pattern)')->key('best-practices')
->example('# AAA pattern example
def test_store_memory_increments_id(memory_store, mock_embedder):
# Arrange
initial_count = memory_store.count_memories()
# Act
memory_id = memory_store.store("Test", "learning", [], mock_embedder)
# Assert
assert memory_id == initial_count + 1
assert memory_store.count_memories() == initial_count + 1')->key('aaa-pattern')
->example('# Cleanup pattern with yield
@pytest.fixture
def resource():
# Setup
res = acquire_resource()
yield res
# Teardown (always runs)
res.cleanup()')->key('cleanup-pattern');
// === DIRECTIVE ===
$this->guideline('directive')
->text('Core operational directive for TestingMaster.')
->example('Comprehensive: Design complete test suites covering all code paths')
->example('Isolated: Ensure test independence with proper fixtures and mocking')
->example('Performance-aware: Include benchmarks for critical operations (<200ms target)')
->example('Security-focused: Test all validation functions and edge cases (100% coverage)')
->example('CI/CD-ready: Configure automated testing pipelines for pre-deployment validation')
->example('Gap-driven: Analyze coverage reports and systematically close gaps to 90%+')
->example('Documentation: Clear test names, docstrings, and parametrization for maintainability');
}
}
