Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

5.9 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""장기 heal 의 비차단 계약 (plan sprite-gen/long-op-loading-ux).

엔진 갱신 후 첫 /api/run 이 heal 을 요청 안에서 동기로 돌리면 첫 탭이 진행률
UI 없이 빈 화면으로 수십 분 멈춘다 (회귀 2026-07-20). maybe_heal 은 heal 을
백그라운드로 발사하고 그레이스만 대기하며 busy 여부만 반환한다. heal 리포트의
소비자는 take_heal_report() 하나 — /api/run 성공 스냅샷 경로 — 뿐이다.
/api/progress 폴링·다운로드가 heal 완료 직후 먼저 호출돼도 리포트가 유실되지
않는다 (validator validator 재현 결함의 회귀 가드, 단일 소비자 원칙).
"""

from __future__ import annotations

import time
from pathlib import Path

import pytest

ROOT = Path(__file__).resolve().parents[2]

import sprite_gen.serve.serve_curation as serve_curation  # noqa: E402


@pytest.fixture(autouse=True)
def _reset_heal_state():
    serve_curation._heal_state["thread"] = None
    serve_curation._heal_state["pending_report"] = None
    serve_curation._heal_state["failed_attempt"] = None
    yield
    thread = serve_curation._heal_state["thread"]
    if thread is not None:
        thread.join(timeout=10)
    serve_curation._heal_state["thread"] = None
    serve_curation._heal_state["pending_report"] = None
    serve_curation._heal_state["failed_attempt"] = None


def _walk_report(run_dir):
    return {"healed": ["walk"], "kept_stale": [], "failed": [], "notes": []}


def _noop_report(run_dir):
    return {"healed": [], "kept_stale": [], "failed": [], "notes": []}


@pytest.mark.slow
def test_progress_poll_never_steals_the_heal_report(tmp_path: Path, monkeypatch) -> None:
    """validator validator 재현 결함의 회귀 가드: 장기 heal 완료 직후
    /api/progress(또는 다운로드) 역할의 maybe_heal 이 먼저 호출돼도 리포트는
    남아 있어야 하고, /api/run 역할의 take_heal_report 가 정확히 1회 가져간다."""
    release = {"at": time.monotonic() + 1.7}

    def slow_heal(run_dir):
        while time.monotonic() < release["at"]:
            time.sleep(0.05)
        return _walk_report(run_dir)

    monkeypatch.setattr(serve_curation, "heal_run", slow_heal)
    started = time.monotonic()
    assert serve_curation.maybe_heal(tmp_path) is True  # 장기 heal — busy 즉답
    # 그레이스(1.5s) + 여유 안에 응답해야 첫 탭이 로딩 UI 를 본다
    assert time.monotonic() - started < serve_curation._HEAL_GRACE_SECONDS + 1.0
    serve_curation._heal_state["thread"].join(timeout=10)

    # 완료 직후: 트리 폴링/다운로드 경로가 먼저 도착하는 시나리오
    monkeypatch.setattr(serve_curation, "heal_run", _noop_report)
    assert serve_curation.maybe_heal(tmp_path) is False  # /api/progress 역할 — 미소비
    assert serve_curation.maybe_heal(tmp_path) is False  # download 역할 — 미소비

    # 그 다음 /api/run 성공 경로가 리포트를 정확히 1회 가져간다
    report = serve_curation.take_heal_report()
    assert report is not None and report["healed"] == ["walk"]
    assert serve_curation.take_heal_report() is None


def test_fresh_heal_stays_synchronous(tmp_path: Path, monkeypatch) -> None:
    monkeypatch.setattr(serve_curation, "heal_run", _noop_report)
    started = time.monotonic()
    busy = serve_curation.maybe_heal(tmp_path)
    assert busy is False
    assert time.monotonic() - started < 1.0
    assert serve_curation.take_heal_report() is None  # no-op 리포트는 첨부하지 않는다


def test_heal_failure_is_observable_not_fatal(tmp_path: Path, monkeypatch) -> None:
    def broken_heal(run_dir):
        raise SystemExit("raw missing")

    monkeypatch.setattr(serve_curation, "heal_run", broken_heal)
    busy = serve_curation.maybe_heal(tmp_path)
    if busy:  # 스케줄링상 그레이스를 넘겼으면 완주 대기
        thread = serve_curation._heal_state["thread"]
        if thread is not None:
            thread.join(timeout=10)
    report = serve_curation.take_heal_report()
    assert report is not None
    assert any("heal skipped" in note for note in report["notes"])
    assert serve_curation.maybe_heal(tmp_path) is False


def test_failed_heal_is_not_retried_until_inputs_change(tmp_path: Path, monkeypatch) -> None:
    """결정론적 검증 실패를 폴링마다 재실행해 80%→0%가 반복되면 안 된다."""
    request = tmp_path / "sprite-request.json"
    request.write_text("{}\n", encoding="utf-8")
    calls = []

    def failed_heal(run_dir):
        calls.append(run_dir)
        return {"healed": [], "kept_stale": [], "failed": ["walk"],
                "notes": ["validation failed"]}

    monkeypatch.setattr(serve_curation, "heal_run", failed_heal)
    assert serve_curation.maybe_heal(tmp_path) is False
    assert len(calls) == 1
    assert serve_curation.maybe_heal(tmp_path) is False
    assert serve_curation.maybe_heal(tmp_path) is False
    assert len(calls) == 1

    request.write_text('{"changed": true}\n', encoding="utf-8")
    assert serve_curation.maybe_heal(tmp_path) is False
    assert len(calls) == 2


def test_existing_failure_suppresses_retry_after_server_restart(tmp_path: Path, monkeypatch) -> None:
    """extract-failure 증거는 프로세스 재기동 뒤에도 같은 시도를 막는다."""
    request = tmp_path / "sprite-request.json"
    request.write_text("{}\n", encoding="utf-8")
    revision = serve_curation._heal_attempt_key(tmp_path)[0]
    (tmp_path / "extract-failure.json").write_text(
        '{"ok": false, "engine_revision": "' + revision
        + '", "rows": [{"state": "walk", "ok": false}]}\n', encoding="utf-8")
    called = []
    monkeypatch.setattr(serve_curation, "heal_run", lambda run_dir: called.append(run_dir))

    assert serve_curation.maybe_heal(tmp_path) is False
    assert called == []
    report = serve_curation.take_heal_report()
    assert report is not None and report["failed"] == ["walk"]