add-cucumber-tests

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BDD Test Generation with Tzatziki

基于Tzatziki的BDD测试生成

Generate valid Cucumber

.feature

files from a user's functional specification, using Tzatziki's step definition library as the source of truth for legal step patterns.

以Tzatziki的步骤定义库作为合法步骤模式的唯一可信来源，根据用户提供的功能规范生成有效的Cucumber

.feature

文件。

Principles

原则

These explain the reasoning behind the workflow — understanding them helps you handle edge cases the workflow doesn't explicitly cover.

Steps come from code, not imagination. Tzatziki provides hundreds of pre-built
```
@Given
```
/
```
@When
```
/
```
@Then
```
patterns in its
```
*Steps.java
```
files. Inventing step text that doesn't match a real definition produces
```
UndefinedStepException
```
at runtime. Per-module reference files in
```
references/steps-*.md
```
contain every legal step pattern — read the relevant ones before writing any scenario.
Verify the environment before writing tests. Run at least one existing Cucumber test in the target module before creating new feature files. This catches missing dependencies, broken bootstrap, or misconfigured runners early — before you've invested effort in writing scenarios that can't execute. If no test exists yet, create the minimal bootstrap first and confirm it discovers at least one scenario.
YAML by default for structured data. Tzatziki scenarios are most readable when request bodies, database fixtures, Kafka payloads, and expected results use
```
"""yml
```
doc strings. Fall back to Gherkin tables for naturally tabular data, or raw JSON only when the contract requires it.
Cover exactly what the user asked for — then help them think about what they missed. Generate scenarios for every functional behavior in the user's specification — not just the happy path. But don't silently add extra scenarios either. Instead, after covering the requested scope, actively identify edge cases and present them to the user as optional additions. To identify edge cases effectively, look at three things: (a) every external service call in the scenario — what happens if it returns an error (4xx, 5xx) or times out? (b) every data collection — what happens if it's empty or contains unexpected values? (c) existing test files in the project that test similar features — they often contain error-handling patterns you can adapt for the new scenario. The user decides which edge cases to include, but your job is to surface them so nothing important is missed.
Reuse what exists. If the project already has a runner, bootstrap class, feature location convention, or glue configuration — reuse them. Creating duplicates causes classpath conflicts and confuses test discovery.

以下是该工作流背后的设计逻辑——理解这些原则可以帮助你处理工作流未明确覆盖的边缘场景。

步骤来自实际代码，而非主观想象。 Tzatziki在其
```
*Steps.java
```
文件中提供了数百个预构建的
```
@Given
```
/
```
@When
```
/
```
@Then
```
模式。自行编造与实际定义不匹配的步骤文本会在运行时抛出
```
UndefinedStepException
```
。
```
references/steps-*.md
```
下的分模块参考文件包含了所有合法的步骤模式——编写任何场景前请先阅读相关参考文档。
编写测试前先验证环境。 创建新的feature文件前，请先在目标模块中运行至少一个已有的Cucumber测试。这可以提前发现依赖缺失、启动流程损坏、运行器配置错误等问题，避免你花精力编写的场景根本无法执行。如果还没有任何测试，请先创建最小启动配置，确认它至少能发现一个场景。
结构化数据默认使用YAML。 当请求体、数据库预置数据、Kafka payload、预期结果使用
```
"""yml
```
文档字符串时，Tzatziki场景的可读性最高。天然适合表格展示的数据可以改用Gherkin表格，仅当契约要求时才使用原始JSON。
完全覆盖用户需求——同时帮用户考虑遗漏的场景。 为用户规范中提到的所有功能行为生成场景，不要只覆盖 happy path。但也不要悄无声息地添加额外场景，你应该在覆盖需求范围后主动识别边缘场景，作为可选补充提交给用户。要高效识别边缘场景，可以关注三个方面：(a) 场景中的每一次外部服务调用——如果它返回错误(4xx、5xx)或者超时会发生什么？(b) 每一个数据集合——如果它为空或者包含非预期值会发生什么？(c) 项目中测试类似功能的已有测试文件——它们通常包含可适配到新场景的错误处理模式。最终由用户决定要包含哪些边缘场景，你的职责是把这些场景暴露出来，避免遗漏重要内容。
复用已有资产。 如果项目已经有运行器、启动类、feature文件存放约定、glue配置，请直接复用。创建重复内容会导致类路径冲突，干扰测试发现。

