gherkin-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gherkin Authoring

Gherkin 创作指南

Overview

概述

Write Gherkin as executable examples of business behavior. Optimize for domain language, concrete examples, and observable outcomes; keep implementation and UI mechanics inside step definitions.

将Gherkin编写为可执行的业务行为示例。优先使用领域语言、具体示例和可观测结果；将实现细节和UI机制放在步骤定义中。

Scope

适用范围

Use this for standalone

.feature

files and Gherkin embedded in Markdown or other prose. When Gherkin is inside a Markdown wrapper, review or rewrite only the Gherkin section unless the user asks for broader document edits. Preserve fences, headings, and surrounding prose. If the input includes Markdown around the Gherkin, return the Markdown wrapper with only the Gherkin block changed.

本指南适用于独立的

.feature

文件，以及嵌入在Markdown或其他文本中的Gherkin内容。当Gherkin被Markdown包裹时，除非用户要求对文档进行更广泛的编辑，否则仅审阅或重写Gherkin部分。保留代码围栏、标题和周围文本。如果输入包含Gherkin周围的Markdown内容，返回仅修改Gherkin块的Markdown包裹内容。

Workflow

工作流程

Identify the Gherkin region: whole
```
.feature
```
file, fenced
```
gherkin
```
block, indented block, quoted acceptance criteria, or inline scenario text.
Preserve the surrounding wrapper unless explicitly asked to change it. For Markdown input, return the heading/prose/fence context, not just the fenced Gherkin block.
Clarify the behavior as examples: initial state, event, observable outcome.
Choose the smallest structure that expresses the behavior:
```
Feature
```
, optional
```
Rule
```
,
```
Background
```
,
```
Scenario
```
/
```
Example
```
, or
```
Scenario Outline
```
with
```
Examples
```
.
Keep scenarios concrete and short, usually 3-5 steps.
Review syntax and readability before returning: colons, step keywords, duplicate step text, observable outcomes, and table/doc string formatting.

识别Gherkin区域：整个
```
.feature
```
文件、带围栏的
```
gherkin
```
块、缩进块、引用的验收标准或内联场景文本。
保留周围的包裹结构，除非明确要求修改。对于Markdown输入，返回包含标题/文本/围栏的完整上下文，而非仅返回带围栏的Gherkin块。
将行为明确为示例：初始状态、事件、可观测结果。
选择能表达行为的最小结构：
```
Feature
```
、可选的
```
Rule
```
、
```
Background
```
、
```
Scenario
```
/
```
Example
```
，或带有
```
Examples
```
的
```
Scenario Outline
```
。
保持场景具体且简短，通常包含3-5个步骤。
返回前检查语法和可读性：冒号、步骤关键字、重复步骤文本、可观测结果，以及表格/文档字符串的格式。

Quick Reference

速查参考

Construct	Use for	Syntax note
`Feature:`	One high-level capability per feature document or block	Requires `:`
`Rule:`	Group scenarios under one business rule	Requires `:`
`Scenario:` / `Example:`	One concrete example	Requires `:`
`Background:`	Short shared context for following scenarios	Requires `:` ; one per `Feature` or `Rule`
`Scenario Outline:`	Same behavior with varied data	Requires `Examples:` and `<parameter>` placeholders
`Examples:`	Data rows for an outline	Requires `:` and a table
`Given`	Known state or precondition	No `:`
`When`	Event or action	No `:`
`Then`	Observable outcome	No `:`
`And` / `But`	Continue the previous step type	No `:`
`*`	Bullet-like step list	Use sparingly for list-style setup
`@tag`	Group or filter features/scenarios	Place above the item tagged
`#`	Line comment	Line comments only; no block comments
`"""`	Doc String	Passed as final step argument
`	`	Data Table

