# Rust 测试分层约定

本文档说明测试应该放在哪里以及每一层允许依赖什么

## 单元测试

单个规则私有状态机编码函数和边界计算使用源码文件底部的 `#[cfg(test)] mod tests`

单元测试可以通过 `use super::*` 访问当前模块私有实现 但不应跨多个业务模块组装完整应用

当前示例包括 Metadata 限制 路径校验 内容组代表选择 响应限流和查询分位数

## 组件测试

需要模块私有装配状态的组件测试保留在对应模块中

例如 Axum router 测试需要私有 `ApiState` 和测试用验证入口 因此与 `api` 模块放在一起而不是为了目录形式公开内部 API

RocksDB adapter 测试需要验证原子批处理私有键空间租约和损坏状态 因此保留在 `storage::rocks` 内部

## 集成测试

只使用 crate 公开 API 的跨层契约放在 crate 根目录 `tests/`

`dht-search/tests/storage_search_flow.rs` 从外部组合领域模型 RocksDB repository 和 Tantivy search 验证写入索引查询关闭重开和恢复

集成测试不得依赖 `pub(crate)` 或为测试扩大生产 API 可见性

## 端到端和运行测试

真实 DHT 网络长时间运行远程部署和浏览器交互依赖外部环境 不放入默认 `cargo test`

这类测试的条件命令结果和验收结论记录到 `TODOS.md` `BENCHMARKS.md` 或部署文档

## 性能基准

可重复的规模测量使用独立 `dht-benchmark` 二进制

基准模块按参数数据集工作负载采样报告和编排拆分 单元测试只验证确定性生成分位数退避和格式化规则

性能结论必须来自 release 构建 默认 debug 运行只用于流程冒烟

## 默认验证命令

```powershell
$env:LIBCLANG_PATH = "$PWD\.tools\libclang\clang\native"
cargo fmt --all --check
cargo test --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
```