Workflow

工作流

1. Understand the Specification

1. 理解需求规范

Analyze the user's input and break it into a checklist of distinct functional behaviors. Each behavior will become one or more scenarios. If anything is ambiguous, ask before proceeding.

While analyzing, also extract:

External dependencies — every API, service, or data source the feature interacts with. Each one is a potential source of edge-case scenarios (errors, timeouts, empty responses).
Performance or reliability hints — if the spec mentions performance concerns, large data volumes, or error handling, note them. These signal scenarios the user likely cares about even if they didn't write explicit acceptance tests for them.
Implicit error paths — if the spec says "call service X to get Y", the spec is describing the happy path. The failure path (service X returns an error) is an edge case to suggest.

分析用户输入，将其拆分为不同功能行为的检查清单，每个行为将对应一个或多个场景。如果有任何歧义，请先询问再继续。

分析过程中还需要提取：

外部依赖 —— 该功能交互的所有API、服务或数据源。每个依赖都是潜在的边缘场景来源（错误、超时、空响应）。
性能或可靠性提示 —— 如果规范提到了性能顾虑、大数据量或者错误处理，请记录下来。这些内容意味着用户很可能关心对应的场景，即便他们没有为这些场景编写明确的验收测试。
隐式错误路径 —— 如果规范提到“调用服务X获取Y”，这描述的是happy path，对应的失败路径（服务X返回错误）就是需要建议的边缘场景。

2. Discover the Project

2. 调研项目现状

Detect the build tool (prefer wrappers:

./mvnw

over

mvn

./gradlew

over

gradle

), then:

Always read
references/steps-core.md
— core step definitions (ObjectSteps) are used in every Tzatziki project for variables, assertions, and data manipulation.
Detect which
tzatziki-*
modules the project depends on by inspecting
```
pom.xml
```
or
```
build.gradle
```
for dependency declarations. A quick way to extract them:
bash
```
grep -o 'tzatziki-[a-z-]*' pom.xml | sort -u
```

Read the matching per-module reference(s) based on detected dependencies:

HTTP/REST testing →
```
references/steps-http.md
```
Spring context →
```
references/steps-spring.md
```
JPA/database →
```
references/steps-spring-jpa.md
```
Kafka messaging →
```
references/steps-spring-kafka.md
```
MongoDB →
```
references/steps-spring-mongodb.md
```
OpenSearch →
```
references/steps-opensearch.md
```
Logging assertions →
```
references/steps-logback.md
```
MCP/AI testing →
```
references/steps-mcp.md
```

When in doubt between a step pattern inferred from a
```
.feature
```
example and one read from the Java
```
*Steps.java
```
source, trust the Java source.
Catalog error-handling patterns from existing
```
.feature
```
files you encounter during discovery. Note how the project tests HTTP error responses (e.g., mocking 404/500 from external APIs), empty data, cache misses, or retry behavior. You'll use these patterns as templates when suggesting edge cases in Step 5.

检测构建工具（优先使用包装器：

./mvnw

优先于

mvn

，

./gradlew

优先于

gradle

），然后：

始终阅读
references/steps-core.md
—— 核心步骤定义(ObjectSteps)会在所有Tzatziki项目中使用，用于变量处理、断言、数据操作。
通过检查
pom.xml
或
build.gradle
的依赖声明，检测项目依赖了哪些
tzatziki-*
模块。快速提取依赖的方法：

bash

grep -o 'tzatziki-[a-z-]*' pom.xml | sort -u

