--- title: "#21 - 共讀 Gherkin 文件" tags: Meetups date: 2022-05-19 --- https://cucumber.io/docs/gherkin/reference/ ## Gherkin Reference Gherkin uses a set of special keywords to give structure and meaning to executable specifications. Each keyword is translated to many spoken languages; in this reference we’ll use English. Most lines in a Gherkin document start with one of the keywords. Comments are only permitted at the start of a new line, anywhere in the feature file. They begin with zero or more spaces, followed by a hash sign (`#`) and some text. Block comments are currently not supported by Gherkin. Either spaces or tabs may be used for indentation. The recommended indentation level is two spaces. Here is an example: ```gherkin= Feature: Guess the word # The first example has two steps Scenario: Maker starts a game When the Maker starts a game Then the Maker waits for a Breaker to join # The second example has three steps Scenario: Breaker joins a game Given the Maker has started a game with the word "silky" When the Breaker joins the Maker's game Then the Breaker must guess a word with 5 characters ``` Gherkin由一組的關鍵字組成的結構和有意義可被執行的規格所構成; 可執行的規格(Java, Ruby)等等的語言都可運行, 來驗證驗收目標; 規範/規格, 以非技術人員的視角, 比起驗證來說, 更關心系統功能的清晰描述能力, 在什麼場景下能夠做什麼事情. 每個關鍵字都能轉成口語表達, 甚至關鍵字能支持[多語系](https://cucumber.io/docs/gherkin/languages/). 通常我們都用英語表達, 目的讓團隊成員們能夠進行討論維護, 進而達成開發者與驗收人員們的期望能夠達成一致. 註解由#開始做表示 Space空白鍵和Tab都能被表示成indentation縮排. 推薦的縮排格式是用2個spaces. 以下是範例. 結構最外層的 Feature 是我們的需求。一個需求會有不同的場景。 The trailing portion (after the keyword) of each step is matched to a code block, called a step definition. Please note that some keywords are followed by a colon (`:`) and some are not. If you add a colon after a keyword that should not be followed by one, your test(s) will be ignored. 大部分的關鍵字後面會跟著 ```:``` 但在某些關鍵字後面不該有```:```但卻加上了, 則這些測試將會被忽略. ## Keywords Each line that isn’t a blank line has to start with a Gherkin keyword, followed by any text you like. The only exceptions are the feature and scenario descriptions. The primary keywords are: 主要關鍵字： * Feature * Rule (as of Gherkin 6) * Example (or `Scenario`) * Given, When, Then, And, But for steps (or *) * Background * Scenario Outline (or Scenario Template) * Examples (or Scenarios) There are a few secondary keywords as well: * `"""` (Doc Strings) * `|` (Data Tables) * `@` (Tags) * `#` (Comments) ``` Localisation ``` > Gherkin is localised for many spoken languages; each has their own localised equivalent of these keywords. ``` Feature |- Description |- Rule |- Background |- Given |- And |- Example/Senario |- Given |- When |- Then |- And |- But |- Senario Outline ``` --- ## Feature 該關鍵字是Gherkin文件的第一個關鍵字, 後面會接上```:```做簡單說明. 通常是一個業務功能. 比較高層級描述軟體功能的方法，在下面縮排可以放細節描述。 ```gherkin= Feature: 登入 毫無反應，就是登入 ``` 有些人會在細節描述使用 user story ## Rule 為 Feature 提供額外的訊息。一個 Rule 由一個或多個場景組合而成 ```gherkin= Feature: Rule: Example: ``` ## Example > 與 `Scenario` 同義 針對業務邏輯做詳細描述; 也能說是```劇本```, 會包含了一組[Steps](#Steps) 一個 Example 建議 3 到 5 個步驟描述，太多反而會失焦無法理解功能。 ## Steps 關鍵字 [`Given`](#Given) [`When`](#When) [`Then`](#Then) [`And`](#And-But) [`But`](#And-But) 每個Step在一個Scenario內只會出現一次. ### Given Given 描述測試的上下文情境，與 3A 原則的 Arrange 意義相近。若有多個前置動作，可以使用 `And` 或 `But` 串接。 避免在 Given 裡使用使用者互動行為。 如： ```gherkin= Given 我已登入 ``` ### When 從使用者的角度去描述一個事件，或一個動作。可以是使用者互動行為，或系統事件。 與3A原則的Act相近 如： ```gherkin= When 領錢 ``` 建議一個場景只描述一個 `When`，有多個 When 應該要拆分不同場景 ### Then 描述期望的結果。與3A原則的Assert相近 從使用者的角度去觀察結果，如報告、使用界面、訊息等，若是系統內部的行為則不適合。 ### And But 補充描述 Given When Then ### * 使用類似列表的方法來補充描述 Given When Then ## Background 有時候會發現一個功能(Feature)中的所有場景，重覆同樣的Given步驟.就能把這些重複的Given都搬到```Background```這區塊. 所以Background這區塊都會放在第一個Scenario/Example之前, 兩者在縮排層級上是同等級的. 撰寫小技巧： 1. 不要使用 Background 設定複雜的狀態 2. 保持 Background 短 3. 使用生動的方法描述 4. 保持 Scenarios 短，而且不要太多 ## Scenario Outline 又稱Scenario Template 在模板內使用```< variable_name >```包覆樣本變數 Scenario在一個Feature內出現很多次, 又只是Value得組合不同時可使用. ```gherkin= Scenario Outline: eating Given there are <start> cucumbers When I eat <eat> cucumbers Then I should have <left> cucumbers Examples: | start | eat | left | | 12 | 5 | 7 | | 20 | 5 | 15 | ``` ## [Step Organization](https://cucumber.io/docs/gherkin/step-organization/)