test: separate manual e2e tests and add one-to-one unit test structure

Author: 0xWelt

autowsgr/ops/README.md

@@ -15,7 +15,7 @@
 - cook
 - reward
 
-每个模块只有少量功能，全部做 e2e 测试即可。测试脚本统一放在 `testing/ops/` 下。
+每个模块只有少量功能，全部做 e2e 测试即可。测试脚本统一放在 `tests/manual/ops/` 下。
 
 | 模块 | 功能 | 状态 |
 |------|------|------|
@@ -36,31 +36,31 @@
 ### startup 测试 ✅
 
 ```bash
-python testing/ops/startup.py
-python testing/ops/startup.py 127.0.0.1:16384
+python tests/ops/startup.py
+python tests/ops/startup.py 127.0.0.1:16384
 ```
 
 ### normal_fight 测试 ✅
 
 ```bash
-python testing/ops/normal_fight.py
-python testing/ops/normal_fight.py 127.0.0.1:16384 3  # 指定设备和次数
-python testing/ops/normal_fight.py --plan examples/plans/normal_fight/7-46SS-all.yaml
+python tests/ops/normal_fight.py
+python tests/ops/normal_fight.py 127.0.0.1:16384 3  # 指定设备和次数
+python tests/ops/normal_fight.py --plan examples/plans/normal_fight/7-46SS-all.yaml
 ```
 
 ### campaign 测试 ✅
 
 ```bash
-python testing/ops/campaign.py                              # 困难驱逐 x1
-python testing/ops/campaign.py 127.0.0.1:16384 困难航母 3  # 指定战役和次数
-python testing/ops/campaign.py "" 简单驱逐 2
+python tests/ops/campaign.py                              # 困难驱逐 x1
+python tests/ops/campaign.py 127.0.0.1:16384 困难航母 3  # 指定战役和次数
+python tests/ops/campaign.py "" 简单驱逐 2
 ```
 
 ### expedition 测试 ✅
 
 ```bash
-python testing/ops/expedition.py
-python testing/ops/expedition.py 127.0.0.1:16384
+python tests/ops/expedition.py
+python tests/ops/expedition.py 127.0.0.1:16384
 ```
 
 ### decisive 测试 ❌
@@ -70,24 +70,24 @@ python testing/ops/expedition.py 127.0.0.1:16384
 ### exercise 测试 ✅
 
 ```bash
-python testing/ops/exercise.py --fleet 1
-python testing/ops/exercise.py --fleet 1 --rival 3
+python tests/ops/exercise.py --fleet 1
+python tests/ops/exercise.py --fleet 1 --rival 3
 ```
 
 ### build 测试 ❌
 
 ```bash
-python testing/ops/build.py
-python testing/ops/build.py 127.0.0.1:16384
+python tests/ops/build.py
+python tests/ops/build.py 127.0.0.1:16384
 ```
 
 ### repair 测试 ❌
 
 #### 修复第一艘舰船 ✅
 
 ```bash
-python testing/ops/repair.py
-python testing/ops/repair.py 127.0.0.1:16384
+python tests/ops/repair.py
+python tests/ops/repair.py 127.0.0.1:16384
 ```
 
 #### 按照名称修复舰船 ❌
@@ -97,21 +97,21 @@ python testing/ops/repair.py 127.0.0.1:16384
 ### destroy 测试 ✅
 
 ```bash
-python testing/ops/destroy.py
-python testing/ops/destroy.py 127.0.0.1:16384
+python tests/ops/destroy.py
+python tests/ops/destroy.py 127.0.0.1:16384
 ```
 
 ### cook 测试 ✅
 
 ```bash
-python testing/ops/cook.py
-python testing/ops/cook.py 127.0.0.1:16384 2
+python tests/ops/cook.py
+python tests/ops/cook.py 127.0.0.1:16384 2
 ```
 
 ### reward 测试 ✅
 
 ```bash
-python testing/ops/reward.py
-python testing/ops/reward.py 127.0.0.1:16384
-python testing/ops/reward.py 127.0.0.1:16384 --auto
+python tests/ops/reward.py
+python tests/ops/reward.py 127.0.0.1:16384
+python tests/ops/reward.py 127.0.0.1:16384 --auto
 ```

docs/developer/test_pkg.md

@@ -4,11 +4,11 @@
 
 `test_pkg/` 是本地私有的视觉/OCR 回归测试集合，**不纳入版本控制**（已在 `.gitignore` 中排除），也不随 PyPI 包发布。
 
-它与 `testing/` 的分工：
+它与 `tests/` 的分工：
 
 | 目录 | 作用 | 版本控制 | 框架 |
 |------|------|----------|------|
-| `testing/` | 单元测试、集成测试 | 是 | pytest |
+| `tests/` | 单元测试、集成测试 | 是 | pytest |
 | `test_pkg/` | 视觉/OCR 回归测试（含截图） | 否（本地私有） | 独立脚本 |
 
 `test_pkg/` 中的测试图片来自游戏实机截图，体积较大且可能涉及版权，因此不适合入库。

tests/__init__.py

@@ -0,0 +1,24 @@
+"""测试公共 fixtures。"""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def fixtures_dir() -> Path:
+    """测试数据目录。"""
+    return Path(__file__).parent / 'fixtures'
+
+
+@pytest.fixture
+def tmp_yaml(tmp_path: Path) -> Callable[[str, str], Path]:
+    """创建临时 YAML 文件的工厂 fixture。"""
+
+    def _factory(name: str, content: str) -> Path:
+        p = tmp_path / name
+        p.write_text(content, encoding='utf-8')
+        return p
+
+    return _factory

