# Testing Patterns

**Analysis Date:** 2026-03-27

## Test Framework

**Runner:**
- 当前仓库未检测到有效的 Go 自动化测试文件：`glob("**/*_test.go")` 返回空，`glob("tests/**")` 返回空。
- 因此，仓库当前状态下不存在可执行的项目内单元测试、集成测试或 E2E 测试代码。

**Assertion Library:**
- 未检测到；因为当前仓库没有 `*_test.go` 文件。

**Configured / Documented commands:**
```bash
go test ./...                 # `README.md` 文档命令；当前仓库没有测试文件
go test -cover ./...          # `README.md` 文档命令；覆盖率描述与仓库现状不符
go test -v ./...              # `Makefile` 的 `test` 目标与 `README.md` 一致
go test ./pkg/...             # `README.md` 文档命令；当前没有对应测试文件
go test ./tests/integration/... # `README.md` 文档命令；当前仓库不存在 `tests/` 目录内容
go test -v ./internal/middleware -run TestKeyAuth # `README.md` 文档命令；当前未检测到对应测试
```

## Policy Reality

**Current project rule (authoritative):**
- `AGENTS.md` 明确规定：本项目不使用任何形式的自动化测试代码。
- `AGENTS.md` 明确禁止单元测试、集成测试、验收测试、流程测试、E2E 测试，以及创建 `*_test.go` 文件；唯一例外是用户明确要求“请写测试”。

**Repository reality:**
- 当前仓库与该规则一致：未发现任何 `*_test.go` 文件，也未发现 `tests/` 目录内容。

**Stale documentation conflicts:**
- `README.md` 仍包含完整“测试”章节，列出 `go test ./...`、覆盖率、集成测试、`tests/integration/`、以及 `docs/testing/test-connection-guide.md` 的说明。
- `README.md` 的项目结构段仍展示 `tests/integration/auth_test.go`、`tests/integration/ratelimit_test.go`。
- `README.md` 的 “Speckit / 宪章” 段仍写有 “70%+ 测试覆盖率，核心业务 90%+”。
- 这些内容与 `AGENTS.md` 的现行禁令、以及仓库中真实文件状态冲突。后续执行应以 `AGENTS.md` + 实际文件现状为准。

## Verification Approach Actually Used

**Primary approach:**
- 人工验证 + 脚本检查 + 文档生成检查 + 生产日志/监控。

**Evidence from policy:**
- `AGENTS.md` 将替代方案明确写为：
  - 使用 PostgreSQL MCP 工具手动验证数据
  - 使用 Postman/curl 手动测试 API
  - 依赖生产环境日志和监控发现问题

**Repository scripts that support this model:**
- `scripts/check-service-errors.sh`：静态扫描 Service 层错误处理规则。
- `scripts/check-comment-paths.sh`：静态扫描 Handler 注释中的 API 路径是否过时。
- `scripts/check-all.sh`：聚合上述脚本。
- `scripts/verify_migration/main.go`：直接连接数据库查询表和字段，验证迁移结果；这是一种手工校验辅助程序，不是自动测试框架。
- `cmd/gendocs/main.go` / `make docs`：通过重新生成 OpenAPI 文档来验证路由注册和文档接线是否完整。

## Test File Organization

**Location:**
- 当前无自动化测试文件。

**Naming:**
- 按 Go 常规应为 `*_test.go`，但本项目现行规则禁止新增，除非用户明确要求。

**Structure:**
```text
自动化测试目录：未检测到
README 中声明的 `tests/integration/`：当前不存在实际文件
```

## Manual Validation Patterns

**API / behavior validation:**
- 使用 Postman、curl 或 Swagger/OpenAPI 文档进行接口人工验证，依据见 `AGENTS.md` 与 `docs/api-documentation-guide.md`。
- 生成 OpenAPI 文档后检查路径是否出现：`go run cmd/gendocs/main.go`，再检查 `docs/admin-openapi.yaml`，依据见 `docs/api-documentation-guide.md`。

**Database validation:**
- 涉及数据正确性时，使用 PostgreSQL MCP 工具做手动查询验证，依据见 `AGENTS.md` 的 `db-validation` 说明。
- 涉及迁移结果时，可运行 `go run scripts/verify_migration/main.go` 检查表与字段；该脚本读取真实数据库 schema，不产出测试报告。

