test_docs_health.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_health/test_docs_health.py
 
"""
Tests for documentation health check.
 
Purpose
-------
Verify that check_docs_health correctly validates required documentation files.
 
Responsibilities
----------------
- Test all docs present.
- Test individual missing files.
- Test completely missing docs.
 
Diagnostics
-----------
Domain: TESTS.HEALTH
Levels:
    L2 — test lifecycle
    L3 — docs validation
    L4 — per-file presence checks
 
Contracts
---------
- All four required files are checked.
- Counts match actual file presence.
"""
 
import pytest
from pathlib import Path
 
from oct.health.oct_health import check_docs_health
 
 
def test_docs_health_all_present(temp_project_root: Path):
    """Test that all required docs are detected when present."""
    (temp_project_root / "docs" / "ARCHITECTURE.md").write_text("# Arch", encoding="utf-8")
    (temp_project_root / "CHANGELOG.md").write_text("# Changelog", encoding="utf-8")
    (temp_project_root / "tests" / "Tests_README.md").write_text("# Tests", encoding="utf-8")
    (temp_project_root / "tests" / "run_tests.py").write_text("# runner", encoding="utf-8")
    (temp_project_root / "oc_diagnostics" / "debug_config.json").write_text("{}", encoding="utf-8")
 
    result = check_docs_health(temp_project_root)
 
    # Standard maturity: 5 required (CHANGELOG.md added), SECURITY.md is optional.
    assert result["total_required"] == 5
    assert result["total_present"] == 5
 
 
def test_docs_health_missing_architecture(temp_project_root: Path):
    """Test detection of missing ARCHITECTURE.md."""
    (temp_project_root / "CHANGELOG.md").write_text("# Changelog", encoding="utf-8")
    (temp_project_root / "tests" / "Tests_README.md").write_text("# Tests", encoding="utf-8")
    (temp_project_root / "tests" / "run_tests.py").write_text("# runner", encoding="utf-8")
    (temp_project_root / "oc_diagnostics" / "debug_config.json").write_text("{}", encoding="utf-8")
 
    result = check_docs_health(temp_project_root)
 
    assert result["total_present"] == 4
    arch_file = next(f for f in result["files"] if f["name"] == "ARCHITECTURE.md")
    assert arch_file["present"] is False
 
 
def test_docs_health_missing_config(temp_project_root: Path):
    """Test detection of missing debug_config.json."""
    (temp_project_root / "docs" / "ARCHITECTURE.md").write_text("# Arch", encoding="utf-8")
    (temp_project_root / "CHANGELOG.md").write_text("# Changelog", encoding="utf-8")
    (temp_project_root / "tests" / "Tests_README.md").write_text("# Tests", encoding="utf-8")
    (temp_project_root / "tests" / "run_tests.py").write_text("# runner", encoding="utf-8")
 
    result = check_docs_health(temp_project_root)
 
    assert result["total_present"] == 4
    config_file = next(f for f in result["files"] if f["name"] == "debug_config.json")
    assert config_file["present"] is False
 
 
def test_docs_health_missing_changelog(temp_project_root: Path):
    """CHANGELOG.md is required at Standard maturity (drift item B1)."""
    (temp_project_root / "docs" / "ARCHITECTURE.md").write_text("# Arch", encoding="utf-8")
    (temp_project_root / "tests" / "Tests_README.md").write_text("# Tests", encoding="utf-8")
    (temp_project_root / "tests" / "run_tests.py").write_text("# runner", encoding="utf-8")
    (temp_project_root / "oc_diagnostics" / "debug_config.json").write_text("{}", encoding="utf-8")
 
    result = check_docs_health(temp_project_root)
 
    assert result["total_present"] == 4
    changelog_file = next(f for f in result["files"] if f["name"] == "CHANGELOG.md")
    assert changelog_file["present"] is False
    assert changelog_file["required"] is True
 
 
def test_docs_health_security_optional_outside_production(temp_project_root: Path):
    """SECURITY.md is shown but not required outside Production maturity."""
    result = check_docs_health(temp_project_root)
 
    security_file = next(f for f in result["files"] if f["name"] == "SECURITY.md")
    assert security_file["present"] is False
    assert security_file["required"] is False
    # SECURITY.md absence does not contribute to total_required.
    assert result["total_required"] == 5
 
 
def test_docs_health_security_required_in_production(temp_project_root: Path):
    """SECURITY.md is required when production_mode=True (Appendix H Level 2)."""
    result = check_docs_health(temp_project_root, production_mode=True)
 
    assert result["total_required"] == 6
    security_file = next(f for f in result["files"] if f["name"] == "SECURITY.md")
    assert security_file["required"] is True
 
 
def test_docs_health_all_missing(temp_project_root: Path):
    """Test when no required docs exist."""
    result = check_docs_health(temp_project_root)
 
    assert result["total_required"] == 5
    assert result["total_present"] == 0
 
 
def test_docs_health_file_list_structure(temp_project_root: Path):
    """Test that file list has correct structure."""
    result = check_docs_health(temp_project_root)
 
    # 5 required + 1 optional (SECURITY.md) at Standard maturity.
    assert len(result["files"]) == 6
    for file_info in result["files"]:
        assert "name" in file_info
        assert "present" in file_info
        assert "required" in file_info