EOS/tests/test_doc.py

import json
import os
import re
import shutil
import sys
from pathlib import Path
from types import SimpleNamespace
from unittest.mock import patch

import pytest

DIR_PROJECT_ROOT = Path(__file__).parent.parent
DIR_TESTDATA = Path(__file__).parent / "testdata"

DIR_DOCS_GENERATED = DIR_PROJECT_ROOT / "docs" / "_generated"
DIR_TEST_GENERATED = DIR_TESTDATA / "docs" / "_generated"

GITHUB_ACTIONS = os.getenv("GITHUB_ACTIONS")


def _normalize_development_version(version: str) -> str:
    """Ignore the commit-derived suffix, while retaining the release version."""
    return re.sub(r"^(v?\d+\.\d+\.\d+)\.dev\d+$", r"\1.dev", version)


def _comparable_openapi_spec(spec: dict) -> dict:
    """Normalize only info.version; preserve the rest of the schema verbatim."""
    return spec | {
        "info": spec["info"]
        | {"version": _normalize_development_version(spec["info"]["version"])}
    }


def _comparable_openapi_md(markdown: str) -> str:
    """Normalize only the generated document's version header."""
    return re.sub(
        r"(?m)^(\*\*Version\*\*: `)([^`]+)(`)$",
        lambda match: match[1] + _normalize_development_version(match[2]) + match[3],
        markdown,
        count=1,
    )


def test_openapi_version_comparison():
    expected = {"info": {"version": "v0.3.0.dev123", "title": "EOS"}, "paths": {"/a": {}}}
    actual = {"info": {"version": "v0.3.0.dev456", "title": "EOS"}, "paths": {"/a": {}}}
    assert _comparable_openapi_spec(actual) == _comparable_openapi_spec(expected)
    assert _comparable_openapi_spec(actual | {"paths": {"/b": {}}}) != _comparable_openapi_spec(
        expected
    )
    assert _comparable_openapi_spec(
        actual | {"info": {"version": "v0.4.0.dev456"}}
    ) != _comparable_openapi_spec(expected)
    assert _comparable_openapi_spec(
        actual | {"info": {"version": "v0.3.0"}}
    ) != _comparable_openapi_spec(expected)


def test_openapi_markdown_version_comparison():
    expected = "# EOS\n\n**Version**: `v0.3.0.dev123`\n\n## Endpoint A\n"
    actual = expected.replace("dev123", "dev456")
    assert _comparable_openapi_md(actual) == _comparable_openapi_md(expected)
    assert _comparable_openapi_md(actual.replace("Endpoint A", "Endpoint B")) != _comparable_openapi_md(
        expected
    )
    assert _comparable_openapi_md(actual.replace("v0.3.0", "v0.4.0")) != _comparable_openapi_md(
        expected
    )
    assert _comparable_openapi_md(actual + "v0.3.0.dev456") != _comparable_openapi_md(
        expected + "v0.3.0.dev123"
    )


