# 我用一条命令搭建了完整的 AI 测试工程化项目TestSpec 实战 你也遇到过这种情况吗让 AI 帮忙写接口测试它秒级吐出一堆 assert resp.status_code 200跑起来全绿结果线上还是出 bug——因为没人查数据库到底落没落库。 这篇带你用一条命令从零搭出一个规格优先的 AI 测试工程化项目让 AI 老老实实按规范写测试不再自由发挥。---## 一、先说痛点AI 写测试为什么越快越危险很多人用 AI 写测试的感受是**快是真快但心里没底**。典型症状有这么几个1. **覆盖遗漏**AI 凭记忆写只覆盖开心路径happy path边界条件、异常路径、权限组合全靠运气。2. **断言空洞**清一色 assert status_code 200。接口逻辑错了但状态码对根本测不出来。3. **DB 校验缺失**写操作增/改/删只看 HTTP 响应不查数据库有没有真的落库。这是真实存在的 bug 高发区。4. **无法追溯**三个月后没人知道某个测试函数对应哪条需求需求一变测试跟着烂掉。AI 的高效输出掩盖了设计的缺失制造出已经覆盖的假象——这比手写遗漏更危险因为它更难被发现。**TestSpec** 就是冲着这个问题来的一个规格优先的测试自动化工程化框架。理念很简单——**先写规格文档再写测试代码**让规格成为 AI 和人共同遵守的合同。它类似 OpenSpec但 OpenSpec 面向接口设计TestSpec 面向**测试**。---## 二、一条命令搭起来testspec init 全过程先装bashpip install testspec然后一条命令启动交互式向导bashtestspec init接下来是 8 步交互我把真实过程贴出来我搭一个订单服务测试项目 order-service-testsTestSpec 框架脚手架 v1.2.0规格优先的测试自动化工程化框架[步骤 1/8] 项目基本信息请输入项目名称英文连字符格式例如order-service-tests: order-service-tests[步骤 2/8] 测试类型决定技能模板和工具桩的内容请选择测试类型1. api - HTTP 接口自动化测试2. unit - 单元测试3. integ - 集成测试4. e2e - 端到端测试可多选逗号分隔例如1 或 1,4: 1,4 # 既测接口又测端到端[步骤 3/8] 编程语言与测试框架请选择语言与框架1. python / pytest (默认)...请选择 [1]: 1[步骤 4/8] 数据库配置是否需要数据库校验(Y/n): y # 写操作必须有 DB 校验选 y请选择数据库类型1. mysql ...请选择 [1]: 2 # 我用 MySQL[步骤 5/8] 测试报告工具请选择报告工具1. allure (默认)请选择 [1]: 1[步骤 6/8] CI/CD 系统请选择 CI/CD 系统1. github_actions (默认)2. gitlab_ci请选择 [1]: 1[步骤 7/8] 业务线 / 功能模块请输入业务线或功能模块名称英文逗号分隔例如order,payment,inventory: order,payment[步骤 8/8] 输出与语言请输入生成项目的目标目录 [./order-service-tests]:文档语言1. zh (默认)2. en请选择 [1]: 1确认后回车**一个完整的测试工程化项目就生成好了**。不用自己配 pytest、不用手写 conftest、不用搭 Allure、不用从零写 HTTP 客户端和 DB 客户端——全给你了。 小贴士不想交互testspec init -y 用默认值一把梭CI 里自动化生成用 testspec init --config project.json。还有 testspec validate ./my-project 校验完整性、testspec upgrade ./my-project 升级框架文件保留你的业务代码。---## 三、生成的项目长什么样order-service-tests/├── CLAUDE.md ← AI 行为规则 架构指南AI 和新人的地图├── testspec.json ← 框架版本标记├── .claude/commands/ ← 15 个 Claude Code 技能命令├── config/variable_loader.py ← 深度合并变量加载器├── utils/│ ├── http_client.py ← HTTP 客户端sentinel 断言模式│ ├── db_client.py ← 数据库客户端连接池 参数化 SQL│ ├── logger.py ← 日志文件写入 敏感脱敏│ ├── data_reader.py ← YAML/JSON/Excel 数据读取│ ├── data_factory.py ← 测试数据工厂│ ├── contract_checker.py ← 契约校验│ ├── assertions.py ← 通用断言辅助│ ├── poll_helper.py ← 轮询等待辅助│ └── mock_server.py ← Mock 服务├── testcase/ ← 测试用例目录按业务线分├── specs/ ← 规格文档目录单一事实来源│ ├── spec-template.md ← 规格文档模板│ ├── spec-example.md ← 规格文档示例│ └── registry.yaml ← Spec 注册表├── scripts/ ← 10 个工具脚本合规自检、覆盖率、flaky 检测…├── ci/ ← CI/CD 配置直接可用 YAML├── data/yaml|json|excel/ ← 测试数据目录├── variables.yaml ← 非敏感默认变量├── variables_override.yaml.template ← 敏感变量结构指南├── pytest.ini / conftest.py├── run_order-service-tests.sh / .ps1 ← 一键执行脚本└── requirements.txt ← 动态生成的依赖重点说三个东西1. **specs/** —— 整个项目的单一事实来源。先在这里用自然语言写清楚要测什么再让 AI 照着写代码。2. **.claude/commands/** —— 15 个技能命令这是 AI 能按规范干活的关键。3. **scripts/check_compliance.py** —— 合规自检脚本写操作没加 DB 校验直接报红这是防漏的最后门禁。---## 四、配合 Claude Code跑通一个完整用例搭好项目后在 specs/order/ 下写一份规格框架给了模板照着填。下面是它自带的示例片段验证创建订单后状态正确落库markdown## 用例说明 验证用户正常下单后订单在数据库中的初始状态为 Pending状态值 1且订单号唯一。## 测试步骤### 步骤 1创建订单- 接口: POST /api/v1/orders- 预期响应: HTTP 201- 断言: order_id 非空 / status pending / created_at 为合法 ISO 时间### 步骤 2数据库校验- 目标表: Orders- 校验字段: Status 1 / ProductId 一致 / Quantity 一致 / CreatedAt 合理规格写完**接下来不写代码而是走 8 步工作流**——每一步对应一个技能命令AI 按步执行| 步骤 | 命令 | 产物 ||---|---|---|| 0 规格对齐 | /case-design内含 | 需求追溯表 || 1 用例设计 | /case-design | 结构化用例清单正常/异常/边界/权限 || 2 测试数据 | /test-data | YAML 参数化数据文件 || 3 写代码 | /write-tests | pytest 测试代码框架 || 4 断言设计 | /assertion-design | 断言策略状态/结构/语义/稳定性/DB 一致性 || 5 DB 校验 | /data-verify | 带超时轮询的 DB 查询 断言 || 6 报告装饰 | /report-decorate | Allure title/step/attach/severity || 7 合规自检 | /compliance-check | 写操作缺 DB 校验的缺失清单 |也可以直接调入口命令 /AutomatedTesting它是个智能调度器分析你的素材后自动规划该调哪些技能。**为什么是 8 步而不是一步到位** 因为每步解决一类问题0-1 防遗漏防幻觉2 保数据独立可重复3 结构化生成而非自由发挥4-5 保证断言有实质意义6 给可观测性7 是防漏门禁。跳过任何一步对应层的风险往往很晚才暴露。---## 五、我最喜欢的一个设计合规自检门禁说实话前面那些 AI 都能装模作样做出来。真正打动我的是最后这一步——/compliance-check它会自动扫描所有写操作用例**没加 DB 校验的直接报红**[WARN] 发现 2 个写操作用例缺少 DB 校验文件: testcase/order/test_order_create_e2e.py- 行 45: test_CreateOrder_WithRemark → 缺少 db_client 调用文件: testcase/payment/test_refund_e2e.py- 行 88: test_Refund_Success → 缺少 db_client 调用请补全上述用例的数据库校验后重新运行自检。接口返回 200 但数据没落库是真实存在的 bug。只有 DB 校验能发现。这个门禁等于把测试有没有真校验这件事从靠人盯变成了机器兜底。---## 六、它适合谁用**适合**- 长期维护的测试套件团队 2 人跑 6 个月以上- 业务逻辑复杂、异常场景多、权限矩阵复杂- 在用 AI 辅助生成测试代码需要规格约束- 有合规/覆盖率/需求追溯要求- 涉及写操作的接口测试DB 校验是必须的**可能过重**- 一次性脚本、临时验证- 1-2 人、5 个以内测试文件的极小项目- 纯函数级单元测试、无外部依赖- 需求本身还没稳定的原型阶段如果觉得 8 步太重也有轻量配置**最小必须步骤 1用例设计 3写代码 7合规自检**。但有一条原则无论如何不该跳——**写操作接口必须有数据库校验**。---## 七、上手三连bashpip install testspec # 装testspec init # 一条命令搭项目# 在 Claude Code 里 /AutomatedTesting # 跑工作流- GitHubhttps://github.com/LittleBearPooh/testspec顺手点个 ⭐ 支持一下开源不易- PyPIhttps://pypi.org/project/testspec/- MIT 协议可自由使用如果你也在被AI 写的测试心里没底折磨或者团队缺一套能追溯、能兜底的测试工程化规范强烈建议试一下。**有问题欢迎在评论区交流也欢迎去 GitHub 提 issue / PR 一起完善。** 用过觉得不错的回来留个言告诉我你落地的场景对作者帮助很大 ---*TestSpec 的核心哲学测试用例的价值不在于代码而在于对系统行为的规格化描述。代码只是规格的一种执行形式。*