**Convention validation:**
- 改动 Service 层错误处理后运行 `bash scripts/check-service-errors.sh`。
- 改动 Handler 注释或路由后运行 `bash scripts/check-comment-paths.sh`。
- 需要一次性检查时运行 `bash scripts/check-all.sh`。

**Documentation / OpenAPI validation:**
- 新增 Handler 后必须同步更新 `cmd/api/docs.go` 与 `cmd/gendocs/main.go`，然后重新生成文档并检查目标路径，依据见 `docs/api-documentation-guide.md`。

## Mocking

**Framework:**
- Not applicable；当前没有自动化测试代码。

**Patterns:**
```text
未检测到 mock 框架、测试替身、fixture helper 或 testutil 包的实际使用。
```

**What to Mock:**
- 当前仓库没有现行自动化测试实践可供复用。

**What NOT to Mock:**
- 当前仓库没有现行自动化测试实践可供复用。

## Fixtures and Factories

**Test Data:**
```text
未检测到 fixture/factory 测试数据目录或 `_test.go` 中的构造模式。
```

**Reality check:**
- `README.md` 仍引用 `docs/testing/test-connection-guide.md` 和 `testutils.NewTestTransaction(...)` 示例，但当前仓库没有对应测试文件作为实际落点。

## Coverage

**Requirements:**
- 当前现行项目规则不要求覆盖率，且原则上禁止自动化测试，依据见 `AGENTS.md`。

**Conflict to document clearly:**
- `README.md` 和其中引用的 Speckit 宪章仍声称需要覆盖率目标；这与 `AGENTS.md` 的测试禁令冲突，且与当前“零测试文件”现状不符。

**View Coverage:**
```bash
go test -cover ./...    # 仅为 README 中遗留命令，不代表现行流程
```

## Test Types

**Unit Tests:**
- 当前未使用。

**Integration Tests:**
- 当前未使用。
- `README.md` 里提到的 `tests/integration/` 是过期描述，不是当前仓库事实。

**E2E Tests:**
- 当前未使用。

## CI Reality

**Actual workflow present:**
- `.gitea/workflows/deploy.yaml` 只有检出、Docker 构建、推送镜像、部署到测试环境的步骤。

**What is not in CI:**
- 未发现 `go test`。
- 未发现 `bash scripts/check-all.sh`。
- 未发现 `bash scripts/check-service-errors.sh`。
- 未发现 `bash scripts/check-comment-paths.sh`。
- 未发现独立的质量门或覆盖率上传步骤。

**Conflict to document clearly:**
- `README.md` 写着“这些检查会在 CI/CD 流程中自动执行”，但 `.gitea/workflows/deploy.yaml` 中没有相应步骤。当前 CI 现实是“构建/部署优先，无显式质量校验门”。

## Common Verification Commands

```bash
bash scripts/check-service-errors.sh   # 校验 Service 错误处理规则
bash scripts/check-comment-paths.sh    # 校验 Handler 注释路径是否过时
bash scripts/check-all.sh              # 运行当前已存在的全部静态脚本检查
go run cmd/gendocs/main.go             # 重新生成 OpenAPI 文档，验证路由接线
make docs                              # 等价于生成 OpenAPI 文档
go run scripts/verify_migration/main.go # 人工验证数据库迁移结果
```

## Current Gaps and Caveats

- `Makefile` 仍保留 `test:` 目标并执行 `go test -v ./...`，这属于历史遗留入口，不应被误解为现行团队要求。
- `README.md` 的测试章节、目录结构和覆盖率目标明显滞后于当前 `AGENTS.md` 规则。
- `scripts/check-service-errors.sh` 虽然存在，但当前仓库 `internal/service/polling/alert_service.go` 仍有 `fmt.Errorf(...)` 违规点，说明现有脚本检查并未通过 CI 强制执行。
- `scripts/verify_migration/main.go` 内含直接数据库连接字符串，反映的是临时人工验证脚本，而不是可复用、无环境依赖的测试体系。

## Prescriptive Summary

- 讨论“测试”时，先区分三件事：`README.md` 的历史文档、`AGENTS.md` 的现行规则、仓库当前真实文件状态。
- 在当前仓库中，默认不要新增 `*_test.go`；只有用户明确要求时才编写测试代码。
- 日常验证优先使用：静态检查脚本、OpenAPI 文档再生成、数据库手查、Postman/curl、人肉回归。
- 判断 CI 是否有质量门时，以 `.gitea/workflows/deploy.yaml` 为准，而不是 `README.md` 的说明。

---

*Testing analysis: 2026-03-27*