test_migrate_config.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_diag/test_migrate_config.py
 
"""
Purpose
-------
OI-508 / FS-515 regression coverage — ``debug_config.json`` schema
bridge. :func:`_get_debug_domain_map` must normalise both the legacy v1
``domains:`` and the current v2 ``DEBUG_LEVELS:`` shape into a single
map shape; :func:`migrate_config` must upgrade v1 -> v2 in-place with a
``.bk`` backup and be idempotent on already-v2 files. The
``oct diag migrate-config`` CLI command must expose the same behaviour
and print a helpful summary.
 
Responsibilities
----------------
- Verify legacy v1 ``domains:`` config normalises into v2 ``DEBUG_LEVELS``.
- Verify ``migrate-config`` creates a ``.bk`` backup and is idempotent.
- Verify ``validate-config`` emits a WARNING on legacy schema with a
  ``migrate-config`` hint.
 
Diagnostics
-----------
Domain: DIAG-TESTS
Levels:
    L2 — test lifecycle
    L3 — assertion details
    L4 — deep tracing
 
Contracts
---------
- Legacy ``domains:`` config normalises into a v2 ``DEBUG_LEVELS`` map.
- Running migrate-config writes ``<path>.bk`` with the original content.
- Running migrate-config twice is a no-op (no backup clobber).
- ``validate-config`` emits a WARNING (not ERROR) on legacy schema and
  references the ``migrate-config`` hint.
"""
 
from __future__ import annotations
 
import json
from pathlib import Path
 
import pytest
from click.testing import CliRunner
 
from oct.cli import cli
from oct.diag.oct_diag import (
    CURRENT_SCHEMA_VERSION,
    _get_debug_domain_map,
    migrate_config,
    validate_config,
)
 
 
_LEGACY_FULL = {
    "_schema_version": "1.0",
    "domains": {
        "ALPHA": {"level": 2, "color": "red"},
        "BETA": {"level": 3, "color": "blue"},
    },
    "global_settings": {"mode": "dev"},
}
 
_LEGACY_SHORT = {"domains": {"TEST": 2}}
 
_V2_FULL = {
    "_schema_version": "2.0",
    "DEBUG_LEVELS": {
        "ALPHA": {"level": 2, "color": "red"},
    },
    "global_settings": {"mode": "dev"},
}
 
 
def _write(path: Path, data: dict) -> Path:
    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
    return path
 
 
def test_get_debug_domain_map_v2_not_legacy():
    """v2 ``DEBUG_LEVELS`` → is_legacy is False."""
    m, legacy = _get_debug_domain_map(_V2_FULL)
    assert legacy is False
    assert m["ALPHA"]["level"] == 2
 
 
def test_get_debug_domain_map_v1_is_legacy():
    """v1 ``domains`` → is_legacy is True; shape matches v2."""
    m, legacy = _get_debug_domain_map(_LEGACY_FULL)
    assert legacy is True
    assert m["ALPHA"] == {"level": 2, "color": "red"}
    assert m["BETA"]["color"] == "blue"
 
 
def test_get_debug_domain_map_short_form_normalised():
    """v1 short form ``{"TEST": 2}`` → ``{"TEST": {"level": 2, "color": "default"}}``."""
    m, legacy = _get_debug_domain_map(_LEGACY_SHORT)
    assert legacy is True
    assert m["TEST"] == {"level": 2, "color": "default"}
 
 
def test_migrate_config_upgrades_v1_to_v2(tmp_path: Path):
    """OI-508: migrate writes v2 schema in-place and creates .bk backup."""
    cfg = _write(tmp_path / "debug_config.json", _LEGACY_FULL)
    original = cfg.read_text(encoding="utf-8")
    result = migrate_config(cfg)
    backup = cfg.with_suffix(".json.bk")
 
    assert result["_schema_version"] == CURRENT_SCHEMA_VERSION
    assert "DEBUG_LEVELS" in result and "domains" not in result
    on_disk = json.loads(cfg.read_text(encoding="utf-8"))
    assert on_disk["DEBUG_LEVELS"]["ALPHA"]["color"] == "red"
    assert backup.read_text(encoding="utf-8") == original
 
 
def test_migrate_config_idempotent_on_v2(tmp_path: Path):
    """OI-508: running migrate on an already-v2 file is a no-op."""
    cfg = _write(tmp_path / "debug_config.json", _V2_FULL)
    before = cfg.read_text(encoding="utf-8")
    migrate_config(cfg)
    after = cfg.read_text(encoding="utf-8")
    assert before == after
    assert not cfg.with_suffix(".json.bk").exists()
 
 
def test_migrate_config_dry_run_never_writes(tmp_path: Path):
    """OI-508: dry_run returns the target shape without touching disk."""
    cfg = _write(tmp_path / "debug_config.json", _LEGACY_FULL)
    before = cfg.read_text(encoding="utf-8")
    new = migrate_config(cfg, dry_run=True)
    assert new["_schema_version"] == CURRENT_SCHEMA_VERSION
    assert cfg.read_text(encoding="utf-8") == before
    assert not cfg.with_suffix(".json.bk").exists()
 
 
def test_validate_config_warns_on_legacy_schema(tmp_path: Path):
    """OI-508: legacy schema → WARNING with migration hint; no hard ERROR."""
    (tmp_path / "oc_diagnostics").mkdir()
    _write(tmp_path / "oc_diagnostics" / "debug_config.json", _LEGACY_FULL)
    issues = validate_config(tmp_path)
    legacy_warnings = [i for i in issues if "legacy v1 schema" in i]
    assert legacy_warnings, issues
    assert "migrate-config" in legacy_warnings[0]
    assert not any(i.startswith("ERROR") for i in issues)
 
 
def test_cli_migrate_config_round_trip(tmp_path: Path):
    """OI-508: ``oct diag migrate-config PATH`` migrates an arbitrary file."""
    cfg = _write(tmp_path / "legacy.json", {"domains": {"TEST": 2}})
    runner = CliRunner()
    result = runner.invoke(cli, ["diag", "migrate-config", str(cfg)])
    assert result.exit_code == 0, result.output
    on_disk = json.loads(cfg.read_text(encoding="utf-8"))
    assert on_disk["_schema_version"] == CURRENT_SCHEMA_VERSION
    assert on_disk["DEBUG_LEVELS"]["TEST"]["level"] == 2
    assert cfg.with_suffix(".json.bk").is_file()