tests/conftest.py

@@ -0,0 +1,9 @@
+"""游戏操作 (ops) 层的测试。
+
+包含两类测试：
+
+| 文件 | 类型 | 运行方式 | 需要真实设备 |
+|---|---|---|---|
+| `test_unit.py` | 单元测试（mock） | `pytest` | 否 |
+| `e2e.py` | 端到端测试（真实设备） | 直接执行 | **是** |
+"""

tests/manual/__init__.py

@@ -0,0 +1,76 @@
+"""ops 端到端测试公共工具。
+
+提供 :func:`launch_for_test` 供各 ops 测试脚本调用，替代手动的
+``ConfigManager.load() → ADBController → GameContext → ensure_game_ready``
+流程，与生产环境的 :func:`autowsgr.scheduler.launcher.launch` 行为对齐。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from autowsgr.context import GameContext
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def launch_for_test(
+    serial: str | None,
+    log_dir: Path,
+    log_level: str = 'DEBUG',
+    *,
+    with_ocr: bool = False,
+) -> GameContext:
+    """为 ops 端到端测试准备就绪的 GameContext。
+
+    加载配置 → 覆盖日志目录/级别 → 连接设备 →
+    构建 GameContext → ensure_game_ready → 返回就绪上下文。
+
+    与 :func:`autowsgr.scheduler.launcher.launch` 的区别：
+
+    * 使用测试专用的 *log_dir* 覆盖配置中的日志目录。
+    * 默认 ``with_ocr=False`` 跳过 OCR 初始化（适用于不需要 OCR 的简单 ops）。
+
+    Parameters
+    ----------
+    serial:
+        ADB 设备序列号；为 ``None`` 时沿用配置文件或自动检测。
+    log_dir:
+        测试专用日志目录（覆盖配置文件 ``log.dir``）。
+    log_level:
+        日志级别，默认 ``"DEBUG"``。
+    with_ocr:
+        是否初始化 OCR 引擎（决战等需要 OCR 的场景置 ``True``）。
+
+    Returns
+    -------
+    GameContext
+        ``ctx.ctrl`` 已连接、游戏已在主页面。
+        若 ``with_ocr=True`` 则 ``ctx.ocr`` 也已初始化。
+    """
+    from autowsgr.infra.logger import setup_logger
+    from autowsgr.scheduler.launcher import Launcher
+
+    launcher = Launcher()
+    cfg = launcher.load_config()
+
+    # 以测试指定 log_dir 覆盖配置中的日志目录
+    channels = cfg.log.effective_channels or None
+    setup_logger(log_dir=log_dir, level=log_level, save_images=True, channels=channels)
+
+    # 以命令行指定的 serial 覆盖配置
+    if serial is not None:
+        new_emu = cfg.emulator.model_copy(update={'serial': serial})
+        launcher.set_config(cfg.model_copy(update={'emulator': new_emu}))
+
+    launcher.connect()
+
+    if with_ocr:
+        ctx = launcher.build_context()
+    else:
+        ctx = GameContext(ctrl=launcher.ctrl, config=launcher.config)
+        launcher.ensure_ready(ctx)
+
+    return ctx

tests/manual/ops/__init__.py

@@ -0,0 +1,73 @@
+"""建造收取 (collect_built_ships) 端到端测试。
+
+用法::
+
+    python tests/manual/ops/build.py
+    python tests/manual/ops/build.py 127.0.0.1:16384
+
+无页面前置要求 — collect_built_ships() 内部通过 goto_page() 自动导航。
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+
+try:
+    if hasattr(sys.stdout, 'reconfigure'):
+        sys.stdout.reconfigure(encoding='utf-8', errors='replace')  # ty: ignore[call-non-callable]
+        sys.stderr.reconfigure(encoding='utf-8', errors='replace')  # ty: ignore[call-non-callable]
+except Exception:  # noqa: S110
+    pass
+from loguru import logger
+
+from tests.manual.ops._framework import launch_for_test
+
+
+_STEPS = [
+    '1. 连接设备',
+    "2. 调用 collect_built_ships(ctrl, build_type='ship', allow_fast_build=False)",
+    '3. 打印收取数量',
+]
+
+
+def main() -> None:
+    serial = sys.argv[1] if len(sys.argv) > 1 else None
+
+    print('=' * 60)
+    print('  建造收取 (collect_built_ships) E2E 测试')
+    print('=' * 60)
+    print()
+    print('  测试步骤:')
+    for s in _STEPS:
+        print(f'    {s}')
+    print()
+    input('  按 Enter 开始运行...')
+    print()
+
+    try:
+        ctx = launch_for_test(serial, log_dir=Path('logs/e2e/build'))
+        ctrl = ctx.ctrl
+        logger.info(f'已连接: {ctrl.serial}')
+        print(f'  [OK] 已连接: {ctrl.serial}')
+
+        from autowsgr.ops.build import collect_built_ships
+
+        result = collect_built_ships(ctx, build_type='ship', allow_fast_build=False)
+        logger.info(f'collect_built_ships() 返回: {result}')
+        print(f'  [OK] collect_built_ships() = {result} 艘')
+    except Exception as exc:
+        logger.opt(exception=True).error(f'测试失败: {exc}')
+        print(f'  [FAIL] {exc}')
+        sys.exit(1)
+
+    ctrl.disconnect()
+    print()
+    print('  [OK] 建造收取测试通过')
+
+
+if __name__ == '__main__':
+    main()