根据检测到的依赖阅读对应的分模块参考文档：

HTTP/REST测试 →
```
references/steps-http.md
```
Spring上下文 →
```
references/steps-spring.md
```
JPA/数据库 →
```
references/steps-spring-jpa.md
```
Kafka消息 →
```
references/steps-spring-kafka.md
```
MongoDB →
```
references/steps-spring-mongodb.md
```
OpenSearch →
```
references/steps-opensearch.md
```
日志断言 →
```
references/steps-logback.md
```
MCP/AI测试 →
```
references/steps-mcp.md
```

如果从
```
.feature
```
示例推断的步骤模式和从Java
```
*Steps.java
```
源码中读取的模式有冲突，以Java源码为准。
调研过程中从遇到的已有
.feature
文件中整理错误处理模式。记录项目如何测试HTTP错误响应（比如 mock 外部API返回404/500）、空数据、缓存未命中、重试行为。你在第5步建议边缘场景时会用这些模式作为模板。

3. Check the Bootstrap

3. 检查启动配置

Search for the existing test infrastructure:

Runner:

@Suite

@IncludeEngines("cucumber")

(JUnit 5) or

AbstractTestNGCucumberTests

Feature location:

@SelectClasspathResource(...)

@SelectDirectories(...)

Spring context:

@CucumberContextConfiguration

@SpringBootTest

(if Spring is used)

If any piece is missing, plan to create it. Read

references/bootstrap-templates.md

for the JUnit 5 runner and Spring configuration templates.

查找已有的测试基础设施：

运行器：

@Suite

@IncludeEngines("cucumber")

(JUnit 5) 或者

AbstractTestNGCucumberTests

Feature文件位置：

@SelectClasspathResource(...)

或者

@SelectDirectories(...)

Spring上下文：

@CucumberContextConfiguration

@SpringBootTest

(如果使用Spring)

如果缺少任何组件，请准备创建对应的内容。阅读

references/bootstrap-templates.md

获取JUnit 5运行器和Spring配置模板。

4. Verify the Environment

4. 验证环境

Run the existing test suite in the target module to confirm it works:

bash

undefined

运行目标模块的已有测试套件，确认环境可用：

bash

undefined

Maven

./mvnw -pl <module> -Dtest=<RunnerClass> test

Gradle

./gradlew :<module>:test --tests <RunnerClass>


A passing or functionally-failing run is fine — what matters is that Cucumber discovers and
executes scenarios. `Tests run: 0` means the runner or feature discovery is broken and needs
fixing before you write anything new.

./gradlew :<module>:test --tests <RunnerClass>


运行通过或者功能层面报错都是可以接受的——重点是Cucumber能够发现并执行场景。如果`Tests run: 0`意味着运行器或者feature发现逻辑有问题，需要先修复再编写新内容。

5. Propose the Plan

5. 提交方案申请确认

⛔ This is a mandatory checkpoint. Do not proceed to Step 6 without the user's explicit approval. Even if the user's specification already includes detailed acceptance tests, present the plan anyway — the user expects to review it, may want to adjust scope, and needs the chance to approve or add edge cases they care about. Skipping this step risks generating the wrong tests and wasting effort.

Output the full plan as regular response text first (never embed a long plan inside the

ask_user

question — the UI truncates it). Include:

Files to create or modify
A table mapping each requested functional behavior to a scenario
Any bootstrap work needed
Suggested edge cases (clearly marked as optional) — see below for how to identify them

Then use the

ask_user

tool with a short, focused question asking only for the user's decision (e.g. "Does this plan look good, and which optional edge cases would you like to include?"). Do not write any

.feature

file until the user confirms.

⛔ 这是强制检查点。 没有用户的明确批准不要进入第6步。即使用户的规范已经包含了详细的验收测试，也要先提交方案——用户希望审阅方案，可能想要调整范围，也需要机会批准或添加他们关心的边缘场景。跳过这一步会有生成错误测试、浪费精力的风险。

