96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# Testing Guide / 测试策略
|
||
|
||
## 中文
|
||
|
||
### 文档校验基线
|
||
|
||
本仓库当前最可靠的文档一致性校验命令是：
|
||
|
||
```bash
|
||
go test ./...
|
||
```
|
||
|
||
原因：
|
||
|
||
- 它直接覆盖当前 Go 模块里的可编译包。
|
||
- 文档中涉及的包名、导出符号、接口签名、请求结构和行为路径都必须至少与这个基线不冲突。
|
||
- 本次工程文档补齐以源码为唯一事实源，因此文档更新完成后应重新执行这条命令确认基线仍为绿色。
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
go test ./...
|
||
make test
|
||
make integration-test
|
||
```
|
||
|
||
说明：
|
||
|
||
- `make test` 是仓库对 `go test` 的脚本封装。
|
||
- `make integration-test` 运行 `tests/e2e/superadmin-login/run-test-scripts.sh`，依赖本地数据库与初始化流程。
|
||
|
||
### 当前包级测试面
|
||
|
||
| 包 | 当前状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| `account/api` | 有测试 | 覆盖注册、登录、MFA、session、sync config、admin settings、xworkmate、accounting、homepage video 等主 API 路径。 |
|
||
| `account/internal/agentserver` | 有测试 | 覆盖 registry 构造、认证、状态上报。 |
|
||
| `account/internal/mailer` | 有测试 | 覆盖 TLS mode 解析与 sender 构造。 |
|
||
| `account/internal/service` | 有测试 | 覆盖 user metrics 聚合行为。 |
|
||
| `account/internal/store` | 有测试 | 覆盖 memory / postgres 相关关键行为与 xworkmate 归一化。 |
|
||
| `account/internal/xrayconfig` | 有测试 | 覆盖 generator、gorm source、periodic syncer。 |
|
||
| `cmd/*`、`internal/auth`、`internal/agentmode`、`internal/syncer`、`internal/utils`、`internal/model`、`config`、`sql` | 暂无测试文件 | 文档应以源码对读为主，并明确哪些行为缺少直接测试保护。 |
|
||
|
||
### 文档更新后的核对清单
|
||
|
||
1. `RegisterRoutes` 中出现的 endpoint，文档必须存在且路径、方法、鉴权方式一致。
|
||
2. `internal/store.Store`、`auth.TokenService`、`service.UserMetricsService`、`xrayconfig.PeriodicSyncer` 等关键接口的签名必须与源码逐字对齐。
|
||
3. 对于暂无测试文件的包，文档必须避免推测性表述，只记录源码中可直接确认的行为。
|
||
|
||
## English
|
||
|
||
### Documentation Verification Baseline
|
||
|
||
The most reliable verification command for documentation alignment in this repository is:
|
||
|
||
```bash
|
||
go test ./...
|
||
```
|
||
|
||
Why this is the baseline:
|
||
|
||
- It covers all buildable Go packages in the current module.
|
||
- Package names, exported symbols, interface signatures, request structs, and behavior described in the docs must remain compatible with this baseline.
|
||
- This documentation refresh uses source code as the only source of truth, so the baseline should be rerun after every doc update.
|
||
|
||
### Common Commands
|
||
|
||
```bash
|
||
go test ./...
|
||
make test
|
||
make integration-test
|
||
```
|
||
|
||
Notes:
|
||
|
||
- `make test` is the repository wrapper around Go tests.
|
||
- `make integration-test` runs `tests/e2e/superadmin-login/run-test-scripts.sh` and depends on local database setup plus initialization steps.
|
||
|
||
### Current Package-Level Test Surface
|
||
|
||
| Package | Current status | Notes |
|
||
| --- | --- | --- |
|
||
| `account/api` | Tested | Covers registration, login, MFA, session, sync config, admin settings, xworkmate, accounting, and homepage video paths. |
|
||
| `account/internal/agentserver` | Tested | Covers registry construction, authentication, and status reporting. |
|
||
| `account/internal/mailer` | Tested | Covers TLS mode parsing and sender construction. |
|
||
| `account/internal/service` | Tested | Covers user metrics aggregation behavior. |
|
||
| `account/internal/store` | Tested | Covers key memory / postgres behavior plus xworkmate normalization. |
|
||
| `account/internal/xrayconfig` | Tested | Covers generator, GORM source, and periodic syncer behavior. |
|
||
| `cmd/*`, `internal/auth`, `internal/agentmode`, `internal/syncer`, `internal/utils`, `internal/model`, `config`, `sql` | No direct test files | Documentation for these packages should stay source-driven and avoid speculative claims. |
|
||
|
||
### Post-Update Checklist
|
||
|
||
1. Every endpoint registered in `RegisterRoutes` must exist in the docs with matching path, method, and auth mode.
|
||
2. Key signatures such as `internal/store.Store`, `auth.TokenService`, `service.UserMetricsService`, and `xrayconfig.PeriodicSyncer` must match the source exactly.
|
||
3. For packages without direct tests, the docs must record only behavior that is directly visible in source.
|