def test_config_documentation_requires_a_timezone_name(
    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
    monkeypatch.syspath_prepend(str(DIR_PROJECT_ROOT))
    from scripts import generate_config_md

    monkeypatch.setattr(generate_config_md, "to_datetime", lambda: SimpleNamespace(timezone_name=None))
    output = tmp_path / "config.md"
    with pytest.raises(RuntimeError, match="Documentation generation requires a timezone name"):
        generate_config_md.write_to_file(output, "Configuration documentation")
    assert not output.exists()


def test_generic_time_windows_keep_nested_documentation(monkeypatch):
    from akkudoktoreos.config.configabc import TimeWindowSequence

    monkeypatch.syspath_prepend(str(DIR_PROJECT_ROOT))
    from scripts import generate_config_md

    monkeypatch.setattr(generate_config_md, "documented_types", set())
    monkeypatch.setattr(generate_config_md, "undocumented_types", {})
    markdown = generate_config_md.generate_config_table_md(
        TimeWindowSequence, ["time_windows"], "", toplevel=True, extra_config=True
    )
    assert "`list[akkudoktoreos.config.configabc.TimeWindow]`" in markdown
    assert ":::{table} time_windows::windows::list" in markdown
    assert "| start_time | `Time`" in markdown
    assert "| duration | `Duration`" in markdown


@pytest.mark.skipif(GITHUB_ACTIONS == "true", reason="Skipped on GitHub Actions - TODO!")
def test_openapi_spec_current(config_eos, set_other_timezone):
    """Verify the openapi spec hasn´t changed."""
    set_other_timezone("UTC") # CI runs on UTC

    expected_spec_path = DIR_PROJECT_ROOT / "openapi.json"
    new_spec_path = DIR_TESTDATA / "openapi-new.json"

    with expected_spec_path.open("r", encoding="utf-8", newline=None) as f_expected:
        expected_spec = json.load(f_expected)

    # Patch get_config and import within guard to patch global variables within the eos module.
    with patch("akkudoktoreos.core.coreabc.get_config", return_value=config_eos):
        # Ensure the script works correctly as part of a package
        root_dir = Path(__file__).resolve().parent.parent
        sys.path.insert(0, str(root_dir))
        from scripts import generate_openapi

        spec = generate_openapi.generate_openapi()
        spec_str = json.dumps(spec, indent=4, sort_keys=True)

    with new_spec_path.open("w", encoding="utf-8", newline="\n") as f_new:
        f_new.write(spec_str)

    # Serialize to ensure comparison is consistent
    expected_spec_str = json.dumps(expected_spec, indent=4, sort_keys=True)

    try:
        assert _comparable_openapi_spec(json.loads(spec_str)) == _comparable_openapi_spec(
            json.loads(expected_spec_str)
        )
    except AssertionError as e:
        pytest.fail(
            f"Expected {new_spec_path} to equal {expected_spec_path}.\n"
            + f"If ok: `make gen-docs` or `cp {new_spec_path} {expected_spec_path}`\n"
        )


@pytest.mark.skipif(GITHUB_ACTIONS == "true", reason="Skipped on GitHub Actions - TODO!")
def test_openapi_md_current(config_eos, set_other_timezone):
    """Verify the generated openapi markdown hasn´t changed."""
    set_other_timezone("UTC") # CI runs on UTC

    expected_spec_md_path = DIR_PROJECT_ROOT / "docs" / "_generated" / "openapi.md"
    new_spec_md_path = DIR_TESTDATA / "openapi-new.md"

    with expected_spec_md_path.open("r", encoding="utf-8", newline=None) as f_expected:
        expected_spec_md = f_expected.read()

    # Patch get_config and import within guard to patch global variables within the eos module.
    with patch("akkudoktoreos.core.coreabc.get_config", return_value=config_eos):
        # Ensure the script works correctly as part of a package
        root_dir = Path(__file__).resolve().parent.parent
        sys.path.insert(0, str(root_dir))
        from scripts import generate_openapi_md

        spec_md = generate_openapi_md.generate_openapi_md()

    with new_spec_md_path.open("w", encoding="utf-8", newline="\n") as f_new:
        f_new.write(spec_md)

    try:
        assert _comparable_openapi_md(spec_md) == _comparable_openapi_md(expected_spec_md)
    except AssertionError as e:
        pytest.fail(
            f"Expected {new_spec_md_path} to equal {expected_spec_md_path}.\n"
            + f"If ok: `make gen-docs` or `cp {new_spec_md_path} {expected_spec_md_path}`\n"
        )


@pytest.mark.skipif(GITHUB_ACTIONS == "true", reason="Skipped on GitHub Actions - TODO!")
def test_config_md_current(config_eos, set_other_timezone):
    """Verify the generated configuration markdown hasn´t changed."""
    set_other_timezone("UTC") # CI runs on UTC

    assert DIR_DOCS_GENERATED.exists()

    # Remove any leftover files from last run
    if DIR_TEST_GENERATED.exists():
        shutil.rmtree(DIR_TEST_GENERATED)

    # Ensure test dir exists
    DIR_TEST_GENERATED.mkdir(parents=True, exist_ok=True)

    # Patch get_config and import within guard to patch global variables within the eos module.
    with patch("akkudoktoreos.core.coreabc.get_config", return_value=config_eos):
        # Ensure the script works correctly as part of a package
        root_dir = Path(__file__).resolve().parent.parent
        sys.path.insert(0, str(root_dir))
        from scripts import generate_config_md

        # Get all the top level fields
        field_names = sorted(config_eos.__class__.model_fields.keys())

        # Create the file paths
        expected = [ DIR_DOCS_GENERATED / "config.md", DIR_DOCS_GENERATED / "configexample.md", ]
        tested = [ DIR_TEST_GENERATED / "config.md", DIR_TEST_GENERATED / "configexample.md", ]
        for field_name in field_names:
            file_name = f"config{field_name.lower()}.md"
            expected.append(DIR_DOCS_GENERATED / file_name)
            tested.append(DIR_TEST_GENERATED / file_name)

        # Create test files
        try:
            config_eos._force_documentation_mode = True
            config_md = generate_config_md.generate_config_md(tested[0], config_eos)
        finally:
            config_eos._force_documentation_mode = False

    # Check test files are the same as the expected files
    for i, expected_path in enumerate(expected):
        tested_path = tested[i]

        with expected_path.open("r", encoding="utf-8", newline=None) as f_expected:
            expected_config_md = f_expected.read()
        with tested_path.open("r", encoding="utf-8", newline=None) as f_expected:
            tested_config_md = f_expected.read()

        try:
            assert tested_config_md == expected_config_md
        except AssertionError as e:
            pytest.fail(
                f"Expected {tested_path} to equal {expected_path}.\n"
                + f"If ok: `make gen-docs` or `cp {tested_path} {expected_path}`\n"
            )