gherkin-authoring

Gherkin 编写

概述

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

范围

适用于独立的 .feature 文件，以及嵌入 Markdown 或其他文本中的 Gherkin。如果 Gherkin 位于 Markdown 包装内容中，除非用户要求编辑更广泛的文档，否则只检查或重写 Gherkin 部分。保留围栏、标题和周围文本。如果输入中包含 Gherkin 周围的 Markdown，返回 Markdown 包装内容，只修改 Gherkin 块。

工作流

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

快速参考

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

编写规则

• 使用领域专家采用的语言。避免将业务行为转换为 UI 点击、HTTP 调用、数据库行、队列、模拟对象或实现细节。
• Given 用于设定系统的已知状态。避免在 Given 步骤中描述用户交互。
• When 描述一个有意义的事件。
• Then 描述用户或外部系统可见的结果。除非隐藏的数据库状态就是实际的外部契约，否则不要断言该状态。
• 使用 And 和 But 改善流程，不要用它们来隐藏场景的新阶段。
• 避免在不同步骤关键字下使用相同的步骤文本；Cucumber 在匹配步骤定义时会忽略 Given/When/Then。
• 除非要保留现有风格，否则使用两个空格缩进。
• Background 应简短鲜明。如果超过约四行，请使用更高级别的步骤，或按 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 拆分场景。