Back to Details

bdd-gherkin-specification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

BDD & Gherkin Specification

BDD与Gherkin规范

You are an expert in Behavior-Driven Development (BDD) and Gherkin specification writing. This skill helps you create clear, executable specifications that bridge business requirements and technical implementation.
您是行为驱动开发（BDD）和Gherkin规范编写方面的专家。本技能可帮助您创建清晰、可执行的规范，衔接业务需求与技术实现。

What is BDD?

什么是BDD？

BDD is a methodology for capturing requirements that expresses the behavior of features using real-world examples. It bridges the gap between business stakeholders, developers, and testers by using shared language and concrete scenarios.
BDD是一种捕获需求的方法论，它通过真实世界的示例来表达功能的行为。它使用通用语言和具体场景，弥合业务利益相关者、开发人员和测试人员之间的差距。

What is Gherkin?

什么是Gherkin？

Gherkin is a plain-text language for writing BDD scenarios using keywords like Feature, Scenario, Given, When, Then. It's human-readable, business-focused, and executable as automated tests.
Gherkin是一种纯文本语言，用于使用Feature、Scenario、Given、When、Then等关键字编写BDD场景。它易于人类阅读、以业务为中心，并且可以作为自动化测试执行。

When to Use This Skill

何时使用本技能

USE when:
  • Defining acceptance criteria for user stories
  • Creating living documentation
  • Bridging communication gaps between technical and non-technical stakeholders
  • Specifying complex business rules
  • Working in cross-functional teams
DO NOT USE when:
  • Requirements are purely technical (architecture, refactoring)
  • Team is small and co-located with constant communication
  • Features are too simple to warrant formal specification
适用场景：
  • 定义用户故事的验收标准
  • 创建活文档
  • 弥合技术与非技术利益相关者之间的沟通差距
  • 明确复杂的业务规则
  • 在跨职能团队中工作
不适用场景：
  • 需求纯技术性（架构、重构）
  • 团队规模小且集中办公，沟通频繁
  • 功能过于简单，无需正式规范

Quick Start

快速入门

Basic Gherkin Structure:
gherkin
Feature: User Login

  Scenario: Successful login with valid credentials
    Given the user is on the login page
    When the user enters valid credentials
    Then the user should be redirected to the dashboard
Gherkin基本结构：
gherkin
Feature: User Login

  Scenario: Successful login with valid credentials
    Given the user is on the login page
    When the user enters valid credentials
    Then the user should be redirected to the dashboard

Available Resources

可用资源

Core Documentation

核心文档

  • gherkin-syntax.md - Complete Gherkin language reference
    • Basic structure and file naming
    • Given-When-Then detailed explanation
    • All keywords (Feature, Scenario, Background, Scenario Outline, Rule)
    • AND/BUT usage
    • Read when: Writing your first feature file or need keyword reference
  • best-practices.md - Writing effective scenarios
    • Declarative vs imperative style
    • Keep scenarios focused and independent
    • Consistent language and perspective
    • Clear outcomes and business value
    • Read when: Reviewing or improving scenario quality
  • examples.md - Real-world feature file examples
    • Complete feature files across different domains
    • Product search, shopping cart, authentication
    • Background and Scenario Outline usage
    • Side-by-side comparisons (good vs bad)
    • Read when: Need inspiration or want to see patterns in action
  • gherkin-syntax.md - 完整的Gherkin语言参考
    • 基本结构和文件命名
    • Given-When-Then详细说明
    • 所有关键字（Feature、Scenario、Background、Scenario Outline、Rule）
    • AND/BUT的用法
    • 阅读时机：编写第一个特性文件或需要关键字参考时
  • best-practices.md - 编写有效场景的最佳实践
    • 声明式与命令式风格
    • 保持场景聚焦且独立
    • 一致的语言和视角
    • 清晰的结果和业务价值
    • 阅读时机：评审或提升场景质量时
  • examples.md - 真实世界的特性文件示例
    • 不同领域的完整特性文件
    • 产品搜索、购物车、身份验证
    • Background和Scenario Outline的用法
    • 优劣对比（好 vs 坏）
    • 阅读时机：需要灵感或想了解实际模式时

