294. Ручной цикл загрузки ROM в core_validator

Добавление ручного цикла загрузки ROM core_validator.py.

Урок 294 из 356 · tests/chapter_08_manual_main/test_294_manual_core_validator_rom_loop.py

Файл для создания в корневой папке

core_validator.py

Зачем нужен этот шаг

Теперь у эмулятора достаточно поведения для выживания при запуске, чтобы сделать полезной ручную точку входа для разработчика:

iNES parsing
Mapper000/NROM
CPU reset vector
Console frame stepping
APU/audio no-op for out-of-scope audio
OAMDMA $4014
controller port 1 through $4016

Этот шаг делает core_validator.py ручным местом для проверки локального ROM и поддержания работы эмулятора покадрово без pygame.

Почему core_validator.py, а не main.py? main.py зарезервирован для визуального запускателя на pygame. core_validator.py остаётся небольшим невизуальным запускателем, полезным при отладке ядра эмулятора без окна или цикла событий фронтенда.

Важное юридическое правило/правило для тестов

Репозиторий учебного курса не должен включать коммерческие файлы ROM. Автоматические тесты не должны требовать MarioBros.nes. Разработчик, желающий вручную запустить Mario Bros., должен предоставить собственную легальную локальную копию:

MarioBros.nes

Эталонный хеш, использованный при разработке курса [Mario Bros. (World).nes]:

MD5 5d7bcc400a2fb5fa27346da345d3bb62  MarioBros.nes
SHA1 314b6e46e814f955b52ac954f67dab849582fe77

Этот хеш является лишь ручным ориентиром. Тесты не должны требовать этот файл или этот точный хеш, поскольку у пользователей могут быть другие легальные дампы/ревизии.

Пример предполагаемой реализации

from pathlib import Path

from emulator.bus.cpu_bus import CpuBus
from emulator.cartridge.cartridge import Cartridge
from emulator.console import Console
from emulator.cpu.cpu import CPU


ROM_PATH = Path("MarioBros.nes")
debug_mode = True


