先講故事,再寫程式碼 左邊一本攤開的故事書,左頁畫著小王端著咖啡,右頁寫著場景 1 和高亮的“關聯測試”錨點;錨點牽出一根虛線,連到右邊的測試程式碼卡片,卡片旁蓋著一枚綠色的透過印章。 小王的一天 場景 1 > 關聯測試

需求文件沒人看,Cucumber 太重,但你又想在動手寫程式碼之前把事情想清楚。

你有沒有遇到過這種情況——

產品經理寫了一頁需求文件,開發看了兩眼就開始寫程式碼。寫完發現理解有偏差,返工。下次換成 Jira ticket,列了一堆驗收條件,開發對著清單一條一條打勾,功能”驗收透過”了,但用起來彆扭——因為沒有人從頭到尾想過”使用者到底是怎麼用這個東西的”。

BDD 試圖解決這個問題:用 Given/When/Then 把行為寫出來,直接跑。但 Cucumber 的學習成本、step definition 的維護成本、結構化語法的表達力限制,讓很多團隊試了又放棄了。

Story-Test-Dev 是一個更輕量的方案。 核心想法很簡單:

Story(写故事) → Test(提取测试) → Dev(实现代码)
  1. Story:用自由敘事體寫使用者故事——有人物、有場景、有動機,像在講一個人怎麼用你的產品
  2. Test:從故事中提取測試用例,用 > 关联测试:TestXxx 錨點把場景和測試關聯起來
  3. Dev:實現程式碼,讓測試透過

不需要安裝框架,不需要學 DSL。Markdown + pytest,完事。


Part 1: WHAT — 一個完整的例子

空談方法論沒有用。我們用一個”待辦事項 API”從頭走一遍。

寫 Story

建立 stories/todo_api.md:

Markdown
# 待办事项 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:

Python
"""Tests for Todo API — derived from stories/todo_api.md"""
import pytest
import 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 / CucumberStory-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 檔案包含三層:

  1. 背景:這個人是誰,他在什麼情境下需要這個功能
  2. 場景:他具體怎麼操作,系統怎麼響應,每個場景帶 > 关联测试: 錨點
  3. 延伸思考(可選):這個功能未來可能怎麼演進

寫 story 的時候,想象你在跟一個不懂技術的同事講”這個功能是幹什麼的”。如果你能把它講成一個連貫的故事,說明你自己已經想清楚了。

錨點怎麼用

Markdown
> 关联测试:`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 可能更直接

參考資料

參考資料

  1. Introducing BDD收藏dannorth.nethttps://dannorth.net/introducing-bdd/ ↩

  2. ATDD by ExampleMarkus Gärtner · 2012 ↩

  3. Specification by ExampleGojko Adzic · 2011 ↩

  4. The Cucumber BookMatt Wynne, Aslak Hellesøy · 2012 ↩

延伸閱讀

  • BDD in the LargeLiz Keogh