tests/test_02_reset.py

"""
测试模块 02 —— reset() 行为

需求覆盖
--------
* R1：seed 参数控制可复现性
* R2：三通道观测编码语义
* R4：reset 返回 (obs, info)
* RF1：BFS 连通性保证（起终点强制可达）
* RF3：info 新增字段初值

对应用例
--------
TC-03, TC-04, TC-05, TC-06, TC-07
"""

from __future__ import annotations

import numpy as np
import pytest

from maze_env import MazeEnv


class TestReset:
    """验证 reset() 的返回值格式、通道语义与 info 初始值。"""

    # ------------------------------------------------------------------ #
    # TC-03  返回值格式                                                     #
    # ------------------------------------------------------------------ #

    @pytest.mark.unit
    def test_reset_obs_shape(self, env_zero: MazeEnv) -> None:
        """TC-03a：reset() 返回 obs，形状为 (4, N, N)。

        输入:  env_zero.reset()，seed=0
        期望:  obs.shape == (4, 6, 6)
        实测:  解包 reset() 返回值
        """
        obs, _ = env_zero.reset()
        assert obs.shape == (4, 6, 6)

    @pytest.mark.unit
    def test_reset_obs_dtype(self, env_zero: MazeEnv) -> None:
        """TC-03b：reset() 返回 obs，dtype 为 float32。

        输入:  env_zero.reset()
        期望:  obs.dtype == float32
        """
        obs, _ = env_zero.reset()
        assert obs.dtype == np.float32

    @pytest.mark.unit
    def test_reset_info_keys(self, env_zero: MazeEnv) -> None:
        """TC-03c：info 包含所有规定字段。

        输入:  env_zero.reset()
        期望:  info.keys() 包含五个字段
        """
        _, info = env_zero.reset()
        required = {"agent_pos", "goal_pos", "step_count",
                    "hit_wall_count", "success"}
        assert required.issubset(info.keys())

    # ------------------------------------------------------------------ #
    # TC-04  边界与起终点                                                   #
    # ------------------------------------------------------------------ #

    @pytest.mark.unit
    def test_border_walls(self) -> None:
        """TC-04a：四条边界全部为墙（wall_map 四边均为 1）。

        输入:  MazeEnv(grid_size=8, obstacle_density=0.0, seed=0).reset()
        期望:  wall[0,:], wall[-1,:], wall[:,0], wall[:,-1] 全为 1.0
        实测:  obs[0]（墙壁通道）各边切片
        """
        env = MazeEnv(grid_size=8, obstacle_density=0.0, seed=0)
        obs, _ = env.reset()
        wall = obs[0]
        assert np.all(wall[0, :]  == 1.0), "上边界应全为墙"
        assert np.all(wall[-1, :] == 1.0), "下边界应全为墙"
        assert np.all(wall[:, 0]  == 1.0), "左边界应全为墙"
        assert np.all(wall[:, -1] == 1.0), "右边界应全为墙"

    @pytest.mark.unit
    def test_start_goal_not_wall(self) -> None:
        """TC-04b：起点 (1,1) 与终点 (N-2,N-2) 永远不为墙。

        输入:  MazeEnv(grid_size=8, obstacle_density=0.0, seed=0).reset()
        期望:  wall[1,1] == 0.0，wall[6,6] == 0.0
        实测:  obs[0] 对应坐标处的值
        """
        env = MazeEnv(grid_size=8, obstacle_density=0.0, seed=0)
        obs, _ = env.reset()
        N, wall = 8, obs[0]
        assert wall[1, 1]       == 0.0, "起点 (1,1) 不应为墙"
        assert wall[N-2, N-2]   == 0.0, "终点 (N-2,N-2) 不应为墙"

    # ------------------------------------------------------------------ #
    # TC-05  Agent 通道                                                     #
    # ------------------------------------------------------------------ #

    @pytest.mark.unit
    def test_agent_channel_position(self, env_zero: MazeEnv) -> None:
        """TC-05a：obs[1] 在 agent_pos 处为 1.0。

        输入:  env_zero.reset()，agent_pos=(1,1)
        期望:  obs[1][1,1] == 1.0
        实测:  obs[1][ar, ac]
        """
        obs, info = env_zero.reset()
        ar, ac = info["agent_pos"]
        assert obs[1, ar, ac] == 1.0

    @pytest.mark.unit
    def test_agent_channel_unique(self, env_zero: MazeEnv) -> None:
        """TC-05b：obs[1] 全图仅一个激活格（sum == 1.0）。

        输入:  env_zero.reset()
        期望:  obs[1].sum() == 1.0
        实测:  np.sum(obs[1])
        """
        obs, _ = env_zero.reset()
        assert float(obs[1].sum()) == 1.0

    # ------------------------------------------------------------------ #
    # TC-06  终点通道                                                       #
    # ------------------------------------------------------------------ #

    @pytest.mark.unit
    def test_goal_channel_position(self, env_zero: MazeEnv) -> None:
        """TC-06a：obs[2] 在 goal_pos 处为 1.0，grid=6 时 goal=(4,4)。

        输入:  env_zero.reset()
        期望:  obs[2][4,4] == 1.0，obs[2].sum() == 1.0
        实测:  obs[2][gr, gc] 及 sum
        """
        obs, info = env_zero.reset()
        gr, gc = info["goal_pos"]
        assert obs[2, gr, gc] == 1.0
        assert float(obs[2].sum()) == 1.0

    # ------------------------------------------------------------------ #
    # TC-07  info 初始值                                                    #
    # ------------------------------------------------------------------ #

    @pytest.mark.unit
    def test_info_initial_values(self, env_zero: MazeEnv) -> None:
        """TC-07：reset() 后 info 所有幕级统计量为初始值。

        输入:  env_zero.reset()
        期望:
          agent_pos == (1, 1)
          goal_pos  == (4, 4)（N=6 时 N-2=4）
          step_count     == 0
          hit_wall_count == 0
          success        == False
        实测:  info 字典各字段
        """
        _, info = env_zero.reset()
        assert info["agent_pos"]       == (1, 1)
        assert info["goal_pos"]        == (4, 4)
        assert info["step_count"]      == 0
        assert info["hit_wall_count"]  == 0
        assert info["success"]         is False


