574 lines
20 KiB
Python
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"
|