Advanced Topics

高级主题

  • anti-patterns.md - Common mistakes and how to avoid them
    • Testing implementation vs behavior
    • Overly technical language
    • Dependent scenarios
    • UI-centric vs behavior-centric
    • Read when: Troubleshooting or code review
  • organization.md - Structuring large feature file suites
    • Directory structure patterns
    • When to split features
    • Using Rules to group scenarios
    • Team collaboration patterns
    • Read when: Setting up project structure or scaling BDD adoption
  • quick-reference.md - Cheat sheet and templates
    • Feature file template to copy
    • Keywords at a glance
    • Common patterns
    • Quick decision tree
    • Read when: Need fast lookup or reminder
  • anti-patterns.md - 常见错误及避免方法
    • 测试实现 vs 测试行为
    • 过于技术化的语言
    • 依赖场景
    • 以UI为中心 vs 以行为为中心
    • 阅读时机：故障排查或代码评审时
  • organization.md - 构建大型特性文件套件
    • 目录结构模式
    • 何时拆分功能
    • 使用Rule对场景进行分组
    • 团队协作模式
    • 阅读时机：设置项目结构或扩展BDD应用时
  • quick-reference.md - 速查表和模板
    • 可复制的特性文件模板
    • 关键字一览
    • 常见模式
    • 快速决策树
    • 阅读时机：需要快速查找或提醒时

Key Principles

核心原则

  1. Be Declarative - Describe WHAT behavior should happen, not HOW it's implemented
  2. Stay Focused - One scenario = one behavior (5-10 steps max)
  3. Stay Independent - Scenarios should not depend on each other
  4. Use Business Language - Avoid technical jargon; speak the user's language
  5. Make it Readable - Anyone on the team should understand the scenario
  1. 采用声明式风格 - 描述应该发生什么行为，而不是如何实现
  2. 保持聚焦 - 一个场景对应一个行为（最多5-10个步骤）
  3. 保持独立 - 场景之间不应相互依赖
  4. 使用业务语言 - 避免技术术语；使用用户的语言
  5. 确保可读性 - 团队中的任何人都应能理解场景

Typical Workflow

典型工作流程

  1. Start with Examples - Read examples.md to see patterns
  2. Learn Syntax - Reference gherkin-syntax.md for keywords
  3. Write Scenarios - Use quick-reference.md template
  4. Review Quality - Check against best-practices.md
  5. Avoid Mistakes - Scan anti-patterns.md during review
  1. 从示例开始 - 阅读examples.md了解模式
  2. 学习语法 - 参考gherkin-syntax.md掌握关键字
  3. 编写场景 - 使用quick-reference.md的模板
  4. 评审质量 - 对照best-practices.md检查
  5. 避免错误 - 评审时查看anti-patterns.md

Quick Tips

快速提示

  • Write scenarios BEFORE code (they're specifications, not tests)
  • Each scenario should be understandable in isolation
  • Use Background for common setup across scenarios
  • Use Scenario Outline for testing multiple similar cases
  • Use Rule to group related scenarios
  • Keep feature files under 20 scenarios (split if larger)
  • 在编写代码之前编写场景（它们是规范，不是测试脚本）
  • 每个场景应能独立理解
  • 对多个场景的通用设置使用Background
  • 对多个相似案例使用Scenario Outline
  • 使用Rule对相关场景进行分组
  • 特性文件场景数控制在20个以内（超过则拆分）

File Naming Convention

文件命名规范

Use lowercase with underscores: 
user_authentication.feature
, 
shopping_cart_checkout.feature
使用小写加下划线：
user_authentication.feature
、
shopping_cart_checkout.feature

Remember

谨记

BDD scenarios are conversations written down, not test scripts. They should be readable by product owners, developers, and testers alike. If your scenario requires technical knowledge to understand, it's not declarative enough.
For comprehensive guidance, explore the reference/ directory based on your current need.
BDD场景是记录下来的对话，而不是测试脚本。产品负责人、开发人员和测试人员都应能轻松阅读。如果您的场景需要专业技术知识才能理解，说明它不够声明式。
如需全面指导，请根据当前需求探索reference/目录下的内容。