首先将完整方案作为普通响应文本输出（永远不要把长方案嵌入

ask_user

问题中——UI会截断内容）。方案包含：

要创建或修改的文件
将每个需求功能行为映射到对应场景的表格
所有需要的启动配置工作
建议的边缘场景（明确标记为可选）——参考下文了解如何识别这些场景

然后使用

ask_user

工具发送简短聚焦的问题，仅询问用户的决定（比如“这个方案是否可行，你希望包含哪些可选的边缘场景？”）。在用户确认前不要编写任何

.feature

文件。

Identifying edge cases

识别边缘场景

Use the external dependencies, error patterns, and spec hints you gathered in Steps 1 and 2 to build a concrete list of optional edge-case scenarios. Work through these categories:

External service failures — For each external API call in the scenario consider what happens when it returns:
- A client error (400, 404) — e.g., the resource doesn't exist
- A server error (500, 502, 503) — e.g., the service is down
- An empty or unexpected response body
Empty and boundary data — For each data collection involved:
- What if the collection is empty? (e.g., a super model with no models, a model with no articles, an overridden rule with an empty
```
value
```
  list)
- What if it contains a single element vs. many?
- What if values are null or missing?
State and ordering — Cache hit vs. miss, pre-existing vs. fresh data, concurrent modifications, retry after failure (CREATED → TO_RETRY → ERROR).
Patterns from existing tests — In Step 2 you cataloged error-handling patterns from the project's existing
```
.feature
```
files. Adapt those patterns to the new feature. For example, if existing tests mock a 404 from
```
/masterdata/v2/arbo/models/{id}/articles
```
and assert "0 kafka messages", suggest the same pattern for any new external API the feature calls.

Present each suggested edge case with a one-line description and mark them as (optional). The user decides which to include.

使用你在第1步和第2步收集的外部依赖、错误模式、规范提示来构建具体的可选边缘场景列表。按以下类别梳理：

外部服务故障 —— 针对场景中的每个外部API调用，考虑返回以下内容时的表现：
- 客户端错误(400, 404) —— 比如资源不存在
- 服务端错误(500, 502, 503) —— 比如服务宕机
- 空的或者非预期的响应体
空数据和边界数据 —— 针对涉及的每个数据集合：
- 如果集合为空会怎么样？（比如没有模型的超模型，没有文章的模型，value列表为空的覆盖规则）
- 集合只有一个元素和有多个元素的表现有什么区别？
- 如果值为null或者缺失会怎么样？
状态和顺序 —— 缓存命中vs未命中，已存在vs新数据，并发修改，失败后重试(CREATED → TO_RETRY → ERROR)。
已有测试中的模式 —— 在第2步你整理了项目已有
```
.feature
```
文件中的错误处理模式，将这些模式适配到新功能上。比如如果已有测试mock了
```
/masterdata/v2/arbo/models/{id}/articles
```
返回404，并断言“0条kafka消息”，那么对于该功能调用的任何新外部API都可以建议相同的模式。

每个建议的边缘场景都用单行描述，标记为**(可选)**。由用户决定要包含哪些。

6. Implement and Validate

6. 实现并验证

Write the
```
.feature
```
file using exact step patterns from step 2 and matching the existing project's style (scenario naming,
```
Background
```
usage, tags, data format conventions).

If no feature convention exists, default to

src/test/resources/features

with

@SelectClasspathResource("features")

Run the tests and inspect the output. The test output is the ground truth for step validity — no amount of visual inspection replaces it. Look specifically for these errors:
- ```
"step(s) are undefined"
```
  +
```
"You can implement these steps"
```
  — means the step text doesn't match any registered step definition. This is the most common mistake and it must be fixed before the task is considered done. Go back to the per-module
```
references/steps-*.md
```
  files, find the correct pattern, and rewrite the step.
- ```
UndefinedStepException
```
  — same root cause, different presentation.
