gherkin-authoring

Gherkin の作成

概要

Gherkin は、ビジネス上の振る舞いを実行可能な例として記述します。ドメイン用語、具体例、観測可能な結果を重視し、実装や UI の仕組みはステップ定義の中に収めます。

対象範囲

スタンドアロンの .feature ファイルと、Markdown やその他の文章に埋め込まれた Gherkin に使用します。Gherkin が Markdown のラッパー内にある場合、ユーザーが文書全体の編集を依頼していない限り、Gherkin のセクションだけを確認または書き換えます。フェンス、見出し、周囲の文章は保持します。入力に Gherkin を囲む Markdown が含まれる場合は、Gherkin ブロックだけを変更し、Markdown のラッパーも含めて返します。

ワークフロー

1. Gherkin の範囲を特定します。ファイル全体の .feature、フェンスで囲まれた gherkin ブロック、インデントされたブロック、引用された受け入れ条件、シナリオのインラインテキストなどです。
2. 明示的に変更を依頼されていない限り、周囲のラッパーを保持します。Markdown 入力の場合は、フェンスで囲まれた Gherkin ブロックだけではなく、見出し、文章、フェンスの文脈も含めて返します。
3. 振る舞いを例として明確にします。初期状態、イベント、観測可能な結果を示します。
4. 振る舞いを表現できる最小限の構成を選びます。Feature、任意の Rule、Background、Scenario／Example、または Examples を伴う Scenario Outline です。
5. シナリオは具体的で短くし、通常は 3～5 ステップにします。
6. 返す前に、構文と読みやすさを確認します。コロン、ステップキーワード、重複するステップテキスト、観測可能な結果、テーブル／ドック文字列の書式を確認します。

クイックリファレンス

構文	用途	構文上の注意
Feature:	機能ドキュメントまたはブロックごとに 1 つの上位機能を記述します	: が必要です
Rule:	1 つのビジネスルールに関連するシナリオをまとめます	: が必要です
Scenario: / Example:	具体例を 1 つ記述します	: が必要です
Background:	後続のシナリオに共通する短い文脈を記述します	: が必要です。Feature または Rule ごとに 1 つです
Scenario Outline:	データを変えて同じ振る舞いを記述します	Examples: と <parameter> プレースホルダーが必要です
Examples:	アウトライン用のデータ行を記述します	: とテーブルが必要です
Given	既知の状態または前提条件を示します	: は不要です
When	イベントまたはアクションを示します	: は不要です
Then	観測可能な結果を示します	: は不要です
And / But	直前のステップの種類を引き継ぎます	: は不要です
*	箇条書きのようなステップリストを示します	リスト形式のセットアップに限って使用します
@tag	機能またはシナリオを分類、フィルタリングします	タグを付ける項目の上に配置します
#	行コメントを示します	行コメントのみです。ブロックコメントはありません
"""	ドック文字列を示します	最終ステップ引数として渡されます
`	`	データテーブルを示します

作成ルール

• ドメインの専門家が使う言葉を使います。ビジネス上の振る舞いを、UI のクリック、HTTP 呼び出し、データベースの行、キュー、モック、実装の詳細に置き換えないでください。
• Given ではシステムを既知の状態にします。Given ステップでのユーザー操作は避けてください。
• When には意味のあるイベントを 1 つ記述します。
• Then にはユーザーまたは外部システムから見える結果を記述します。実際の外部契約でない限り、隠れたデータベースの状態をアサートしないでください。
• And と But は流れをよくするために使い、シナリオに新たな段階を隠さないでください。
• 異なるステップキーワードの下で同じステップテキストを使わないでください。ステップ定義を照合する際、Cucumber は Given／When／Then を無視します。
• 既存のスタイルを維持する場合を除き、インデントは 2 つのスペースにします。
• Background は短く、具体的にします。4 行程度を超える場合は、より上位のステップを使うか、Rule／Feature ごとに分割します。
• データが異なるだけで振る舞いが同じ場合に限り、Scenario Outline を使います。
• データテーブルのセル内では、| は \|、改行は \n、バックスラッシュは \\ としてエスケープします。

例

Markdown のラッパーを保持し、Gherkin ブロックのみを作成します。

## Acceptance Criteria

```gherkin
Feature: Password reset
  Rule: Reset links expire after their allowed lifetime

    Scenario: Customer resets their password before the link expires
      Given Priya has requested a password reset
      And the reset link is still valid
      When Priya chooses a new password with the reset link
      Then she can sign in with the new password

    Scenario: Customer uses an expired reset link
      Given Priya has requested a password reset
      And the reset link has expired
      When Priya tries to choose a new password with the reset link
      Then she is told the reset link has expired
      And her password is unchanged
```

よくある間違い

間違い	修正方法
Gherkin ブロックの周囲にある Markdown について不満を述べる	ラッパーをそのまま保持し、Gherkin セクションのみを対象にします。
入力が Markdown だったのに、フェンス付き Gherkin ブロックだけを返す	元の Markdown ラッパーを保持し、Gherkin の内容のみを変更して返します。
Feature Checkout または Scenario: Place order:	Feature の後に不足しているコロンを追加し、シナリオタイトルの余分なコロンを削除します。
Given I click the checkout button	インタラクションを When に移し、状態は Given で説明します。
Then an order row exists in the database	注文確認など、観察可能な結果を優先します。
Given と Then で同じステップテキストを再利用する	ドメイン上の意味が異なることが分かるように表現を変更します。
UI 操作が多数ある長いスクリプト	抽象度を上げ、シナリオを振る舞いに絞ります。
大きな Background セクション	より高いレベルのコンテキストを使うか、Rule または Feature ごとにシナリオを分割します。