# [ACCUPASS] BDD - Gherkin（小黃瓜）開發文件筆記

###### tags `Work` `ACCUPASS`

<div style="display: flex; justify-content: flex-end">

> created: 2024/09/02

</div>

## 前言

上上週技術長有分享 BDD 的開發理念，並告知 RD 開發時都未留下相關文件，造成日後維運困難。為了解決這個問題，他提到 RD 開發完畢後需寫文件，讓日後 QA 及 PM 甚至是改朝換代的時候後人可以看到這裡開發的規格。因為目前後端 team 人力吃緊，因此他特別提到前端可以先行實作，因此才有這份筆記兼文件模板。

## 範例

（技術長在分享會時提供的範例）

- 以功能（feature）為主軸，一個功能有許多場景（scenario）
- 一個場景（scenario）會有基本的 Given、When、Then及 [And, But]，**且不管是 Given、When 還是 Then，一行只能做一件事情**
- Given: 前置條件，如背景知識或是起始狀態
- When: 一個動作或是事件
- Then: 預期的結果
- And: 當 Given, When 或者 Then 沒辦法只能用一行（一件事情）描述完，用 And 接續描述
- But: 表示與上一個情況的相反情形

（關鍵字對應的中文翻譯）

## 需要注意的地方

### 1. 避免過於細小的 UI 細節

身為前端 UI 的流程很重要，但是過於細小的 UI 細節對於文件沒有必要，而且到時候設計修改的話就會讓文件的維護很困難。所以我認為驗證基本的流程型 UI 就行了：

功能（Feature）：Excel 上傳彈窗流程

場景（Scenario）：顯示上傳 Excel 檔案的說明彈窗
前置條件（Given）使用者未上傳任何 Excel 檔案
當（When）使用者點擊上傳名單按鈕
那麼（Then）會出現說明上傳 Excel 的彈窗，其彈窗供使用者觀看說明並可上傳檔案

:::info
僅寫出流程需要的 UI，而不是描述 UI 的 style 等對於流程無關的資訊。
:::

### 2. 避免過多的細節

表單輸入不需要全部欄位寫出來，因為這個不算是商業邏輯的流程範疇內：

# ref. https://ithelp.ithome.com.tw/articles/10226615

Scenario: 抽獎活動抽號碼牌
Given 我想要抽獎
When 我進入了抽獎頁面
And 我填了我的姓名在 '.name' 欄位
And 我填了我的聯絡電話在 '.phone' 欄位
And 我填了我的 Email 在 '.email' 欄位
And 我填了我的縣市在 '.city' 欄位
And 我填了我的詳細地址在 '.street' 欄位
And 我填了我的郵遞區號在 '.post_code' 欄位
And 我點擊了抽號碼牌的按鈕
Then 我應該得到了一個抽獎號碼牌
And 我應該得到一封 Email 通知包含號碼牌資訊

# ref. https://ithelp.ithome.com.tw/articles/10226615

Scenario: 抽獎活動抽號碼牌
Given 我想要抽獎因此填了以下資訊：
  # 表單欄位等不是商業邏輯的流程不需要寫過於複雜 => 商業邏輯的流程 > 介面邏輯操作的流程
  | name | email         | phone      | city   | street     | postcode | ... |
  | John | [e-mail] | 0912121212 | Taipei | Xinyi Road | 123      | ... |
When 我抽了號碼牌
Then 我應該得到了一個抽獎號碼牌
And 我應該得到一封 Email 通知包含號碼牌資訊

## 使用模板

這裡是每次功能開發時要加工的地方！

功能（Feature）：

場景（Scenario）：
前置條件（Given）
當（When）
那麼（Then）

[並且（And）, But]

## 參考資料

1. [BDD - 如何寫出好的 Gherkin 語法展示你的 Specification By Examples](https://ithelp.ithome.com.tw/articles/10226615)