结构	用途	语法说明
`Feature:`	每个功能文档或块对应一项高级功能	需要加 `:`
`Rule:`	将场景归到某一业务规则下	需要加 `:`
`Scenario:` / `Example:`	一个具体示例	需要加 `:`
`Background:`	后续场景的简短共享上下文	需要加 `:` ；每个 `Feature` 或 `Rule` 下仅能有一个
`Scenario Outline:`	数据不同但行为一致的场景	需要搭配 `Examples:` 和 `<parameter>` 占位符
`Examples:`	场景大纲的数据行	需要加 `:` 和表格
`Given`	已知状态或前置条件	无需加 `:`
`When`	事件或操作	无需加 `:`
`Then`	可观测结果	无需加 `:`
`And` / `But`	延续前一步骤类型	无需加 `:`
`*`	类似项目符号的步骤列表	仅在列表式设置中谨慎使用
`@tag`	分组或筛选功能/场景	放在被标记项的上方
`#`	行注释	仅支持行注释；不支持块注释
`"""`	文档字符串	作为步骤的最终参数传递
`	`	数据表

Authoring Rules

创作规则

Use the language domain experts use. Avoid translating business behavior into UI clicks, HTTP calls, database rows, queues, mocks, or implementation details.
```
Given
```
puts the system in a known state. Avoid user interaction in
```
Given
```
steps.
```
When
```
describes one meaningful event.
```
Then
```
describes an outcome visible to a user or external system. Do not assert hidden database state unless that is the actual external contract.
Use
```
And
```
and
```
But
```
to improve flow, not to hide new phases of the scenario.
Avoid identical step text under different step keywords; Cucumber ignores
```
Given
```
/
```
When
```
/
```
Then
```
when matching step definitions.
Use two-space indentation unless preserving existing style.
Keep
```
Background
```
short and vivid. If it grows beyond about four lines, use higher-level steps or split by
```
Rule
```
/
```
Feature
```
.
Use
```
Scenario Outline
```
only when examples share the same behavior and differ by data.
Escape
```
|
```
as
```
\|
```
, newline as
```
\n
```
, and backslash as
```
\\
```
inside Data Table cells.

使用领域专家的语言。避免将业务行为转化为UI点击、HTTP调用、数据库行、队列、模拟对象或实现细节。
```
Given
```
用于将系统置于已知状态。避免在
```
Given
```
步骤中包含用户交互。
```
When
```
描述一个有意义的事件。
```
Then
```
描述用户或外部系统可见的结果。除非数据库状态是实际的外部契约，否则不要断言隐藏的数据库状态。
使用
```
And
```
和
```
But
```
提升流程流畅度，而非隐藏场景的新阶段。
避免在不同步骤关键字下使用相同的步骤文本；Cucumber匹配步骤定义时会忽略
```
Given
```
/
```
When
```
/
```
Then
```
。
除非需要保留现有格式，否则使用两个空格缩进。
保持
```
Background
```
简短且清晰。如果超过约四行，使用更高层级的步骤或按
```
Rule
```
/
```
Feature
```
拆分。
仅当示例行为相同仅数据不同时，使用
```
Scenario Outline
```
。
在数据表单元格中，将
```
|
```
转义为
```
\|
```
，换行转义为
```
\n
```
，反斜杠转义为
```
\\
```
。

Example

示例

Markdown wrapper preserved; only the Gherkin block is authored:

markdown

undefined

保留Markdown包裹结构；仅创作Gherkin块：

markdown

undefined

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

undefined

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

undefined

Common Mistakes

常见错误

Mistake	Fix
Complaining about Markdown around a Gherkin block	Preserve the wrapper and work only on the Gherkin section.
Returning only a fenced Gherkin block when the input was Markdown	Return the original Markdown wrapper with only the Gherkin content changed.
`Feature Checkout` or `Scenario: Place order:`	Add the missing colon after `Feature` ; remove extra colon from the scenario title.
`Given I click the checkout button`	Move interaction to `When` ; describe state in `Given` .
`Then an order row exists in the database`	Prefer an observable result, such as an order confirmation.
Reusing the same step text for `Given` and `Then`	Change the wording so the domain meaning is distinct.
Long scripts with many UI actions	Raise the abstraction and keep the scenario to the behavior.
Large `Background` sections	Use higher-level context or split scenarios by `Rule` or `Feature` .

错误	修复方案
抱怨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` 拆分场景。