- ```
ParseError
```
  — malformed Gherkin syntax.
- ```
Tests run: 0
```
  — runner or feature discovery is broken. Accept functional assertion failures (e.g.
```
expected 200 but got 404
```
  ) — they're expected in BDD when the product behavior isn't implemented yet.
Repeat until every requested behavior from step 1 is present and zero undefined-step errors remain in the test output.

Running a single feature from the CLI: When you need to target one specific feature file or scenario line, use

cucumber.features

as the selector — not

-Dtest=...

cucumber.filter.name

. Read

references/cli-execution.md

for the full details, because

cucumber.features

triggers standalone Cucumber execution that bypasses the runner's

@ConfigurationParameter

annotations.

使用第2步中得到的准确步骤模式编写
```
.feature
```
文件，匹配项目已有风格（场景命名、
```
Background
```
使用、标签、数据格式约定）。
如果没有feature文件存放约定，默认存放在
```
src/test/resources/features
```
，使用
```
@SelectClasspathResource("features")
```
配置。
运行测试并检查输出。 测试输出是步骤有效性的绝对依据——任何人工检查都无法替代。重点关注以下错误：
- ```
"step(s) are undefined"
```
  +
```
"You can implement these steps"
```
  —— 意味着步骤文本和任何已注册的步骤定义都不匹配。这是最常见的错误，必须修复后才算完成任务。回到分模块的
```
references/steps-*.md
```
  文件，找到正确的模式并重写步骤。
- ```
UndefinedStepException
```
  —— 根因和上面相同，只是展示形式不同。
- ```
ParseError
```
  —— Gherkin语法格式错误。
- ```
Tests run: 0
```
  —— 运行器或者feature发现逻辑损坏。功能断言失败是可接受的（比如
```
expected 200 but got 404
```
  ）——在产品功能还未实现时，这是BDD中的预期情况。
重复上述流程，直到第1步中所有需求功能都已覆盖，且测试输出中没有任何未定义步骤的错误。

从CLI运行单个feature： 当你需要指定运行单个feature文件或者某行场景时，使用

cucumber.features

作为选择器——不要用

-Dtest=...

或者

cucumber.filter.name

。阅读

references/cli-execution.md

了解完整细节，因为

cucumber.features

会触发独立的Cucumber执行，绕过运行器的

@ConfigurationParameter

注解。

Success Criteria

成功标准

At least one existing test was run and confirmed operational before new scenarios were written.
The plan was presented to the user and approved before any
.feature
file was written.
Generated scenarios cover 100% of the functional behaviors the user explicitly requested.
All step text comes from real Tzatziki step definitions (no invented steps).
Tests were run and the output contains zero "undefined step" errors. This is the definitive validation — if the test output says
```
"step(s) are undefined"
```
, the task is not done.
Any required runner or Spring bootstrap files are in place.
Tests are discovered and executed with the correct build tool command.
Edge-case scenarios were identified, presented to the user, and included only if approved.
Any remaining failures are functional assertions, not technical setup problems.

编写新场景前，至少运行过一个已有测试并确认环境可用。
编写任何
.feature
文件前，方案已提交给用户并获得批准。
生成的场景100%覆盖用户明确要求的所有功能行为。
所有步骤文本都来自真实的Tzatziki步骤定义（没有编造的步骤）。
已运行测试，输出中没有任何“未定义步骤”错误。 这是最终验证标准——如果测试输出显示
```
"step(s) are undefined"
```
，则任务未完成。
所有需要的运行器或Spring启动配置文件都已就绪。
使用正确的构建工具命令可以发现并执行测试。
边缘场景已被识别、提交给用户，且仅在获得批准的情况下才被包含。
所有剩余的失败都是功能断言失败，而非技术配置问题。

Reference Files

参考文件

Read these when needed — they contain templates and detailed guidance that would clutter the main workflow:

需要时阅读这些文件——它们包含了会让主工作流过于臃肿的模板和详细指导：

