mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-10-12 17:21:55 +00:00
229 lines
9.1 KiB
Python
229 lines
9.1 KiB
Python
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"
|
||
)
|