需求文件沒人看,Cucumber 太重,但你又想在動手寫程式碼之前把事情想清楚。
你有沒有遇到過這種情況——
產品經理寫了一頁需求文件,開發看了兩眼就開始寫程式碼。寫完發現理解有偏差,返工。下次換成 Jira ticket,列了一堆驗收條件,開發對著清單一條一條打勾,功能”驗收透過”了,但用起來彆扭——因為沒有人從頭到尾想過”使用者到底是怎麼用這個東西的”。
BDD 試圖解決這個問題:用 Given/When/Then 把行為寫出來,直接跑。但 Cucumber 的學習成本、step definition 的維護成本、結構化語法的表達力限制,讓很多團隊試了又放棄了。
Story-Test-Dev 是一個更輕量的方案。 核心想法很簡單:
Story(写故事) → Test(提取测试) → Dev(实现代码)- Story:用自由敘事體寫使用者故事——有人物、有場景、有動機,像在講一個人怎麼用你的產品
- Test:從故事中提取測試用例,用
> 关联测试:TestXxx錨點把場景和測試關聯起來 - Dev:實現程式碼,讓測試透過
不需要安裝框架,不需要學 DSL。Markdown + pytest,完事。
Part 1: WHAT — 一個完整的例子
空談方法論沒有用。我們用一個”待辦事項 API”從頭走一遍。
寫 Story
建立 stories/todo_api.md:
# 待办事项 API
## 背景
小王是一个前端工程师,他需要一个简单的待办事项后端 API。他不想用重量级的项目管理工具,只想要一个能增删查的 REST 接口,数据存本地就好。
---
## 小王的日常使用
### 场景 1:创建一条待办
> 关联测试:`TestTodoAPI.test_create_todo`
小王打开终端,向 `POST /api/todos` 发送了一条请求,body 里写着 `{"title": "买咖啡", "due": "2025-03-15"}`。接口返回 201,response 里带着刚创建的待办,有 `id`、`title`、`due`、`done: false` 四个字段。
一条待办就建好了。
### 场景 2:查看所有待办
> 关联测试:`TestTodoAPI.test_list_todos`
小王请求 `GET /api/todos`,返回一个列表,里面有他刚才创建的那条。他又加了一条 "写周报",再次请求,列表里变成了两条,按创建时间排序。
### 场景 3:完成一条待办
> 关联测试:`TestTodoAPI.test_complete_todo`
小王买完咖啡回来,向 `PATCH /api/todos/{id}` 发送`{"done": true}`。接口返回更新后的待办,`done` 变成了 `true`。他再看列表,那条待办还在,只是状态变了——他不想完成就消失,万一要回顾呢。注意幾個特點:
- 人物是具體的:“小王,前端工程師”——不是抽象的”使用者”
- 場景是敘事的:像在講一個人的使用過程,不是在列需求清單
- 錨點是顯式的:每個場景都有
> 关联测试:標註對應的測試方法 - API 細節嵌在故事裡:請求路徑、引數、返回值都在敘事中自然出現
從 Story 提取 Test
建立 tests/test_todo_api.py:
"""Tests for Todo API — derived from stories/todo_api.md"""import pytestimport requests
class TestTodoAPI: """Test cases mapped to story scenarios."""
def test_create_todo(self): """场景 1:创建一条待办""" response = requests.post( f"{BASE_URL}/api/todos", json={"title": "买咖啡", "due": "2025-03-15"}, ) assert response.status_code == 201 data = response.json() assert data["title"] == "买咖啡" assert data["due"] == "2025-03-15" assert data["done"] is False assert "id" in data
def test_list_todos(self): """场景 2:查看所有待办""" # 先创建两条 requests.post(f"{BASE_URL}/api/todos", json={"title": "买咖啡"}) requests.post(f"{BASE_URL}/api/todos", json={"title": "写周报"})
response = requests.get(f"{BASE_URL}/api/todos") assert response.status_code == 200 todos = response.json() assert len(todos) == 2
def test_complete_todo(self): """场景 3:完成一条待办""" # 创建 created = requests.post( f"{BASE_URL}/api/todos", json={"title": "买咖啡"}, ).json()
# 完成 response = requests.patch( f"{BASE_URL}/api/todos/{created['id']}", json={"done": True}, ) assert response.status_code == 200 assert response.json()["done"] is True
# 完成后仍在列表中 todos = requests.get(f"{BASE_URL}/api/todos").json() completed = [t for t in todos if t["id"] == created["id"]] assert len(completed) == 1 assert completed[0]["done"] is True測試用例和 story 場景一一對應。測試方法名就是錨點裡寫的名字,docstring 標註了對應的場景編號。
實現程式碼
測試寫好了,接下來寫實現讓它們透過。這一步就是常規的開發——重點是:story 和 test 在你動手寫程式碼之前就已經存在了。
這就是 Story-Test-Dev 的全部流程。沒有框架要裝,沒有 DSL 要學,沒有 step definition 要維護。
Part 2: WHY — 為什麼不直接用 BDD
Story-Test-Dev 的靈感來自幾個成熟的方法論。但它刻意做了減法。
業界有什麼
BDD (Behavior-Driven Development) — Dan North, 2006。用 Given/When/Then 結構化語法描述行為,直接作為可執行測試1。代表工具:Cucumber, Behave (Python), SpecFlow。
ATDD (Acceptance Test-Driven Development) — Kent Beck, Ward Cunningham。先定義驗收標準,再寫驗收測試,最後實現。參考書:ATDD by Example2。
Specification by Example (SBE) — Gojko Adzic。用具體例項(而非抽象規格)驅動開發,例項同時充當活文件和測試。參考書:Specification by Example3。
Example Mapping — Matt Wynne (Cucumber 團隊)。用卡片把 Rule → Example → Question 對映出來,再轉化為測試。參考書:The Cucumber Book4。
這些方法論都在解決同一個問題:在寫程式碼之前,先把”要做什麼”想清楚,並且讓這個”想清楚”的產物能自動驗證。
那 Story-Test-Dev 做了什麼不同的事
| 維度 | BDD / Cucumber | Story-Test-Dev |
|---|---|---|
| Story 格式 | Given/When/Then 結構化語法 | 自由敘事體(“小王開啟終端……”) |
| Story 與測試的關係 | 1:1 自動繫結(框架驅動) | 手動錨點 > 关联测试:TestXxx |
| Story 的讀者 | 主要是開發和 QA | 更像產品文件,任何人可讀 |
| 工具依賴 | 需要 Cucumber 等專用框架 | 純 Markdown + pytest,零框架依賴 |
| 敘事深度 | 面向機器解析,偏幹 | 面向人類閱讀,有背景、動機、感受 |
展開說三個關鍵差異。
自由敘事 vs 結構化語法。 BDD 的 Given/When/Then 是為了讓機器解析而設計的,寫出來像填表格。Story-Test-Dev 的故事是給人讀的——有背景介紹、有人物動機、有使用感受。“小王買完咖啡回來,向 PATCH /api/todos/{id} 傳送……” 比 “Given a completed todo, When the user patches it” 多傳達了一層資訊:這是一個自然的使用場景,不是在填驗收清單。
手動錨點 vs 自動繫結。 BDD 框架要求 step definition 和 feature file 透過正則匹配繫結。Story-Test-Dev 只用一行 Markdown 引用就夠了。好處是零工具依賴;代價是如果測試改名了,錨點需要手動更新。對於中小規模專案,這個取捨是值得的。
零框架依賴。 不需要學 Cucumber,不需要寫 step definition,不需要配置 runner。寫 Markdown,寫 pytest,完了。團隊裡來了新人,給他看 story 檔案他就能理解功能,給他看 test 檔案他就能理解介面。
Part 3: HOW — 落地要點
Story 怎麼寫
一個好的 story 檔案包含三層:
- 背景:這個人是誰,他在什麼情境下需要這個功能
- 場景:他具體怎麼操作,系統怎麼響應,每個場景帶
> 关联测试:錨點 - 延伸思考(可選):這個功能未來可能怎麼演進
寫 story 的時候,想象你在跟一個不懂技術的同事講”這個功能是幹什麼的”。如果你能把它講成一個連貫的故事,說明你自己已經想清楚了。
錨點怎麼用
> 关联测试:`TestClassName.test_method_name`這行 Markdown 就是 story 和 test 之間的全部繫結機制。規則很簡單:
- 錨點裡的名字和測試方法的全限定名一致
- 一個場景對應一個測試方法
- 測試檔案的 docstring 裡標註對應的場景編號,方便反向查詢
沒有自動化檢查。如果你想加一個 CI 步驟來檢查錨點是否和測試名匹配,寫個指令碼掃描 stories/*.md 裡的錨點、再對照 tests/ 裡的方法名就行——幾十行 Python 的事。但很多時候,手動保持一致就夠了。
專案結構
my_project/├── stories/ # 用户故事│ ├── todo_api.md│ └── user_auth.md├── tests/│ ├── test_todo_api.py # 从 story 提取的测试│ └── test_user_auth.py├── src/│ └── ... # 实现代码└── story-test-dev.md # 方法说明(可选)Story 檔案和測試檔案的命名保持對應關係:stories/todo_api.md → tests/test_todo_api.py。
什麼時候適合用
- 中小規模專案:Story-Test-Dev 的手動錨點在幾十個場景內完全可控
- API 服務:故事天然適合描述”使用者怎麼調介面”
- AI 輔助開發:把 story 餵給 AI,讓它生成測試程式碼,再生成實現程式碼——story 充當了 AI 的需求文件
- 團隊溝通:故事檔案可以直接發給產品經理或新同事看,不需要解釋 Given/When/Then 是什麼
不太適合的場景:
- 大規模團隊(50+ 人):手動錨點的維護成本會上升,可能需要工具化
- UI 密集型產品:敘事體更適合描述資料流和 API 互動,複雜的 UI 互動用 Playwright 的 codegen 可能更直接
參考資料
參考資料
-
Introducing BDD收藏dannorth.nethttps://dannorth.net/introducing-bdd/ ↩
-
ATDD by Example ↩
-
Specification by Example ↩
-
The Cucumber Book ↩
延伸閱讀
- BDD in the Large