ローカライゼーション
Gherkinは多くの使用言語にローカライズされています。それぞれに、これらのキーワードのローカライズされた同等のものがあります。
Gherkinは、実行可能な仕様に構造と意味を与える特別なキーワードのセットを使用します。各キーワードは多くの言語に翻訳されています。このリファレンスでは、英語を使用します。
Gherkinドキュメントのほとんどの行は、いずれかのキーワードで始まります。
コメントは、フィーチャファイル内の任意の場所にある新しい行の先頭にのみ許可されます。コメントは、ゼロ個以上のスペース、それに続くハッシュ記号（#）、そしてテキストで始まります。
ブロックコメントは、現在Gherkinではサポートされていません。
インデントには、スペースまたはタブを使用できます。推奨されるインデントレベルは2スペースです。例を示します。
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のキーワードで始まり、その後に任意のテキストを続ける必要があります。例外は、Example/Scenario、Background、Scenario Outline、Rule行の下に配置された自由形式の説明です。
主なキーワードは次のとおりです。
FeatureRule（Gherkin 6以降）Example（またはScenario）Given、When、Then、And、But（ステップ用）（または*）BackgroundScenario Outline（またはScenario Template）Examples（またはScenarios）
いくつかの二次的なキーワードもあります。
"""（Doc Strings）|（データテーブル）@（タグ）#（コメント）
Feature
Featureキーワードの目的は、ソフトウェアフィーチャの高レベルな説明を提供し、関連するシナリオをグループ化することです。
Gherkinドキュメントの最初の主要キーワードは常にFeatureでなければならず、その後に:とフィーチャを説明する短いテキストが続きます。
Featureの下に自由形式のテキストを追加して、詳細な説明を追加できます。
これらの説明行は、Cucumberの実行時には無視されますが、レポートに使用できます（公式のHTMLフォーマッタなどのレポートツールによって含まれます）。
Feature: Guess the word
The word guess game is a turn-based game for two players.
The Maker makes a word for the Breaker to guess. The game
is over when the Breaker guesses the Maker's word.
Example: Maker starts a game
名前とオプションの説明は、Cucumberにとって特別な意味を持ちません。それらの目的は、簡単な説明やビジネスルール（一般的な受け入れ基準）のリストなど、フィーチャの重要な側面を文書化するための場所を提供することです。
Featureの自由形式の説明は、Background、Rule、Example、またはScenario Outline（またはそれらのエイリアスキーワード）で始まる行が始まると終了します。
ファイルとディレクトリ構造とは別に、関連するフィーチャをグループ化するために、Featureの上にタグを配置できます。
.featureファイルには、1つのFeatureしか持つことができません。
説明
（Featureについて上記で説明したように）自由形式の説明は、Example/Scenario、Background、Scenario Outline、Ruleの下にも配置できます。
行がキーワードで始まらない限り、好きなものを記述できます。
説明はMarkdown形式にすることができます。公式のHTMLフォーマッタを含むフォーマッタはこれをサポートしています。
Rule
（オプションの）Ruleキーワードは、Gherkin v6以降の一部です。
CucumberにおけるRuleのサポート
Ruleキーワードはまだ比較的新しいものです。多くのCucumber実装ですでに移植されています。しかし、問題が発生した場合は、Cucumber実装のドキュメントを確認して、それがサポートされていることを確認してください。
Ruleキーワードの目的は、実装されるべき1つのビジネスルールを表すことです。フィーチャに追加情報を提供します。Ruleは、このビジネスルールに属するいくつかのシナリオをグループ化するために使用されます。Ruleには、特定のルールを示す1つ以上のシナリオを含める必要があります。
例：
# -- FILE: features/gherkin.rule_example.feature
Feature: Highlander
Rule: There can be only One
Example: Only One -- More than one alive
Given there are 3 ninjas
And there are more than one ninja alive
When 2 ninjas meet, they will fight
Then one ninja dies (but not me)
And there is one ninja less alive
Example: Only One -- One alive
Given there is only 1 ninja alive
Then he (or she) will live forever ;-)
Rule: There can be Two (in some cases)
Example: Two -- Dead and Reborn as Phoenix
...
Example
これは、ビジネスルールを説明する具体的な例です。ステップのリストで構成されています。
キーワードScenarioは、キーワードExampleの同義語です。
ステップの数はいくつでも構いませんが、例ごとに3〜5ステップを推奨します。ステップが多すぎると、例が仕様とドキュメントとしての表現力を失う原因となります。
例は、仕様とドキュメントであることに加えて、テストでもあります。全体として、あなたの例はシステムの実行可能な仕様です。
例は次のパターンに従います。
- 初期コンテキストを記述する（
Givenステップ） - イベントを記述する（
Whenステップ） - 期待される結果を記述する（
Thenステップ）
ステップ
各ステップは、Given、When、Then、And、またはButで始まります。
Cucumberは、シナリオ内の各ステップを記述した順番に1つずつ実行します。Cucumberがステップを実行しようとすると、実行する一致するステップ定義を探します。
ステップ定義を探す際に、キーワードは考慮されません。これは、別のステップと同じテキストを持つGiven、When、Then、And、またはButステップを持つことができないことを意味します。
Cucumberは、次のステップを重複と見なします。
Given there is money in my account
Then there is money in my account
これは制限のように見えるかもしれませんが、より曖昧さがなく、より明確なドメイン言語を考案することを強制します。
Given my account has a balance of £430
Then my account should have a balance of £430
Given
Givenステップは、システムの初期コンテキスト、つまりシナリオの場面を記述するために使用されます。通常は過去に起こったことです。
CucumberがGivenステップを実行すると、オブジェクトの作成と構成、またはテストデータベースへのデータの追加など、システムを明確に定義された状態に設定します。
Givenステップの目的は、ユーザー（または外部システム）がシステムと対話（Whenステップ）し始める前に、システムを既知の状態にすることです。Givenではユーザーとの対話については触れないようにします。ユースケースを作成する場合、Givenは前提条件になります。
複数のGivenステップを使用しても問題ありません（読みやすくするために、2番目以降にはAndまたはButを使用します）。
例
- ミッキーとミニーはゲームを始めました。
- ログインしています。
- ジョーの残高は42ポンドです。
When
Whenステップは、イベントまたはアクションを記述するために使用されます。これは、人がシステムと対話する場合もあれば、別のシステムによってトリガーされるイベントの場合もあります。
例
- 単語を推測する。
- 友達を招待する。
- お金を引き出す。
1922年だと想像してください。
ほとんどのソフトウェアは、人が手動で行うことができることを行います（それほど効率的にではありませんが）。
テクノロジーやユーザーインターフェースに関する前提を一切置かない例を考案するよう努めてください。コンピュータが存在しなかった1922年だと想像してください。
実装の詳細は、ステップ定義に隠す必要があります。
Then
Thenステップは、期待される結果または結果を記述するために使用されます。
Thenステップのステップ定義では、実際の結果（システムが実際に実行すること）と期待される結果（ステップがシステムが実行するべきであると述べていること）を比較するためにアサーションを使用する必要があります。
結果は、観測可能な出力であるべきです。つまり、システムから出力されるもの（レポート、ユーザーインターフェース、メッセージ）であり、システムの内部深く埋め込まれた動作（データベースのレコードなど）ではありません。
例
- 推測された単語が間違っていたことを確認する
- 招待を受ける
- カードが取り込まれるべきである
データベースを調べるために`Then`ステップを実装したくなるかもしれませんが、その誘惑に抵抗してください！
ユーザー（または外部システム）にとって観察可能な結果のみを検証する必要があります。データベースへの変更は通常、観察可能ではありません。
そして、しかし
連続した`Given`または`Then`がある場合、次のように記述できます。
Example: Multiple Givens
Given one thing
Given another thing
Given yet another thing
When I open my eyes
Then I should see something
Then I shouldn't see something else
または、連続した`Given`または`Then`を`And`と`But`で置き換えることで、より流動的な構造の例を作成できます。
Example: Multiple Givens
Given one thing
And another thing
And yet another thing
When I open my eyes
Then I should see something
But I shouldn't see something else
*
Gherkinは、通常のステップキーワードの代わりにアスタリスク（`*`）を使用することもサポートしています。これは、事実上「もののリスト」であるステップがある場合に役立ちます。これにより、そうでなければ`And`などの自然言語ではそれほどエレガントに読めないものを、箇条書きのように表現できます。
例：
Scenario: All done
Given I am out shopping
And I have eggs
And I have milk
And I have butter
When I check my list
Then I don't need anything
次のように表現できます
Scenario: All done
Given I am out shopping
* I have eggs
* I have milk
* I have butter
When I check my list
Then I don't need anything
背景
時々、`Feature`内のすべてのシナリオで同じ`Given`ステップを繰り返していることに気付くでしょう。
これは、すべてのシナリオで繰り返されるため、これらのステップはシナリオを記述するために「不可欠」ではなく、「付随的な詳細」であることを示しています。そのような`Given`ステップは、`Background`セクションの下にグループ化することで、文字通りバックグラウンドに移動できます。
`Background`を使用すると、それに続くシナリオにコンテキストを追加できます。1つ以上の`Given`ステップを含めることができ、これらは各シナリオの前に実行されますが、任意のBeforeフックの後です。
`Background`は、最初の`Scenario` / `Example`の前に、同じインデントレベルに配置されます。
例：
Feature: Multiple site support
Only blog owners can post to a blog, except administrators,
who can post to all blogs.
Background:
Given a global administrator named "Greg"
And a blog named "Greg's anti-tax rants"
And a customer named "Dr. Bill"
And a blog named "Expensive Therapy" owned by "Dr. Bill"
Scenario: Dr. Bill posts to his own blog
Given I am logged in as Dr. Bill
When I try to post to "Expensive Therapy"
Then I should see "Your article was published."
Scenario: Dr. Bill tries to post to somebody else's blog, and fails
Given I am logged in as Dr. Bill
When I try to post to "Greg's anti-tax rants"
Then I should see "Hey! That's not your blog!"
Scenario: Greg posts to a client's blog
Given I am logged in as Greg
When I try to post to "Expensive Therapy"
Then I should see "Your article was published."
`Background`は、たとえば`Rule`レベルでもサポートされています。
Feature: Overdue tasks
Let users know when tasks are overdue, even when using other
features of the app
Rule: Users are notified about overdue tasks on first use of the day
Background:
Given I have overdue tasks
Example: First use of the day
Given I last used the app yesterday
When I use the app
Then I am notified about overdue tasks
Example: Already used today
Given I last used the app earlier today
When I use the app
Then I am not notified about overdue tasks
...
`Feature`または`Rule`ごとに`Background`ステップのセットを1つだけ持つことができます。異なるシナリオに異なる`Background`ステップが必要な場合は、シナリオのセットをより多くの`Rule`またはより多くの`Feature`に分割することを検討してください。
`Background`のより明示的でない代替手段については、条件付きフックを確認してください。
Backgroundの使用に関するヒント
- クライアントが実際に知る必要がある状態でない限り、`Background`を使用して**複雑な状態**を設定しないでください。
- たとえば、ユーザー名とサイト名がクライアントにとって重要でない場合は、`Given I am logged in as a site owner`などのより高レベルのステップを使用します。
- `Background`セクションを**短く**保ちます。
- クライアントは、シナリオを読む際にこれらの情報を実際に覚えておく必要があります。`Background`が4行を超える場合は、関連性の低い詳細の一部をより高レベルのステップに移動することを検討してください。
- `Background`セクションを**鮮やかに**します。
- カラフルな名前を使用し、ストーリーを語るようにしてください。人間の脳は、「User A」、「User B」、「Site 1」などの名前よりも、ストーリーをはるかにうまく追跡します。
- シナリオを**短く**保ち、あまり多く作成しないでください。
- `Background`セクションが画面からスクロールされた場合、読者は何が起こっているのかを完全に把握できなくなります。より高レベルのステップを使用するか、`*.feature`ファイルを分割することを検討してください。
Scenario Outline
`Scenario Outline`キーワードは、異なる値の組み合わせで同じ`Scenario`を複数回実行するために使用できます。
`Scenario Template`キーワードは`Scenario Outline`キーワードの同義語です。
異なる値を使用するためにシナリオをコピーして貼り付けることは、すぐに面倒で反復的になります。
Scenario: eat 5 out of 12
Given there are 12 cucumbers
When I eat 5 cucumbers
Then I should have 7 cucumbers
Scenario: eat 5 out of 20
Given there are 20 cucumbers
When I eat 5 cucumbers
Then I should have 15 cucumbers
これらの2つの類似したシナリオを`Scenario Outline`にまとめることができます。
Scenario Outlineを使用すると、`< >`で区切られたパラメーターを使用して、これらのシナリオをより簡潔に表現できます。
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 |
Examples
`Scenario Outline`には、1つ以上の`Examples`(または`Scenarios`)セクションが含まれている必要があります。そのステップは、直接実行されることのないテンプレートとして解釈されます。代わりに、`Scenario Outline`は、その下の`Examples`セクションの各行（最初のヘッダー行を除く）に対して1回実行されます。
ステップは、例テーブルのヘッダーを参照する`< >`で区切られた*パラメーター*を使用できます。Cucumberは、ステップをステップ定義と照合しようとする*前*に、これらのパラメーターをテーブルからの値で置き換えます。
複数行ステップ引数でもパラメーターを使用できます。
ステップ引数
場合によっては、1行に収まるよりも多くのデータをステップに渡したい場合があります。この目的のために、Gherkinには`Doc Strings`と`Data Tables`があります。
Doc Strings
`Doc Strings`は、より大きなテキストをステップ定義に渡すのに便利です。
テキストは、独自の行にある3つの二重引用符で構成されるデリミタでオフセットする必要があります。
Given a blog post named "Random" with Markdown body
"""
Some Title, Eh?
===============
Here is the first paragraph of my blog post. Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
"""
ステップ定義では、このテキストを見つけてパターンに一致させる必要はありません。ステップ定義の最後の引数として自動的に渡されます。
開始`"""`のインデントは重要ではありませんが、一般的な慣例は、囲んでいるステップから2つのスペースです。ただし、3重引用符内のインデントは重要です。Doc Stringの各行は、開始`"""`に従ってインデントが解除されます。開始`"""`の列を超えるインデントは、保持されます。
Doc Stringsは、デリミタとして3つのバックティックを使用することもサポートしています。
Given a blog post named "Random" with Markdown body
```
Some Title, Eh?
===============
Here is the first paragraph of my blog post. Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
```
Markdownで記述することに慣れている人には、これは馴染みがあるかもしれません。
バックティックのツールサポート
現在のすべてのバージョンのCucumberはデリミタとしてバックティックをサポートしていますが、テキストエディターなどの多くのツールはまだサポートしていません。
含まれるコンテンツの種類でDocStringに注釈を付けることができます。コンテンツの種類は、3重引用符の後に次のように指定します。
Given a blog post named "Random" with Markdown body
"""markdown
Some Title, Eh?
===============
Here is the first paragraph of my blog post. Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
"""
コンテンツタイプのツールサポート
現在のすべてのバージョンのCucumberはデリミタとしてコンテンツタイプをサポートしていますが、テキストエディターなどの多くのツールはまだサポートしていません。
Data Tables
`Data Tables`は、値のリストをステップ定義に渡すのに便利です。
Given the following users exist:
| name | email | twitter |
| Aslak | aslak@cucumber.io | @aslak_hellesoy |
| Julien | julien@cucumber.io | @jbpros |
| Matt | matt@cucumber.io | @mattwynne |
`Doc Strings`と同様に、`Data Tables`はステップ定義に最後の引数として渡されます。
表セルのエスケープ
表セルの改行文字を使用する場合は、`\n`として記述できます。セルの一部として`|`が必要な場合は、`\|`としてエスケープできます。最後に、`\`が必要な場合は、`\\`でエスケープできます。
Data Table API
Cucumberは、ステップ定義内からテーブルを操作するための豊富なAPIを提供しています。詳細については、Data Table APIリファレンスを参照してください。
使用言語
Gherkinで選択する言語は、ユーザーとドメインエキスパートがドメインについて話す際に使用する言語と同じである必要があります。2つの言語間の翻訳は避けるべきです。
そのため、Gherkinは70以上の言語に翻訳されています。
ノルウェー語で記述されたGherkinシナリオを次に示します。
# language: no
Funksjonalitet: Gjett et ord
Eksempel: Ordmaker starter et spill
Når Ordmaker starter et spill
Så må Ordmaker vente på at Gjetter blir med
Eksempel: Gjetter blir med
Gitt at Ordmaker har startet et spill med ordet "bløtt"
Når Gjetter blir med på Ordmakers spill
Så må Gjetter gjette et ord på 5 bokstaver
フィーチャファイルの最初の行にある`# language:`ヘッダーは、使用する言語をCucumberに指示します。たとえば、フランス語の場合は`# language: fr`です。このヘッダーを省略すると、Cucumberはデフォルトで英語（`en`）になります。
一部のCucumber実装では、構成でデフォルトの言語を設定することもできるため、すべてのファイルに`# language`ヘッダーを配置する必要はありません。