# 测试

> 适用：改动 `osmassets/osm.py`、`osmassets/geom.py`，或往里加新的纯函数。

---

## 怎么跑

```bash
python3 -m unittest discover blender/tests
```

**不需要 Blender**，用系统 Python 就行。当前 51 个用例，运行约 0.01 秒。

这是全仓唯一的自动化测试。快到没有理由不在每次改动后跑一遍。

能这么跑的前提是 `osmassets` 的[依赖分层](./module-structure.md)——
`test_pure.py:19` 手动把 `blender/` 塞进 `sys.path`，然后只 import 纯 Python 模块。

---

## 最重要的一条：期望值必须从几何推导

`test_pure.py:9-11` 写得很直白：

> The expected values are derived from the geometry, not captured from the
> implementation — **a test that just records current output would ratify a bug.**

具体做法是在测试里写清楚**为什么**是这个数：

```python
def test_half_outside_polygon_is_cut_at_the_boundary(self):
    clipped = clip_polygon(SQUARE, 0.0, 5.0, 0.0, 10.0)
    self.assertTrue(all(x <= 5.0 + 1e-9 for x, _ in clipped))
    # A 10x10 square clipped to half its width is a 5x10 rectangle.
    self.assertAlmostEqual(polygon_area(clipped), 50.0, places=6)
```

反例——**不要这样写**：

```python
def test_clip(self):
    # 跑一遍把输出粘过来
    self.assertEqual(clip_polygon(SQUARE, 0.0, 5.0, 0.0, 10.0),
                     [(0.0, 0.0), (5.0, 0.0), (5.0, 10.0), (0.0, 10.0)])
```

这种测试在实现正确时和实现错误时**同样会通过**。它固化的是当前行为，不是需求。

**自检**：把被测的那个特性从实现里删掉，测试还能过吗？能过就是无效测试。

---

## 每个几何函数都要覆盖退化输入

这是本套测试最系统的部分。`geom.py` 的函数会收到真实 OSM 数据里的各种畸形几何，
所以每个函数都有一个 `test_degenerate_input`：

| 退化情形 | 例子 |
|---|---|
| 空输入 | `clip_polygon([], ...)` → `[]` (`:73`) |
| 点数不足成面 | `clip_polygon([(0,0),(1,1)], ...)` → `[]` (`:74`) |
| 完全在裁剪框外 | `clip_polygon(SQUARE, 20,30,20,30)` → `[]` (`:70`) |
| 零长线段 | `sample_tree_row` 跳过而非除零 (`:203`) |
| 重复顶点 | `distance_to_ring` 不除零 (`:178`) |
| 参数为零 | `sample_ring_boundary(SQUARE, spacing=0.0)` → `[]` (`:123`) |
| 单点输入 | `sample_polygon_interior([(0,0)], ...)` → `[]` (`:146`) |

**加新几何函数就配一个 `test_degenerate_input`。** 约定是"返回空/零"而不是抛异常——
一个坏多边形不该中断整片区域的构建。

### 除零守卫要指名道姓

覆盖某个具体守卫时，注释写清楚针对哪一行：

```python
def test_axis_aligned_edge_does_not_divide_by_zero(self):
    # A vertical edge crossing the x clip plane exercises the b[0] == a[0]
    # guard in the intersection lambdas.
```

这样守卫被误删时，失败的测试能直接说明它保护的是什么（`test_pure.py:76-78`）。

---

## 其余几条约定

### 随机采样必须验 seed 可复现

```python
def test_seed_is_deterministic(self):
    first  = sample_polygon_interior(SQUARE, spacing=3.0, seed=7)
    second = sample_polygon_interior(SQUARE, spacing=3.0, seed=7)
    self.assertEqual(first, second)
```

不可复现的采样会让 [parity 校验](../guides/artifact-parity-guide.md)永久性地红。
任何带随机的新函数都要收 `seed` 参数并配这个测试（`test_pure.py:135-138`）。

### 绕向无关的性质要两个方向都测

`sample_ring_boundary` 的 `inset` 对顺时针和逆时针都必须往内缩：

