test_docstring_fixing.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_formatter/test_docstring_fixing.py
 
"""
Tests for docstring fixing.
 
Purpose
-------
Verify that the formatter correctly fixes missing/incomplete module docstrings.
 
Responsibilities
----------------
- Test addition of complete docstring when missing.
- Test addition of missing sections to partial docstrings.
- Test preservation of existing docstring content.
- Test correct positioning after header block.
 
Diagnostics
-----------
Domain: TESTS.FORMATTER
Levels:
    L2 — test lifecycle
    L3 — test case setup
    L4 — detailed docstring parsing and verification
 
Contracts
---------
- New docstrings are inserted after the header block (after blank line).
- Existing docstrings are never replaced, only extended.
- All required sections are present in the result.
"""
 
import pytest
from pathlib import Path
 
from oct.formatter.oct_format import fix_docstring, FormatterContext
 
 
def test_add_missing_docstring(temp_project_root: Path, formatter_ctx_fix: FormatterContext):
    """Test that complete docstring skeleton is added when missing."""
    test_file = temp_project_root / "test_no_docstring.py"
    content = (
        "#!/usr/bin/env python3\n"
        "# -*- coding: utf-8 -*-\n"
        "# test.py\n"
        "\n"
        "def foo():\n"
        "    pass\n"
    )
    test_file.write_text(content, encoding="utf-8")
 
    changed, new_content, messages = fix_docstring(test_file, content, formatter_ctx_fix)
 
    assert changed is True
    assert '"""' in new_content
    assert "Purpose" in new_content
    assert "Responsibilities" in new_content
    assert "Diagnostics" in new_content
    assert "Contracts" in new_content
 
 
def test_add_missing_section_purpose(temp_project_root: Path, formatter_ctx_fix: FormatterContext):
    """Test that missing Purpose section is added."""
    test_file = temp_project_root / "test_missing_purpose.py"
    content = (
        '"""\nResponsibilities\n----------------\nNone.\n"""'
    )
 
    changed, new_content, messages = fix_docstring(test_file, content, formatter_ctx_fix)
 
    assert changed is True
    assert "Purpose" in new_content
    assert "Responsibilities" in new_content
 
 
def test_preserve_existing_docstring(temp_project_root: Path, formatter_ctx_fix: FormatterContext):
    """Test that existing docstring content is preserved."""
    test_file = temp_project_root / "test_preserve_docstring.py"
    original_docstring = (
        '"""\n'
        'Purpose\n'
        '-------\n'
        'This is a very important module.\n'
        '"""'
    )
    content = original_docstring
 
    changed, new_content, messages = fix_docstring(test_file, content, formatter_ctx_fix)
 
    assert changed is True
    assert "This is a very important module." in new_content
 
 
def test_docstring_dry_run(temp_project_root: Path, formatter_ctx: FormatterContext):
    """Test that dry-run mode doesn't modify files."""
    test_file = temp_project_root / "test_docstring_dryrun.py"
    content = "#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n# test.py\n\ndef foo():\n    pass\n"
    test_file.write_text(content, encoding="utf-8")
 
    changed, _, messages = fix_docstring(test_file, content, formatter_ctx)
 
    assert changed is True  # Change detected
    assert test_file.read_text(encoding="utf-8") == content  # But not applied
 
 
def test_complete_docstring_no_change(temp_project_root: Path, formatter_ctx_fix: FormatterContext):
    """Test that complete docstrings are not modified."""
    test_file = temp_project_root / "test_complete_docstring.py"
    content = (
        '"""\n'
        'Purpose\n'
        '-------\n'
        'Test.\n'
        'Responsibilities\n'
        '----------------\n'
        'Test.\n'
        'Diagnostics\n'
        '-----------\n'
        'Domain: TEST\n'
        'Levels:\n'
        '    L2 — test\n'
        'Contracts\n'
        '---------\n'
        'Test.\n'
        '"""'
    )
 
    changed, _, messages = fix_docstring(test_file, content, formatter_ctx_fix)
 
    assert changed is False
    assert len(messages) == 0