specformula-feature

SpecFormula Feature 撰寫指南

SpecFormula 的 .feature 檔案使用 Gherkin DSL 搭配 ISA 指令與符號系統，以宣告式語法定義 BDD 測試。每個指令的 Gherkin 語法由 isa.yml 的 instructions[].format 正則表達式定義，撰寫前請先查看專案的 isa.yml 確認實際格式。

撰寫 SOP

新增 Feature

規劃新功能的完整測試檔案，依照 Step 1 → Step 2 → Step 3 流程撰寫所有 Scenario。

新增 Scenario

在現有 .feature 檔案中新增測試場景，依照 Step 1 → Step 2 → Step 3 流程撰寫。

新增 Step

在現有 Scenario 中新增步驟，根據步驟類型（Given / When / Then）參考對應的決策樹。

Step 1：前置條件（Given）

根據測試場景需要的初始狀態，判斷需要哪些前置條件：

• 測試涉及時間相關欄位（如 createdAt、updatedAt）？→ TimeControl（讀取 time-control.md）
• 測試需要模擬時間推移？→ 多次 TimeControl（讀取 time-control.md）
• 需要準備資料？→ EntitySetup（讀取 entity-setup.md）
• 需要前置 API 流程？→ ApiCall（讀取 api-call.md）
• 需要自訂步驟？→ Custom（讀取 custom.md）

Background:
  # 1. 固定時間
  Given 現在時間為 "2026-01-27T10:00:00"
  # 2. 直接插入資料庫
  Given 準備一個使用者, with table:
    | >Alice.id | name  | email             | passwordHash | status |
    | <userId   | Alice | [email protected] | password123  | ACTIVE |

Step 2：事件（When）

• 執行 HTTP API 請求？→ ApiCall（讀取 api-call.md）
• 需要自訂步驟？→ Custom（讀取 custom.md）

  # 前置 API（取得 Token）
  When (No Actor) 使用者登入, call table:
    | >AliceToken | email             | password    |
    | <token      | [email protected] | password123 |
  # 被測試的 API
  When (UID="$Alice.id") 新增待辦事項, call table:
    | >todo1.id | title  | description |
    | <todoId   | 買牛奶 | 去全聯買    |

Step 3：後置條件驗證（Then）

驗證事件執行後的結果：

• 驗證 API 狀態碼與回應內容？→ ResponseValidate（讀取 response-validate.md）
• 需要存在特定資料？→ EntityValidate（讀取 entity-validate.md）
• 需要不存在特定資料？→ EntityNonExistenceValidate（讀取 entity-non-existence-validate.md）
• 需要自訂步驟？→ Custom（讀取 custom.md）

  # 1. 回應驗證
  Then 新增待辦事項(201)回應, with table:
    | todoId    | userId    | title  | completed |
    | $todo1.id | $Alice.id | 買牛奶 | false     |
  # 2. 資料庫狀態驗證
  And 應該存在一個待辦事項, with table:
    | todoId    | userId    | title  | completed | createdAt                        |
    | $todo1.id | $Alice.id | 買牛奶 | false     | &sameTime("2026-01-27T10:00:00") |