test_doxygen_cleanup.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_docs/test_doxygen_cleanup.py
 
"""
Purpose
-------
Validate the OI-423 stale Doxyfile sweeper in ``oct.docs.oct_docs``.
 
Responsibilities
----------------
- Confirm old ``oct-doxyfile-*.Doxyfile`` temp files are removed.
- Confirm recent ``oct-doxyfile-*.Doxyfile`` temp files are preserved.
- Confirm unrelated temp files are never touched.
- Confirm the sweeper is resilient to per-file OS errors.
- Confirm the sweeper returns the count of removed files.
 
Diagnostics
-----------
Domain: DOCS-TESTS
L2: test lifecycle
L3: assertion details
L4: deep tracing
 
Contracts
---------
Inputs:  tmp_path, monkeypatch pytest fixtures
Outputs: pass/fail assertions
"""
 
import os
import tempfile
import time
from pathlib import Path
 
import pytest
 
from oct.docs import oct_docs
from oct.docs.oct_docs import (
    _sweep_stale_doxyfiles,
    _STALE_DOXYFILE_MAX_AGE_SECONDS,
)
 
 
@pytest.fixture
def isolated_tmp(tmp_path: Path, monkeypatch) -> Path:
    """Redirect ``tempfile.gettempdir()`` to an isolated directory.
 
    Prevents tests from touching (or being polluted by) the real system
    temp directory.
    """
    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))
    # oct_docs imported tempfile at module level, so we also need to
    # patch the module-level reference.
    monkeypatch.setattr(oct_docs.tempfile, "gettempdir", lambda: str(tmp_path))
    return tmp_path
 
 
def _make_stale(path: Path, age_seconds: float) -> None:
    path.write_text("# fake Doxyfile\n", encoding="utf-8")
    past = time.time() - age_seconds
    os.utime(path, (past, past))
 
 
def test_sweep_removes_old_stale_doxyfile(isolated_tmp: Path) -> None:
    """A 48h-old oct-doxyfile-*.Doxyfile is removed."""
    stale = isolated_tmp / "oct-doxyfile-abc123.Doxyfile"
    _make_stale(stale, 48 * 3600)
 
    removed = _sweep_stale_doxyfiles()
 
    assert removed == 1
    assert not stale.exists()
 
 
def test_sweep_preserves_recent_doxyfile(isolated_tmp: Path) -> None:
    """A freshly-created oct-doxyfile-*.Doxyfile is preserved."""
    recent = isolated_tmp / "oct-doxyfile-xyz.Doxyfile"
    recent.write_text("# live Doxyfile\n", encoding="utf-8")
 
    removed = _sweep_stale_doxyfiles()
 
    assert removed == 0
    assert recent.exists()
 
 
def test_sweep_ignores_unrelated_temp_files(isolated_tmp: Path) -> None:
    """Files without the oct-doxyfile- prefix are never touched."""
    foreign = isolated_tmp / "foo.Doxyfile"
    _make_stale(foreign, 48 * 3600)
 
    removed = _sweep_stale_doxyfiles()
 
    assert removed == 0
    assert foreign.exists()
 
 
def test_sweep_returns_count(isolated_tmp: Path) -> None:
    """The return value equals the number of files actually removed."""
    for i in range(3):
        _make_stale(
            isolated_tmp / f"oct-doxyfile-{i}.Doxyfile", 48 * 3600,
        )
    # Two recent, one unrelated: should not be counted.
    (isolated_tmp / "oct-doxyfile-live.Doxyfile").write_text("x", encoding="utf-8")
    _make_stale(isolated_tmp / "unrelated.Doxyfile", 48 * 3600)
 
    removed = _sweep_stale_doxyfiles()
 
    assert removed == 3
 
 
def test_sweep_handles_unlink_failure_gracefully(
    isolated_tmp: Path, monkeypatch,
) -> None:
    """A per-file OSError during unlink must not propagate."""
    stale = isolated_tmp / "oct-doxyfile-locked.Doxyfile"
    _make_stale(stale, 48 * 3600)
 
    real_unlink = Path.unlink
 
    def fake_unlink(self, *args, **kwargs):
        if self.name == "oct-doxyfile-locked.Doxyfile":
            raise OSError("simulated permission error")
        return real_unlink(self, *args, **kwargs)
 
    monkeypatch.setattr(Path, "unlink", fake_unlink)
 
    # Must not raise.
    removed = _sweep_stale_doxyfiles()
    assert removed == 0
 
 
def test_sweep_respects_custom_max_age(isolated_tmp: Path) -> None:
    """An explicit max_age_seconds overrides the 24h default."""
    # 1 hour old — under the default 24h, but over a custom 30min cap.
    path = isolated_tmp / "oct-doxyfile-borderline.Doxyfile"
    _make_stale(path, 3600)
 
    assert _sweep_stale_doxyfiles() == 0
    assert path.exists()
    assert _sweep_stale_doxyfiles(max_age_seconds=1800) == 1
    assert not path.exists()
 
 
def test_sweep_default_constant_is_one_day() -> None:
    """Sanity: the module-level constant matches the documented value."""
    assert _STALE_DOXYFILE_MAX_AGE_SECONDS == 24 * 60 * 60