测试

evstats 的自动化测试有一个统一入口：仓库根的 evs-test（Python，用 uv 管理）。它按编号挑用例，拼好 Makefile 目标、起本机的 ClickHouse 与 Redis、跑完按编号汇总。

跑测试

cd evs-test
uv run main.py --list                  # 全部用例：编号、里程碑、执行方式、分组、标题
uv run main.py --case T-Q23            # 一个用例（也接受 TQ23）
uv run main.py --case T-Q01~T-Q04      # 区间
uv run main.py --case T-S              # 编号前缀：全部浏览器场景
uv run main.py --case dash             # 目录：unit、dash、openapi、docs、sdk、media
uv run main.py --case agent            # dash 下的分组：api、agent、stats
uv run main.py --case M3               # 里程碑门槛（含之前的里程碑）
uv run main.py --case all              # 全部测试（不含 media）

结果打印在终端，汇总写到仓库根的 build/test/last-run.md，各步骤的原始报告也在 build/test/。

环境隔离

测试只用本机 Docker 里的 ClickHouse 库 evstats_test（及 evstats_test_*）和 Redis 1 号库，入口会先 docker compose -f deploy/dev/compose.yaml up -d --wait。手工开发用的 evstats 库和 0 号库不会被碰。

用例怎么组织

目录	内容	执行方式
unit/	不连库的单元测试与静态检查：Go、Vitest、JUnit、lint	make test-unit-*
dash/	管理后台：后台接口（T-A、T-C、T-B、T-K、安全项 SEC-*）、Agent、Stats 界面场景（T-S）	Go 接口用例；Python Playwright
openapi/	开放接口：统计接口两边一致（T-Q）、契约（T-O）、CORS	Go 接口用例
docs/	官网用例 T-D01～T-D08；官网副本与源头一致 T-D09～T-D11	yarn test；Python 检查
sdk/	Web、Go、Java SDK	各自的测试命令
media/	官网截图与动图	Python Playwright

公用代码在 lib/：用例结构、目录、跨目录检查、示例数据生成、浏览器辅助（lib/browser/）。

加一个用例

接口用例：实现写在 evs-aggr/internal/apitest/（真实 HTTP 打 127.0.0.1:18080），期望的数字放在 internal/testkit/expect.json；然后在 evs-test 对应目录的 cases.py 登记编号和 Go 测试函数名。--list 会提示没有登记的测试函数。

浏览器场景：写在 evs-test/dash/browser_*.py，函数签名是 (page, context, browser, report_dir)，在同一文件的 CASES 里登记，再在 dash/cases.py 里登记编号。场景运行时由 e2ectl 管理一个测试用的 evstats 进程（127.0.0.1:18080）、一个假模型、一个假 SMTP 和一个加载 Web SDK 的示例站点：

辅助	用途
Ctl(context).reset()	清空测试库，重启 evstats，返回管理员账号等信息
api_setup、create_project、create_user	用接口完成引导、建项目、建用户
ctl.load_fixture_h(project_id)	灌入固定的夹具数据，返回期望的数字
ctl.ai_script(tool, args, answer)	让假模型下一次调用指定的工具，用模板回答
context_options()	新建浏览器上下文的公共参数（无头浏览器自带的 UA 会被当成爬虫丢掉）

官网用例：写在 evs-docs/scripts/check.ts，在 evs-test/docs/cases.py 登记。

持续集成

任务	内容
aggr	go vet、golangci-lint、单元测试、接口用例
dash	ESLint、Stylelint、vue-tsc、Vitest、构建、包体积
e2e	构建管理界面与 Web SDK，用 evs-test 跑全部浏览器场景
docs	官网构建与文档用例
registry	前后端模块注册表一致
sdk-web、sdk-go、sdk-java	三端 SDK
license	新依赖的许可证在允许列表内

改完之前

• 改了代码：相关用例通过，uv run main.py --case unit 全绿。
• 改了接口或统计口径：对应的 T-Q / T-O 用例通过，官网契约副本已同步（T-D09）。
• 改了界面：T-S 场景通过，需要时重新生成截图。
• 改了文档：uv run main.py --case docs 通过。