Laravel MCP Companion

"""Integration tests for complete Laravel MCP Companion workflows.""" import pytest from unittest.mock import patch, MagicMock import laravel_mcp_companion from docs_updater import DocsUpdater @pytest.mark.integration class TestDocumentationWorkflows: """Test complete documentation workflows.""" def test_full_documentation_update_and_search_workflow(self, test_docs_dir): """Test complete workflow: update docs, then search and read.""" # Import standalone implementations from mcp_tools import ( list_laravel_docs_impl, search_laravel_docs_impl, read_laravel_doc_content_impl ) # Setup: Mock the updater to simulate successful update with patch('docs_updater.DocsUpdater') as mock_updater_class: mock_updater = MagicMock() mock_updater.needs_update.return_value = True mock_updater.update.return_value = True mock_updater_class.return_value = mock_updater # Mock metadata after update with patch('mcp_tools.get_laravel_docs_metadata') as mock_metadata: mock_metadata.return_value = { 'commit_sha': 'abc123def456', 'commit_date': '2024-01-01T12:00:00Z', 'commit_message': 'Update documentation' } # Step 1: Update documentation (simulate with DocsUpdater) updater = mock_updater update_result = updater.update(force=False) assert update_result is True # Step 2: List available documentation with patch('mcp_tools.os.listdir', return_value=['routing.md', 'eloquent.md']): list_result = list_laravel_docs_impl(test_docs_dir, "12.x") assert "routing.md" in list_result assert "eloquent.md" in list_result # Step 3: Search documentation with patch('mcp_tools.os.listdir', return_value=['routing.md']), \ patch('mcp_tools.get_file_content_cached', return_value="# Routing\n\nLaravel routing documentation."): search_result = search_laravel_docs_impl(test_docs_dir, "routing", "12.x") # TOON format: query and file paths assert "routing" in search_result assert "routing.md" in search_result # Step 4: Read specific documentation (test_docs_dir / "12.x" / "routing.md").write_text("# Routing\n\nDetailed routing info") read_result = read_laravel_doc_content_impl(test_docs_dir, "routing.md", "12.x") assert "# Routing" in read_result assert "Detailed routing info" in read_result def test_package_recommendation_workflow(self, sample_package_catalog): """Test complete package recommendation workflow.""" with patch.dict(laravel_mcp_companion.PACKAGE_CATALOG, sample_package_catalog): # Step 1: Get recommendations for a use case from laravel_mcp_companion import get_laravel_package_recommendations recommendations = get_laravel_package_recommendations("authentication for single page applications") # TOON format: package name and install command assert "Laravel Sanctum" in recommendations or "Sanctum" in recommendations assert "laravel/sanctum" in recommendations # Step 2: Get detailed info about specific package from laravel_mcp_companion import get_laravel_package_info package_info = get_laravel_package_info("laravel/sanctum") # TOON format: name and description fields assert "Sanctum" in package_info assert "authentication" in package_info.lower() # Step 3: Get packages by category from laravel_mcp_companion import get_laravel_package_categories category_packages = get_laravel_package_categories("authentication") assert "Laravel Sanctum" in category_packages # Step 4: Get implementation features from laravel_mcp_companion import get_features_for_laravel_package with patch.dict(laravel_mcp_companion.FEATURE_MAP, {'laravel/sanctum': ['spa-auth', 'api-tokens']}): features = get_features_for_laravel_package("laravel/sanctum") assert "spa-auth" in features assert "api-tokens" in features def test_external_documentation_workflow(self, test_external_docs_dir): """Test external documentation fetching and reading workflow.""" from docs_updater import ExternalDocsFetcher # Create an external docs fetcher external_fetcher = ExternalDocsFetcher(test_external_docs_dir.parent) # Step 1: List available services services = external_fetcher.list_available_services() assert "forge" in services assert "vapor" in services # Step 2: Update external documentation (simulate) with patch.object(external_fetcher, 'fetch_laravel_service_docs', return_value=True): result = external_fetcher.fetch_laravel_service_docs("forge") assert result is True # Step 3: Check that external docs exist # The test fixture should have created these files forge_dir = test_external_docs_dir / "forge" assert forge_dir.exists() assert (forge_dir / "introduction.md").exists() # Step 4: Read external documentation content content = (forge_dir / "introduction.md").read_text() assert "Forge" in content assert "Introduction" in content @pytest.mark.integration class TestErrorRecoveryWorkflows: """Test error recovery and resilience workflows.""" def test_documentation_update_failure_recovery(self, test_docs_dir): """Test recovery from documentation update failures.""" from docs_updater import DocsUpdater with patch.object(DocsUpdater, 'update') as mock_update: # First attempt fails mock_update.side_effect = Exception("Network error") updater = DocsUpdater(test_docs_dir, "12.x") # Should handle error gracefully try: updater.update(force=False) except Exception as e: # Error is expected assert "Network error" in str(e) # System should still be functional for other operations # Test that we can still read metadata metadata = updater.read_local_metadata() assert isinstance(metadata, dict) # Should return empty dict or existing metadata def test_file_system_error_recovery(self, test_docs_dir): """Test recovery from file system errors.""" from mcp_tools import read_laravel_doc_content_impl, clear_caches # Clear caches first clear_caches() # Create documentation file version_dir = test_docs_dir / "12.x" version_dir.mkdir(parents=True, exist_ok=True) test_file = version_dir / "test.md" test_file.write_text("# Test Documentation") # Test normal operation result = read_laravel_doc_content_impl(test_docs_dir, "test.md", "12.x") assert "# Test Documentation" in result # Clear cache before testing error case clear_caches() # Simulate file permission error with patch('builtins.open', side_effect=PermissionError("Access denied")): result = read_laravel_doc_content_impl(test_docs_dir, "test.md", "12.x") # Should handle the error and return error message assert "Documentation file not found" in result or "Error" in result # Other operations should still work from laravel_mcp_companion import get_laravel_package_info with patch.dict(laravel_mcp_companion.PACKAGE_CATALOG, {'test/package': {'name': 'Test', 'description': 'Test package'}}): package_result = get_laravel_package_info("test/package") assert "Test" in package_result def test_network_error_resilience(self, test_docs_dir): """Test resilience to network errors.""" # Test external service fetching with network issues with patch('docs_updater.urllib.request.urlopen') as mock_urlopen: mock_urlopen.side_effect = Exception("Network timeout") fetcher = DocsUpdater(test_docs_dir, "12.x") # Should handle network errors gracefully try: fetcher.get_latest_commit() assert False, "Should have raised an exception" except Exception as e: # Error should be handled at the appropriate level assert "Network timeout" in str(e) or "Error fetching" in str(e) def test_malformed_data_handling(self, test_docs_dir): """Test handling of malformed or corrupted data.""" from docs_updater import DocsUpdater # Create corrupted metadata file version_dir = test_docs_dir / "12.x" version_dir.mkdir(parents=True, exist_ok=True) metadata_dir = version_dir / ".metadata" metadata_dir.mkdir(exist_ok=True) metadata_file = metadata_dir / "sync_info.json" metadata_file.write_text("{ invalid json content }") # Create a DocsUpdater instance updater = DocsUpdater(test_docs_dir, "12.x") # Should handle corrupted metadata gracefully metadata = updater.read_local_metadata() assert metadata == {} # Should return empty dict for corrupted metadata @pytest.mark.integration class TestCachingWorkflows: """Test caching behavior across operations.""" def test_file_content_caching_workflow(self, test_docs_dir): """Test file content caching across multiple operations.""" from mcp_tools import get_file_content_cached, clear_caches, _file_content_cache # Clear caches first clear_caches() # Setup test file test_file = test_docs_dir / "test_cache.md" test_content = "# Caching Test\n\nThis content should be cached." test_file.write_text(test_content) # First read - should cache the content result1 = get_file_content_cached(test_file) assert result1 == test_content # Verify cache is populated assert len(_file_content_cache) > 0 # Modify the file test_file.write_text("Modified content") # Second read - should still use cache (not detect modification in this test) result2 = get_file_content_cached(test_file) assert result2 == test_content # Still cached content # Clear cache and read again clear_caches() result3 = get_file_content_cached(test_file) assert result3 == "Modified content" # Now reads new content def test_search_result_caching(self, test_docs_dir): """Test search result caching.""" from mcp_tools import search_laravel_docs_impl, clear_caches, _search_result_cache # Clear caches first clear_caches() # Create test files version_dir = test_docs_dir / "12.x" version_dir.mkdir(exist_ok=True) (version_dir / "test.md").write_text("test content with keyword") with patch('mcp_tools.os.listdir', return_value=['test.md']): # First search - should cache result result1 = search_laravel_docs_impl(test_docs_dir, "keyword", "12.x") # TOON format: query field present assert "keyword" in result1 # Verify search cache is populated assert len(_search_result_cache) > 0 # Second search with same query - should use cache # We can verify by checking the cache directly # The cache key format is "search:query:version:include_external" cache_key = "search:keyword:12.x:True" assert cache_key in _search_result_cache cached_result = _search_result_cache[cache_key] assert "test.md" in cached_result def test_cache_invalidation_workflow(self, test_docs_dir): """Test cache invalidation during documentation updates.""" from mcp_tools import clear_caches, _file_content_cache, _search_result_cache # Populate caches _file_content_cache["test"] = "cached_content" _search_result_cache[("test", "12.x", True)] = "cached_search" # Verify caches are populated assert len(_file_content_cache) > 0 assert len(_search_result_cache) > 0 # Clear caches (simulating what would happen after an update) clear_caches() # Verify caches are cleared assert len(_file_content_cache) == 0 assert len(_search_result_cache) == 0 @pytest.mark.integration class TestSecurityWorkflows: """Test security-related workflows.""" def test_path_traversal_protection_workflow(self, test_docs_dir): """Test path traversal protection across different operations.""" from mcp_tools import read_laravel_doc_content_impl # Setup safe file version_dir = test_docs_dir / "12.x" version_dir.mkdir(parents=True, exist_ok=True) safe_file = version_dir / "safe.md" safe_file.write_text("# Safe Content") # Setup file outside version directory outside_file = test_docs_dir / "outside.md" outside_file.write_text("# Outside Content - Should not be accessible") # Test safe access result = read_laravel_doc_content_impl(test_docs_dir, "safe.md", "12.x") assert "# Safe Content" in result # Path traversal attempts should be blocked traversal_attempts = [ "../outside.md", "../../outside.md", "../12.x/../outside.md" ] for attempt in traversal_attempts: result = read_laravel_doc_content_impl(test_docs_dir, attempt, "12.x") # Should either return error or safe content, never outside content assert "# Outside Content" not in result # Should indicate access denied or file not found assert "Documentation file not found" in result or "Access denied" in result def test_input_validation_workflow(self, test_docs_dir): """Test input validation across different functions.""" from mcp_tools import search_laravel_docs_impl # Test search input validation # Empty search should be rejected result = search_laravel_docs_impl(test_docs_dir, "", "12.x") assert "Search query cannot be empty" in result # Whitespace-only search should be rejected result = search_laravel_docs_impl(test_docs_dir, " ", "12.x") assert "Search query cannot be empty" in result # Package name validation from laravel_mcp_companion import get_laravel_package_info # Empty package name should be handled with patch.dict(laravel_mcp_companion.PACKAGE_CATALOG, {}, clear=True): result = get_laravel_package_info("") assert "not found" in result # Very long package name should be handled long_name = "a" * 1000 result = get_laravel_package_info(long_name) assert "not found" in result @pytest.mark.integration class TestPerformanceWorkflows: """Test performance-related workflows.""" def test_large_file_handling(self, test_docs_dir): """Test handling of large documentation files.""" from mcp_tools import read_laravel_doc_content_impl # Create a large test file version_dir = test_docs_dir / "12.x" version_dir.mkdir(parents=True, exist_ok=True) large_file = version_dir / "large.md" # Create content with ~10KB of text large_content = "# Large File\n\n" + ("This is a large documentation file. " * 500) large_file.write_text(large_content) # Should handle large file without issues result = read_laravel_doc_content_impl(test_docs_dir, "large.md", "12.x") assert "# Large File" in result assert len(result) > 1000 # Should contain substantial content # Search should also work with large files from mcp_tools import search_laravel_docs_impl with patch('mcp_tools.os.listdir', return_value=['large.md']): search_result = search_laravel_docs_impl(test_docs_dir, "Large", "12.x") assert "12.x/large.md" in search_result def test_multiple_version_handling(self, test_docs_dir): """Test performance with multiple Laravel versions.""" from mcp_tools import search_laravel_docs_impl # Create multiple version directories with files versions = ["10.x", "11.x", "12.x"] for version in versions: version_dir = test_docs_dir / version version_dir.mkdir(parents=True, exist_ok=True) # Create several files per version for i in range(5): test_file = version_dir / f"file_{i}.md" test_file.write_text(f"# File {i} for {version}\n\nContent for version {version}") # Search across all versions should be reasonably fast import time start_time = time.time() with patch('mcp_tools.SUPPORTED_VERSIONS', versions), \ patch('mcp_tools.os.listdir', return_value=[f'file_{i}.md' for i in range(5)]): result = search_laravel_docs_impl(test_docs_dir, "File", version=None) # Search all versions end_time = time.time() # Should complete in reasonable time (< 1 second for this test) assert end_time - start_time < 1.0 # TOON format: query field present assert "File" in result def test_concurrent_access_simulation(self, test_docs_dir): """Test behavior under simulated concurrent access.""" from mcp_tools import read_laravel_doc_content_impl # Setup test file version_dir = test_docs_dir / "12.x" version_dir.mkdir(parents=True, exist_ok=True) test_file = version_dir / "concurrent.md" test_file.write_text("# Concurrent Access Test") # Simulate multiple rapid accesses results = [] for i in range(10): result = read_laravel_doc_content_impl(test_docs_dir, "concurrent.md", "12.x") results.append(result) # All results should be consistent assert all("# Concurrent Access Test" in result for result in results) assert len(set(results)) == 1 # All results should be identical