```python
ccw = sample_ring_boundary(SQUARE, spacing=10.0, inset=1.0)
cw  = sample_ring_boundary(list(reversed(SQUARE)), spacing=10.0, inset=1.0)
self.assertTrue(all(point_in_polygon((x, y), SQUARE) for x, y, _, _ in ccw))
self.assertTrue(all(point_in_polygon((x, y), SQUARE) for x, y, _, _ in cw))
```

同理 `polygon_area` 对绕向不敏感、`signed_polygon_area` 敏感，两者分别验
（`test_pure.py:88-91, 109-115`）。

### 跨边界的连续性要单独测

真实几何常见的坑是"分段处理时每段各自重新开始"：

```python
def test_spacing_carries_across_segment_joins(self):
    # Two 3m segments with 4m spacing: the second sample must land 1m into
    # the second segment, not restart at its origin.
```

（`test_pure.py:190-196`）

### 解析器的容错语义要写死

`parse_osm` 的两档行为必须都有测试（`test_pure.py:343-356`）：

- **坏节点跳过，不致命**：`lon='oops'` 的节点被忽略，其余照常解析
- **缺 `bounds` 直接抛 `RuntimeError`**：没有 bounds 就无法建立投影，继续下去毫无意义

分档理由见 `generate_scene.py:9-12`：OSM 导出可能带上区域外的 relation 成员，
所以范围只认 `bounds` 元素，不用全部节点算包围盒。

### 用真实格式的 fixture

`OSM_SAMPLE`（`test_pure.py:285`）是一段真的 OSM XML，故意塞进了坏节点、
`action='delete'` 的 way、引用了不存在节点的 way。写进临时文件再解析，
`tearDown` 里 `os.unlink`。

**别 mock 解析器。** 解析器的价值就在于处理真实世界的脏数据。

---

## 命名

- 类名 = 被测函数的驼峰 + `Test`：`ClipPolygonTest`、`SampleTreeRowTest`
- 方法名是**陈述句，说明这个行为是什么**，不是 `test_case_1`：
  `test_polygon_keeps_only_the_exterior_ring`、
  `test_trailing_point_is_skipped_when_it_would_double_plant`

方法名读起来就是这个函数的规格说明。

---

## 测不到的部分怎么办

`bpy` 层（`mesh.py`、`materials.py`、`tree.py`、两个入口脚本）**没有单元测试**，
也不打算有——它们需要真实的 Blender 运行时。

这一层的回归防线是 **parity 校验**：结构摘要比对，而不是单元测试。
见[产物一致性指南](../guides/artifact-parity-guide.md)。

**推论**：能挪进纯 Python 层的逻辑就挪。一个函数只要不碰 `bpy`，
放进 `geom.py` 就立刻获得测试覆盖的资格。

### 以 MeshBatch 为边界的静态设施测试

少数 bpy 要素模块的价值在于确定性地向 `MeshBatch` 追加顶点与面，而不是调用 bpy API
本身。对这类模块（例如 `osmassets/traffic_signals.py`），应在 `blender/tests/` 用假的
`osmassets.mesh.MeshBatch` 导入模块，断言有效输入的装配数量和关键几何方向。这样可覆盖
“校验函数意外返回空、所有要素被静默跳过”这一类错误，不必依赖可用的 Blender 进程。

测试必须在本文件列出的 `python3 -m unittest discover blender/tests` 命令下独立运行；测试
文件自己添加 `blender/` 到 `sys.path`，不能依赖其他测试的导入顺序。

---

## 反模式

| 反模式 | 后果 |
|---|---|
| 把当前输出粘成期望值 | 实现有 bug 时测试照样绿 |
| 新几何函数不配退化输入测试 | 真实数据一进来就崩 |
| 退化输入抛异常而不是返回空 | 一个坏多边形中断整片区域 |
| 带随机的函数不收 `seed` | parity 校验永久红 |
| mock 掉 OSM 解析 | 测不到它唯一的价值 |
| 在测试里 import `bpy` 侧模块 | 整个套件无法运行 |
| 只测一种绕向 | 反向多边形进来才发现 |