Files
fiona-assistant/tests/test_md_frontmatter.py
2026-09-29 16:01:16 +02:00

574 lines
20 KiB
Python

"""Tests for MD Frontmatter module.
This module handles parsing and managing YAML frontmatter in markdown files
for version control and source tracking. Primary focus is on name and version
fields for source controlling later.
"""
import pathlib
import tempfile
import pytest
from fiona.librarian.md_frontmatter import (
FrontmatterError,
FrontmatterParser,
RequiredFieldError,
extract_frontmatter_string,
extract_name_and_version,
get_file_version,
parse_frontmatter,
update_version,
validate_required_fields,
)
# =============================================================================
# Fixtures
# =============================================================================
@pytest.fixture
def valid_frontmatter_content():
"""Sample markdown content with valid frontmatter including name and version."""
return """---
name: Test Document
version: 1.0.0
title: Test Page
created: 2025-09-20
updated: 2025-09-21
type: concept
sources: [raw/articles/test.md]
tags: [test, example]
---
# Page Content
This is the page content.
"""
@pytest.fixture
def minimal_frontmatter_content():
"""Sample markdown content with minimal required frontmatter including name and version."""
return """---
name: Minimal Document
version: 0.1.0
title: Minimal Page
created: 2025-09-20
updated: 2025-09-20
type: concept
---
# Content here
"""
@pytest.fixture
def frontmatter_without_name():
"""Sample markdown content missing name field."""
return """---
version: 1.0.0
title: Nameless Page
created: 2025-09-20
updated: 2025-09-20
type: concept
---
# Content here
"""
@pytest.fixture
def frontmatter_without_version():
"""Sample markdown content missing version field."""
return """---
name: Versionless Document
title: Versionless Page
created: 2025-09-20
updated: 2025-09-20
type: concept
---
# Content here
"""
@pytest.fixture
def missing_required_frontmatter_content():
"""Sample markdown content missing required fields."""
return """---
title: Incomplete Page
created: 2025-09-20
---
# Content here
"""
@pytest.fixture
def no_frontmatter_content():
"""Sample markdown content without frontmatter."""
return """# Page Title
This is content without frontmatter.
"""
@pytest.fixture
def invalid_yaml_frontmatter_content():
"""Sample markdown content with invalid YAML in frontmatter."""
return """---
name: Invalid Page
version: 1.0.0
invalid_yaml: [unclosed bracket
type: concept
---
# Content here
"""
@pytest.fixture
def frontmatter_with_optional_fields():
"""Sample markdown content with optional quality signal fields."""
return """---
name: Quality Document
version: 2.0.0-beta
title: Quality Page
created: 2025-09-20
updated: 2025-09-21
type: concept
confidence: high
contested: false
contradictions: [other-page]
sources: [raw/articles/test.md]
tags: [test]
---
# Content
"""
@pytest.fixture
def temp_md_file(valid_frontmatter_content):
"""Create a temporary markdown file with frontmatter."""
with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
f.write(valid_frontmatter_content)
f.flush()
yield pathlib.Path(f.name)
pathlib.Path(f.name).unlink(missing_ok=True)
# =============================================================================
# Test: extract_frontmatter_string
# =============================================================================
class TestExtractFrontmatterString:
"""Tests for extract_frontmatter_string function."""
def test_extract_valid_frontmatter(self, valid_frontmatter_content):
"""Should extract frontmatter string (YAML content only) from content with frontmatter."""
result = extract_frontmatter_string(valid_frontmatter_content)
assert "name: Test Document" in result
assert "version: 1.0.0" in result
assert "created: 2025-09-20" in result
assert "---" not in result # Should not include delimiters
assert "# Page Content" not in result
def test_extract_minimal_frontmatter(self, minimal_frontmatter_content):
"""Should extract minimal frontmatter."""
result = extract_frontmatter_string(minimal_frontmatter_content)
assert "name: Minimal Document" in result
assert "version: 0.1.0" in result
assert "# Content here" not in result
def test_extract_no_frontmatter_returns_none(self, no_frontmatter_content):
"""Should return None when no frontmatter exists."""
result = extract_frontmatter_string(no_frontmatter_content)
assert result is None
def test_extract_empty_content_returns_none(self):
"""Should return None for empty content."""
result = extract_frontmatter_string("")
assert result is None
def test_extract_content_with_only_delimiters(self):
"""Should return empty string for content with only --- delimiters."""
content = "---\n---\n"
result = extract_frontmatter_string(content)
assert result == ""
# =============================================================================
# Test: parse_frontmatter
# =============================================================================
class TestParseFrontmatter:
"""Tests for parse_frontmatter function."""
def test_parse_valid_frontmatter(self, valid_frontmatter_content):
"""Should parse valid frontmatter into dictionary."""
result = parse_frontmatter(valid_frontmatter_content)
assert isinstance(result, dict)
assert result["name"] == "Test Document"
assert result["version"] == "1.0.0"
assert result["title"] == "Test Page"
assert result["created"] == "2025-09-20"
assert result["updated"] == "2025-09-21"
assert result["type"] == "concept"
assert result["sources"] == ["raw/articles/test.md"]
assert result["tags"] == ["test", "example"]
def test_parse_minimal_frontmatter(self, minimal_frontmatter_content):
"""Should parse minimal frontmatter."""
result = parse_frontmatter(minimal_frontmatter_content)
assert result["name"] == "Minimal Document"
assert result["version"] == "0.1.0"
assert result["title"] == "Minimal Page"
def test_parse_no_frontmatter_returns_empty_dict(self, no_frontmatter_content):
"""Should return empty dict when no frontmatter exists."""
result = parse_frontmatter(no_frontmatter_content)
assert result == {}
def test_parse_invalid_yaml_raises_error(self, invalid_yaml_frontmatter_content):
"""Should raise FrontmatterError for invalid YAML."""
with pytest.raises(FrontmatterError) as exc_info:
parse_frontmatter(invalid_yaml_frontmatter_content)
assert "Failed to parse YAML" in str(exc_info.value)
def test_parse_frontmatter_with_optional_fields(self, frontmatter_with_optional_fields):
"""Should parse optional fields correctly."""
result = parse_frontmatter(frontmatter_with_optional_fields)
assert result["name"] == "Quality Document"
assert result["version"] == "2.0.0-beta"
assert result["confidence"] == "high"
assert result["contested"] is False
# =============================================================================
# Test: extract_name_and_version (PRIMARY FEATURE)
# =============================================================================
class TestExtractNameAndVersion:
"""Tests for extract_name_and_version function - PRIMARY for source control."""
def test_extract_name_and_version_from_valid(self, valid_frontmatter_content):
"""Should extract name and version from valid frontmatter."""
name, version = extract_name_and_version(valid_frontmatter_content)
assert name == "Test Document"
assert version == "1.0.0"
def test_extract_name_and_version_from_minimal(self, minimal_frontmatter_content):
"""Should extract name and version from minimal frontmatter."""
name, version = extract_name_and_version(minimal_frontmatter_content)
assert name == "Minimal Document"
assert version == "0.1.0"
def test_extract_name_and_version_from_optional_fields(self, frontmatter_with_optional_fields):
"""Should extract name and version with pre-release version."""
name, version = extract_name_and_version(frontmatter_with_optional_fields)
assert name == "Quality Document"
assert version == "2.0.0-beta"
def test_extract_name_and_version_missing_name(self, frontmatter_without_name):
"""Should raise error when name is missing."""
with pytest.raises(RequiredFieldError) as exc_info:
extract_name_and_version(frontmatter_without_name)
assert "name" in str(exc_info.value).lower()
def test_extract_name_and_version_missing_version(self, frontmatter_without_version):
"""Should raise error when version is missing."""
with pytest.raises(RequiredFieldError) as exc_info:
extract_name_and_version(frontmatter_without_version)
assert "version" in str(exc_info.value).lower()
def test_extract_name_and_version_no_frontmatter(self, no_frontmatter_content):
"""Should raise error when no frontmatter exists."""
with pytest.raises(RequiredFieldError):
extract_name_and_version(no_frontmatter_content)
def test_extract_name_and_version_from_file(self, temp_md_file):
"""Should extract name and version from file path."""
name, version = extract_name_and_version(temp_md_file)
assert name == "Test Document"
assert version == "1.0.0"
# =============================================================================
# Test: get_file_version (PRIMARY FEATURE)
# =============================================================================
class TestGetFileVersion:
"""Tests for get_file_version function - PRIMARY for source control."""
def test_get_file_version_from_content(self, valid_frontmatter_content):
"""Should get version from content."""
version = get_file_version(valid_frontmatter_content)
assert version == "1.0.0"
def test_get_file_version_from_file(self, temp_md_file):
"""Should get version from file path."""
version = get_file_version(temp_md_file)
assert version == "1.0.0"
def test_get_file_version_missing_version(self, frontmatter_without_version):
"""Should raise error when version is missing."""
with pytest.raises(RequiredFieldError) as exc_info:
get_file_version(frontmatter_without_version)
assert "version" in str(exc_info.value).lower()
def test_get_file_version_no_frontmatter(self, no_frontmatter_content):
"""Should raise error when no frontmatter exists."""
with pytest.raises(RequiredFieldError):
get_file_version(no_frontmatter_content)
# =============================================================================
# Test: update_version
# =============================================================================
class TestUpdateVersion:
"""Tests for update_version function."""
def test_update_version_in_content(self, valid_frontmatter_content):
"""Should update version in content and return new content."""
new_content = update_version(valid_frontmatter_content, "2.0.0")
frontmatter = parse_frontmatter(new_content)
assert frontmatter["version"] == "2.0.0"
assert frontmatter["name"] == "Test Document"
assert "# Page Content" in new_content
def test_update_version_preserves_content(self, valid_frontmatter_content):
"""Should preserve all content except version."""
new_content = update_version(valid_frontmatter_content, "99.99.99")
assert "# Page Content" in new_content
assert "This is the page content." in new_content
assert "title: Test Page" in new_content
def test_update_version_in_file(self, temp_md_file):
"""Should update version in file."""
update_version(temp_md_file, "3.0.0", in_place=True)
frontmatter = parse_frontmatter(temp_md_file)
assert frontmatter["version"] == "3.0.0"
def test_update_version_no_frontmatter_raises_error(self, no_frontmatter_content):
"""Should raise error when trying to update version on content without frontmatter."""
with pytest.raises(FrontmatterError):
update_version(no_frontmatter_content, "1.0.0")
# =============================================================================
# Test: validate_required_fields
# =============================================================================
class TestValidateRequiredFields:
"""Tests for validate_required_fields function."""
def test_validate_all_required_fields_present(self, valid_frontmatter_content):
"""Should pass when all required fields are present."""
frontmatter = parse_frontmatter(valid_frontmatter_content)
result = validate_required_fields(frontmatter)
assert result is True
def test_validate_missing_required_field_raises_error(self, missing_required_frontmatter_content):
"""Should raise RequiredFieldError when required fields are missing."""
frontmatter = parse_frontmatter(missing_required_frontmatter_content)
with pytest.raises(RequiredFieldError) as exc_info:
validate_required_fields(frontmatter)
assert "Missing required fields" in str(exc_info.value)
assert "updated" in str(exc_info.value)
assert "type" in str(exc_info.value)
def test_validate_empty_frontmatter_missing_all(self):
"""Should report all missing fields for empty frontmatter."""
frontmatter = {}
with pytest.raises(RequiredFieldError) as exc_info:
validate_required_fields(frontmatter)
error_msg = str(exc_info.value)
assert "title" in error_msg
assert "created" in error_msg
assert "updated" in error_msg
assert "type" in error_msg
def test_validate_with_custom_required_fields(self, valid_frontmatter_content):
"""Should allow custom required field list."""
frontmatter = parse_frontmatter(valid_frontmatter_content)
result = validate_required_fields(frontmatter, required_fields=["name", "version"])
assert result is True
# =============================================================================
# Test: FrontmatterParser class
# =============================================================================
class TestFrontmatterParser:
"""Tests for FrontmatterParser class."""
def test_parse_file(self, temp_md_file):
"""Should parse frontmatter from a file path."""
parser = FrontmatterParser()
result = parser.parse_file(temp_md_file)
assert result["name"] == "Test Document"
assert result["version"] == "1.0.0"
assert result["title"] == "Test Page"
assert result["type"] == "concept"
def test_parse_content(self, valid_frontmatter_content):
"""Should parse frontmatter from content string."""
parser = FrontmatterParser()
result = parser.parse_content(valid_frontmatter_content)
assert result["name"] == "Test Document"
assert result["version"] == "1.0.0"
def test_validate_file(self, temp_md_file):
"""Should validate frontmatter in a file."""
parser = FrontmatterParser()
result = parser.validate_file(temp_md_file)
assert result is True
def test_validate_file_missing_fields(self, temp_md_file, missing_required_frontmatter_content):
"""Should raise error when validating file with missing fields."""
with temp_md_file.open('w') as f:
f.write(missing_required_frontmatter_content)
parser = FrontmatterParser()
with pytest.raises(RequiredFieldError):
parser.validate_file(temp_md_file)
def test_extract_content_body(self, valid_frontmatter_content):
"""Should extract content body without frontmatter."""
parser = FrontmatterParser()
body = parser.extract_content_body(valid_frontmatter_content)
assert "# Page Content" in body
assert "---" not in body
assert "name: Test Document" not in body
def test_extract_content_body_no_frontmatter(self, no_frontmatter_content):
"""Should return full content when no frontmatter exists."""
parser = FrontmatterParser()
body = parser.extract_content_body(no_frontmatter_content)
assert body == no_frontmatter_content
def test_get_metadata(self, valid_frontmatter_content):
"""Should extract version control metadata."""
parser = FrontmatterParser()
metadata = parser.get_metadata(valid_frontmatter_content)
assert "name" in metadata
assert "version" in metadata
assert "title" in metadata
assert "created" in metadata
assert "updated" in metadata
assert "type" in metadata
def test_has_frontmatter_true(self, valid_frontmatter_content):
"""Should return True for content with frontmatter."""
parser = FrontmatterParser()
assert parser.has_frontmatter(valid_frontmatter_content) is True
def test_has_frontmatter_false(self, no_frontmatter_content):
"""Should return False for content without frontmatter."""
parser = FrontmatterParser()
assert parser.has_frontmatter(no_frontmatter_content) is False
def test_get_name_and_version(self, valid_frontmatter_content):
"""Should extract name and version from content."""
parser = FrontmatterParser()
name, version = parser.get_name_and_version(valid_frontmatter_content)
assert name == "Test Document"
assert version == "1.0.0"
def test_get_version(self, valid_frontmatter_content):
"""Should extract version from content."""
parser = FrontmatterParser()
version = parser.get_version(valid_frontmatter_content)
assert version == "1.0.0"
def test_update_version(self, valid_frontmatter_content):
"""Should update version in content."""
parser = FrontmatterParser()
new_content = parser.update_version(valid_frontmatter_content, "5.0.0")
frontmatter = parse_frontmatter(new_content)
assert frontmatter["version"] == "5.0.0"
# =============================================================================
# Integration Tests
# =============================================================================
class TestIntegration:
"""Integration tests for frontmatter handling with focus on name and version."""
def test_full_workflow(self, valid_frontmatter_content):
"""Test complete workflow: extract, parse, validate."""
frontmatter_str = extract_frontmatter_string(valid_frontmatter_content)
assert frontmatter_str is not None
frontmatter = parse_frontmatter(valid_frontmatter_content)
assert isinstance(frontmatter, dict)
assert validate_required_fields(frontmatter) is True
name, version = extract_name_and_version(valid_frontmatter_content)
assert name == "Test Document"
assert version == "1.0.0"
def test_parser_class_full_workflow(self, temp_md_file):
"""Test FrontmatterParser end-to-end with name/version focus."""
parser = FrontmatterParser()
frontmatter = parser.parse_file(temp_md_file)
assert frontmatter["name"] == "Test Document"
assert frontmatter["version"] == "1.0.0"
assert parser.validate_file(temp_md_file) is True
body = parser.extract_content_body(temp_md_file.read_text())
assert "# Page Content" in body
name, version = parser.get_name_and_version(temp_md_file)
assert name == "Test Document"
assert version == "1.0.0"
def test_version_tracking_workflow(self, temp_md_file):
"""Test version tracking workflow - PRIMARY use case."""
parser = FrontmatterParser()
current_version = parser.get_version(temp_md_file)
assert current_version == "1.0.0"
parser.update_version(temp_md_file, "2.0.0", in_place=True)
new_version = parser.get_version(temp_md_file)
assert new_version == "2.0.0"
name, version = parser.get_name_and_version(temp_md_file)
assert name == "Test Document"
assert version == "2.0.0"