# DataPacker 项目 Agent 约束

## 严禁文本断言（Strict Ban on Text Assertions）

编写或修改 pytest 测试时，绝对禁止任何形式的纯文本或字符串断言。

### 禁止写法

- 禁止 `assert "some string" in result`。
- 禁止 `assert result == "exact string"`。
- 禁止 `assert "string" not in result`。
- 禁止使用正则表达式匹配纯文本输出。
- 禁止使用 `pytest.raises(..., match=...)` 校验异常消息。
- 禁止通过读取 Markdown、源码、脚本、workflow 或配置文件后搜索字符串来验证行为。

### 必须采用的验证方式

- 验证数据结构或对象状态：断言函数返回的字典、Dataclass、Pydantic Model、Enum、Path 或其他领域对象属性，不断言其序列化文本。
- 验证方法调用：使用 `unittest.mock.patch`、`MagicMock` 或 spy，断言底层核心函数收到的参数和调用次数。
- 验证业务副产物：断言文件、archive members、hash、状态码、布尔值、数值、对象类型或进程退出状态。
- 验证结构化配置：TOML、YAML、JSON 必须解析成对象后验证；不得搜索原始文本。
- 验证异常时优先断言异常类型和结构化属性，不得匹配异常消息。

### 被测代码只有文本输出时

如果被测函数只返回一个巨大字符串，必须先重构业务代码，把“数据组装”和“文本渲染”拆开；测试只覆盖数据组装函数返回的结构化对象。不得为了保留文本断言而增加另一种字符串搜索、正则或快照测试。

### 项目门禁

- 项目内所有 `test_*.py`、`*_test.py` 和 `conftest.py` 都必须通过文本断言 AST policy gate，包括根测试集之外的子项目测试。
- 新测试和既有测试适用同一规则，不允许 grandfathered violation。
- 字符串可以作为被测 API 输入、Path 构造参数、字典 key 或 mock 调用参数；禁止的是对纯文本结果、渲染文本、源码文本、日志文本和异常消息进行断言。