# ======================================================================
# TC-14  外部注入地图（options["wall_map"]）
# ======================================================================

class TestResetWallMapInjection:
    """验证 reset(options={'wall_map': ...}) 外部注入地图路径。"""

    @pytest.mark.unit
    def test_inject_wall_map_used(self) -> None:
        """TC-14a：注入自定义 wall_map 后，env._wall_map 与注入值一致。

        输入:  全零 6×6 wall_map（无障碍）
        期望:  env.wall_map 与注入值匹配
        实测:  np.array_equal
        """
        import numpy as np
        env = MazeEnv(grid_size=6, obstacle_density=0.0, seed=0)
        custom_map = np.zeros((6, 6), dtype=np.float32)
        # 添加边界墙（真实使用场景）
        custom_map[0, :] = 1.0
        custom_map[-1, :] = 1.0
        custom_map[:, 0] = 1.0
        custom_map[:, -1] = 1.0
        env.reset(options={"wall_map": custom_map})
        assert np.array_equal(env.wall_map, custom_map), \
            "注入的 wall_map 应被环境直接使用"

    @pytest.mark.unit
    def test_inject_wall_map_wrong_shape_raises(self) -> None:
        """TC-14b：注入形状不匹配的 wall_map 应抛出 ValueError。

        输入:  grid_size=6 的环境，注入 5×5 wall_map
        期望:  ValueError
        实测:  pytest.raises
        """
        import numpy as np
        env = MazeEnv(grid_size=6, obstacle_density=0.0, seed=0)
        bad_map = np.zeros((5, 5), dtype=np.float32)
        with pytest.raises(ValueError, match="wall_map"):
            env.reset(options={"wall_map": bad_map})

    @pytest.mark.unit
    def test_inject_custom_start_goal(self) -> None:
        """TC-14c：通过 options 覆盖 start / goal 坐标生效。

        输入:  options={'start': (1,1), 'goal': (2,2)}
        期望:  info['agent_pos'] == (1,1)，info['goal_pos'] == (2,2)
        实测:  info 字段
        """
        env = MazeEnv(grid_size=6, obstacle_density=0.0, seed=0)
        _, info = env.reset(options={"start": (1, 1), "goal": (2, 2)})
        assert info["agent_pos"] == (1, 1)
        assert info["goal_pos"]  == (2, 2)


# ======================================================================
# TC-15  只读属性（wall_map / goal_pos / agent_pos）
# ======================================================================

class TestReadOnlyProperties:
    """验证环境暴露的只读属性行为。"""

    @pytest.mark.unit
    def test_wall_map_property_readonly(self) -> None:
        """TC-15a：wall_map 属性返回不可写视图，写入应抛出 ValueError。

        期望:  对返回的 ndarray 赋值触发 ValueError
        实测:  ValueError
        """
        import numpy as np
        env = MazeEnv(grid_size=6, obstacle_density=0.0, seed=0)
        env.reset()
        wmap = env.wall_map
        with pytest.raises(ValueError):
            wmap[0, 0] = 1.0   # 写入只读视图应抛出异常

    @pytest.mark.unit
    def test_goal_pos_property(self) -> None:
        """TC-15b：goal_pos 属性返回终点坐标 tuple。

        期望:  isinstance(env.goal_pos, tuple)，值为 (N-2, N-2)
        实测:  属性值类型与内容
        """
        env = MazeEnv(grid_size=6, obstacle_density=0.0, seed=0)
        env.reset()
        gp = env.goal_pos
        assert isinstance(gp, tuple)
        assert gp == (4, 4)

    @pytest.mark.unit
    def test_agent_pos_property(self) -> None:
        """TC-15c：agent_pos 属性返回 Agent 当前坐标 tuple。

        期望:  reset 后 agent_pos == (1, 1)
        实测:  属性值
        """
        env = MazeEnv(grid_size=6, obstacle_density=0.0, seed=0)
        env.reset()
        assert env.agent_pos == (1, 1)