#!/usr/bin/env python3
"""
Test suite for Phase 3: Auto-Registration Implementation
Tests the automatic document registration functionality added to manage_docs.
Validates that EDIT operations auto-register unregistered documents, while
CREATE operations remain unchanged.
"""
import asyncio
import json
import pytest
import sqlite3
import sys
from pathlib import Path
from unittest.mock import AsyncMock, MagicMock, patch
# Add parent directory to path for imports
sys.path.insert(0, str(Path(__file__).parent.parent))
from scribe_mcp.storage.sqlite import SQLiteStorage
from scribe_mcp.tools.manage_docs import _auto_register_document, manage_docs
class TestAutoRegisterDocument:
"""Test the _auto_register_document helper function."""
@pytest.mark.asyncio
async def test_auto_register_new_document(self, tmp_path):
"""Test that auto-registration creates registry entry for unregistered doc."""
# Setup: Create test database and project
db_path = tmp_path / "test.db"
storage = SQLiteStorage(str(db_path))
await storage._initialise()
# Create project in database
project_name = "test_auto_register_project"
repo_root = str(tmp_path / "repo")
docs_dir = tmp_path / "repo" / "docs" / "dev_plans" / project_name
docs_dir.mkdir(parents=True, exist_ok=True)
await storage.upsert_project(
name=project_name,
repo_root=repo_root,
progress_log_path=str(docs_dir / "PROGRESS_LOG.md"),
)
# Create an unregistered document file
arch_file = docs_dir / "ARCHITECTURE_GUIDE.md"
arch_file.write_text("# Architecture Guide\n\nTest content")
# Prepare project dict (without docs field - simulating unregistered doc)
project = {
"name": project_name,
"root": repo_root,
"docs": {}, # Empty - architecture not registered
}
# Mock server_module.storage_backend
with patch("scribe_mcp.tools.manage_docs.server_module") as mock_server:
mock_server.storage_backend = storage
# Mock ProjectRegistry and append_entry
with patch("scribe_mcp.tools.manage_docs._PROJECT_REGISTRY") as mock_registry:
with patch("scribe_mcp.tools.manage_docs.append_entry", new_callable=AsyncMock):
# Execute: Auto-register the document
result = await _auto_register_document(project, "architecture")
# Verify: Function returned True
assert result is True
# Verify: Database was updated with docs_json
row = await storage._fetchone(
"SELECT docs_json FROM scribe_projects WHERE name = ?",
(project_name,),
)
assert row is not None
assert row["docs_json"] is not None
docs_json = json.loads(row["docs_json"])
assert "architecture" in docs_json
assert str(arch_file) in docs_json["architecture"]
@pytest.mark.asyncio
async def test_auto_register_missing_file_fails(self, tmp_path):
"""Test that auto-registration fails gracefully for non-existent file."""
# Setup: Create test database and project
db_path = tmp_path / "test.db"
storage = SQLiteStorage(str(db_path))
await storage._initialise()
project_name = "test_missing_file"
repo_root = str(tmp_path / "repo")
docs_dir = tmp_path / "repo" / "docs" / "dev_plans" / project_name
docs_dir.mkdir(parents=True, exist_ok=True)
await storage.upsert_project(
name=project_name,
repo_root=repo_root,
progress_log_path=str(docs_dir / "PROGRESS_LOG.md"),
)
project = {
"name": project_name,
"root": repo_root,
"docs": {},
}
# Mock server_module.storage_backend
with patch("scribe_mcp.tools.manage_docs.server_module") as mock_server:
mock_server.storage_backend = storage
# Execute & Verify: Should raise ValueError for missing file
with pytest.raises(ValueError) as exc_info:
await _auto_register_document(project, "architecture")
assert "does not exist" in str(exc_info.value)
assert "generate_doc_templates" in str(exc_info.value)
@pytest.mark.asyncio
async def test_auto_register_computes_hash(self, tmp_path):
"""Test that auto-registration computes SHA256 hash correctly."""
# Setup
db_path = tmp_path / "test.db"
storage = SQLiteStorage(str(db_path))
await storage._initialise()
project_name = "test_hash_computation"
repo_root = str(tmp_path / "repo")
docs_dir = tmp_path / "repo" / "docs" / "dev_plans" / project_name
docs_dir.mkdir(parents=True, exist_ok=True)
await storage.upsert_project(
name=project_name,
repo_root=repo_root,
progress_log_path=str(docs_dir / "PROGRESS_LOG.md"),
)
# Create document with known content
phase_file = docs_dir / "PHASE_PLAN.md"
test_content = "# Phase Plan\n\nTest phase content"
phase_file.write_text(test_content)
# Compute expected hash
import hashlib
expected_hash = hashlib.sha256(test_content.encode('utf-8')).hexdigest()
project = {
"name": project_name,
"root": repo_root,
"docs": {},
}
with patch("scribe_mcp.tools.manage_docs.server_module") as mock_server:
mock_server.storage_backend = storage
with patch("scribe_mcp.tools.manage_docs._PROJECT_REGISTRY") as mock_registry:
mock_registry.record_doc_update = AsyncMock()
with patch("scribe_mcp.tools.manage_docs.append_entry", new_callable=AsyncMock) as mock_append:
# Execute
await _auto_register_document(project, "phase_plan")
# Verify: append_entry was called with hash in metadata
assert mock_append.called
call_kwargs = mock_append.call_args.kwargs
assert "meta" in call_kwargs
assert "hash" in call_kwargs["meta"]
assert call_kwargs["meta"]["hash"] == expected_hash[:8]
@pytest.mark.asyncio
async def test_auto_register_logs_event(self, tmp_path):
"""Test that auto-registration logs to progress log."""
# Setup
db_path = tmp_path / "test.db"
storage = SQLiteStorage(str(db_path))
await storage._initialise()
project_name = "test_logging"
repo_root = str(tmp_path / "repo")
docs_dir = tmp_path / "repo" / "docs" / "dev_plans" / project_name
docs_dir.mkdir(parents=True, exist_ok=True)
await storage.upsert_project(
name=project_name,
repo_root=repo_root,
progress_log_path=str(docs_dir / "PROGRESS_LOG.md"),
)
checklist_file = docs_dir / "CHECKLIST.md"
checklist_file.write_text("# Checklist\n\nTest items")
project = {
"name": project_name,
"root": repo_root,
"docs": {},
}
with patch("scribe_mcp.tools.manage_docs.server_module") as mock_server:
mock_server.storage_backend = storage
with patch("scribe_mcp.tools.manage_docs._PROJECT_REGISTRY") as mock_registry:
mock_registry.record_doc_update = AsyncMock()
with patch("scribe_mcp.tools.manage_docs.append_entry", new_callable=AsyncMock) as mock_append:
# Execute
await _auto_register_document(project, "checklist")
# Verify: append_entry was called with correct parameters
assert mock_append.called
call_kwargs = mock_append.call_args.kwargs
assert "message" in call_kwargs
assert "Auto-registered document: checklist" in call_kwargs["message"]
assert "status" in call_kwargs
assert call_kwargs["status"] == "info"
assert "agent" in call_kwargs
assert call_kwargs["agent"] == "manage_docs"
assert "meta" in call_kwargs
meta = call_kwargs["meta"]
assert meta["action"] == "auto_register"
assert meta["doc"] == "checklist"
class TestManageDocsAutoRegistration:
"""Test auto-registration integration in manage_docs function."""
@pytest.mark.asyncio
async def test_edit_action_auto_registers(self, tmp_path):
"""Test that EDIT action auto-registers unregistered document."""
# This is an integration test - would require full manage_docs setup
# For now, we verify the logic path exists
# Full integration testing happens in Phase 4
pass
@pytest.mark.asyncio
async def test_create_action_no_auto_register(self):
"""Test that CREATE actions do NOT trigger auto-registration."""
# Verify EDIT_ACTIONS set doesn't include CREATE actions
from scribe_mcp.tools.manage_docs import manage_docs
# The EDIT_ACTIONS set is defined inside manage_docs function
# We can verify by checking the function code or integration test
# Full verification happens in Phase 4 comprehensive testing
pass
class TestAutoRegistrationErrorHandling:
"""Test error handling in auto-registration."""
@pytest.mark.asyncio
async def test_auto_register_invalid_doc_key(self, tmp_path):
"""Test that invalid doc_key raises appropriate error."""
db_path = tmp_path / "test.db"
storage = SQLiteStorage(str(db_path))
await storage._initialise()
project_name = "test_invalid_key"
repo_root = str(tmp_path / "repo")
docs_dir = tmp_path / "repo" / "docs" / "dev_plans" / project_name
docs_dir.mkdir(parents=True, exist_ok=True)
await storage.upsert_project(
name=project_name,
repo_root=repo_root,
progress_log_path=str(docs_dir / "PROGRESS_LOG.md"),
)
project = {
"name": project_name,
"root": repo_root,
"docs": {},
}
with patch("scribe_mcp.tools.manage_docs.server_module") as mock_server:
mock_server.storage_backend = storage
# Execute & Verify: Invalid doc_key should fail
with pytest.raises(ValueError) as exc_info:
await _auto_register_document(project, "invalid_unknown_doc_key_xyz")
assert "Invalid document key" in str(exc_info.value) or "does not exist" in str(exc_info.value)
@pytest.mark.asyncio
async def test_auto_register_without_backend_fails(self, tmp_path):
"""Test that auto-registration fails if storage backend unavailable."""
project_name = "test_no_backend"
repo_root = str(tmp_path / "repo")
docs_dir = tmp_path / "repo" / "docs" / "dev_plans" / project_name
docs_dir.mkdir(parents=True, exist_ok=True)
# Create document
arch_file = docs_dir / "ARCHITECTURE_GUIDE.md"
arch_file.write_text("# Architecture")
project = {
"name": project_name,
"root": repo_root,
"docs": {},
}
# Mock server_module with NO storage_backend
with patch("scribe_mcp.tools.manage_docs.server_module") as mock_server:
mock_server.storage_backend = None # No backend
# Execute & Verify
with pytest.raises(ValueError) as exc_info:
await _auto_register_document(project, "architecture")
assert "Storage backend not available" in str(exc_info.value)
if __name__ == "__main__":
pytest.main([__file__, "-v"])