Per-Module Step References (read based on detected dependencies)

分模块步骤参考（根据检测到的依赖阅读）

references/steps-core.md
— ObjectSteps: variables, assertions, data manipulation, type conversions. Always read this — core steps are used in every Tzatziki project.
references/steps-http.md
— HttpSteps: HTTP mocking, request/response assertions, REST API testing. Read when the project uses
```
tzatziki-http
```
.
references/steps-spring.md
— SpringSteps: Spring context, properties, bean manipulation. Read when the project uses
```
tzatziki-spring
```
.
references/steps-spring-jpa.md
— SpringJPASteps: JPA entity management, database fixtures, persistence assertions. Read when the project uses
```
tzatziki-spring-jpa
```
.
references/steps-spring-kafka.md
— KafkaSteps: Kafka topic management, message producing/consuming, async assertions. Read when the project uses
```
tzatziki-spring-kafka
```
.
references/steps-spring-mongodb.md
— SpringMongoSteps: MongoDB collection management, document fixtures, query asse/rtions. Read when the project uses
```
tzatziki-spring-mongodb
```
.
references/steps-opensearch.md
— OpenSearchSteps: index management, document indexing, search assertions. Read when the project uses
```
tzatziki-opensearch
```
.
references/steps-logback.md
— LoggerSteps: log assertion, log level management. Read when the project uses
```
tzatziki-logback
```
.
references/steps-mcp.md
— McpSteps: MCP server testing, tool invocation, AI integration. Read when the project uses
```
tzatziki-test-mcp
```
.

references/steps-core.md
—— ObjectSteps：变量、断言、数据操作、类型转换。必须阅读 —— 所有Tzatziki项目都会用到核心步骤。
references/steps-http.md
—— HttpSteps：HTTP mock、请求/响应断言、REST API测试。项目使用
```
tzatziki-http
```
时阅读。
references/steps-spring.md
—— SpringSteps：Spring上下文、属性、Bean操作。项目使用
```
tzatziki-spring
```
时阅读。
references/steps-spring-jpa.md
—— SpringJPASteps：JPA实体管理、数据库预置数据、持久化断言。项目使用
```
tzatziki-spring-jpa
```
时阅读。
references/steps-spring-kafka.md
—— KafkaSteps：Kafka主题管理、消息生产/消费、异步断言。项目使用
```
tzatziki-spring-kafka
```
时阅读。
references/steps-spring-mongodb.md
—— SpringMongoSteps：MongoDB集合管理、文档预置数据、查询断言。项目使用
```
tzatziki-spring-mongodb
```
时阅读。
references/steps-opensearch.md
—— OpenSearchSteps：索引管理、文档索引、搜索断言。项目使用
```
tzatziki-opensearch
```
时阅读。
references/steps-logback.md
—— LoggerSteps：日志断言、日志级别管理。项目使用
```
tzatziki-logback
```
时阅读。
references/steps-mcp.md
—— McpSteps：MCP服务测试、工具调用、AI集成。项目使用
```
tzatziki-test-mcp
```
时阅读。

Other References

其他参考

references/bootstrap-templates.md
— JUnit 5 runner and Spring
```
@CucumberContextConfiguration
```
templates. Read when you need to create a new runner or Spring bootstrap class.
references/cli-execution.md
— How to run a single feature or scenario from the CLI using
```
cucumber.features
```
, including the Maven/Gradle property-mirroring mechanism. Read when you need to target a specific
```
.feature
```
file instead of running the full suite.

references/bootstrap-templates.md
—— JUnit 5运行器和Spring
```
@CucumberContextConfiguration
```
模板。需要创建新运行器或Spring启动类时阅读。
references/cli-execution.md
—— 如何使用
```
cucumber.features
```
从CLI运行单个feature或场景，包括Maven/Gradle属性镜像机制。需要指定运行单个
```
.feature
```
文件而非运行完整测试套件时阅读。