def main() -> None:
    if not ROM_PATH.exists():
        raise FileNotFoundError(
            "MarioBros.nes not found. Provide your own legal local copy. "
            "This file is intentionally not included in the tutorial repository."
        )

    cartridge = Cartridge.from_ines_bytes(ROM_PATH.read_bytes())

    cpu_bus = CpuBus(cartridge=cartridge)
    cpu = CPU(cpu_bus)
    console = Console(cpu=cpu, ppu=cpu_bus.ppu)

    cpu.reset()

    print(f"Loaded {ROM_PATH}")
    print(f"CPU reset PC = ${cpu.pc:04X}")
    print("Starting frame loop. Press Ctrl+C to stop.")

    try:
        while True:
            executed = console.step_until_next_frame()

            if debug_mode:
                print(
                    f"frame={console.ppu.frame} "
                    f"pc=${cpu.pc:04X} "
                    f"instructions={executed}"
                )
    except KeyboardInterrupt:
        print("

Stopped by user.")

if __name__ == "__main__":
    main()

Ручная команда

uv run python core_validator.py

Ожидаемое ручное поведение

Эта команда не завершается сама по себе. Она продолжает выполнять кадры, пока разработчик не нажмёт Ctrl+C. Это ожидаемо, поскольку core_validator.py — это ручной, длительно работающий инструмент выполнения ROM, а не автоматический тест.

Почему этот тест не вызывает main()

core_validator.py — это ручной бесконечный цикл. Автоматические тесты должны оставаться конечными и не должны требовать локальный коммерческий файл ROM. Эти тесты проверяют только структуру.

Почему debug_mode проверяется только на существование: debug_mode — это ручной регулятор управления. Будущие шаги курса могут устанавливать его в True или False в зависимости от того, что изучается. Тесты не должны фиксировать это значение.

Вне рамок этого шага

отображение pygame
сопоставление клавиш
закоммиченные ROM-файлы для тестов
проверка того, что core_validator.py даёт корректный игровой процесс
вызов main() из pytest

Запустить этот урок

uv run pytest tests/chapter_08_manual_main/test_294_manual_core_validator_rom_loop.py -v

Пример реализации

Пример предполагаемой реализации

from pathlib import Path

from emulator.bus.cpu_bus import CpuBus
from emulator.cartridge.cartridge import Cartridge
from emulator.console import Console
from emulator.cpu.cpu import CPU


ROM_PATH = Path("MarioBros.nes")
debug_mode = True


def main() -> None:
    if not ROM_PATH.exists():
        raise FileNotFoundError(
            "MarioBros.nes not found. Provide your own legal local copy. "
            "This file is intentionally not included in the tutorial repository."
        )

    cartridge = Cartridge.from_ines_bytes(ROM_PATH.read_bytes())

    cpu_bus = CpuBus(cartridge=cartridge)
    cpu = CPU(cpu_bus)
    console = Console(cpu=cpu, ppu=cpu_bus.ppu)

    cpu.reset()

    print(f"Loaded {ROM_PATH}")
    print(f"CPU reset PC = ${cpu.pc:04X}")
    print("Starting frame loop. Press Ctrl+C to stop.")

    try:
        while True:
            executed = console.step_until_next_frame()

            if debug_mode:
                print(
                    f"frame={console.ppu.frame} "
                    f"pc=${cpu.pc:04X} "
                    f"instructions={executed}"
                )
    except KeyboardInterrupt:
        print("

Показать код тестаtest_294_manual_core_validator_rom_loop.py

import inspect
from pathlib import Path

import core_validator


def test_core_validator_exists_and_exposes_manual_entry_point_variables():
    """
    Objective:
    core_validator.py exposes the basic manual-run configuration without requiring
    tests to execute the infinite loop.
    """
    assert Path("core_validator.py").exists()
    assert hasattr(core_validator, "ROM_PATH")
    assert hasattr(core_validator, "debug_mode")
    assert hasattr(core_validator, "main")
    assert callable(core_validator.main)


def test_core_validator_rom_path_points_to_local_mariobros_file_name_without_requiring_it():
    """
    Objective:
    core_validator.py documents the expected local ROM filename, but pytest must
    not require that file to exist.
    """
    assert isinstance(core_validator.ROM_PATH, Path)
    assert core_validator.ROM_PATH.name == "MarioBros.nes"


def test_core_validator_debug_mode_exists_but_test_does_not_freeze_value():
    """
    Objective:
    debug_mode is a manual/developer knob. The test verifies the knob exists but
    does not assert True or False, so future tutorial steps may change it.
    """
    assert hasattr(core_validator, "debug_mode")


def test_core_validator_uses_real_rom_boot_construction_path():
    """
    Objective:
    core_validator.py should use the same ownership path as the emulator architecture:

        Cartridge -> CpuBus -> CPU + PPU -> Console
    """
    source = inspect.getsource(core_validator.main)

    assert "Cartridge.from_ines_bytes" in source
    assert "CpuBus(cartridge=cartridge)" in source
    assert "CPU(cpu_bus)" in source
    assert "Console(cpu=cpu, ppu=cpu_bus.ppu)" in source


def test_core_validator_uses_cpu_reset_vector_before_running_frames():
    """
    Objective:
    core_validator.py must boot through the ROM reset vector instead of forcing PC
    manually.
    """
    source = inspect.getsource(core_validator.main)

    assert "cpu.reset()" in source
    assert "cpu.pc = 0x8000" not in source


def test_core_validator_steps_by_frame_not_single_instruction_loop():
    """
    Objective:
    The manual loop should use the frame-level Console helper introduced earlier.
    """
    source = inspect.getsource(core_validator.main)

    assert "console.step_until_next_frame()" in source


def test_core_validator_has_keyboard_interrupt_escape_for_infinite_manual_loop():
    """
    Objective:
    An unlimited manual loop is acceptable only if the user can stop it cleanly
    with Ctrl+C.
    """
    source = inspect.getsource(core_validator.main)

    assert "while True" in source
    assert "KeyboardInterrupt" in source
    assert "Stopped by user" in source


def test_core_validator_has_main_guard_so_importing_does_not_start_loop():
    """
    Objective:
    Importing core_validator.py from pytest must not start the manual ROM loop.
    """
    source = Path("core_validator.py").read_text()

    assert 'if __name__ == "__main__"' in source
    assert "main()" in source


def test_core_validator_does_not_import_pygame():
    """
    Objective:
    core_validator.py is intentionally non-visual. Pygame belongs in main.py or
    other manual/frontend entry points.
    """
    source = Path("core_validator.py").read_text()

    assert "import pygame" not in source

Тестовые функции (9)

test_core_validator_exists_and_exposes_manual_entry_point_variables
test_core_validator_rom_path_points_to_local_mariobros_file_name_without_requiring_it
test_core_validator_debug_mode_exists_but_test_does_not_freeze_value
test_core_validator_uses_real_rom_boot_construction_path
test_core_validator_uses_cpu_reset_vector_before_running_frames
test_core_validator_steps_by_frame_not_single_instruction_loop
test_core_validator_has_keyboard_interrupt_escape_for_infinite_manual_loop
test_core_validator_has_main_guard_so_importing_does_not_start_loop
test_core_validator_does_not_import_pygame