sdd4j-ears-tests

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: SDD4J EARS Tests

技能：SDD4J EARS Tests

Objective

目标

Turn SDD4J EARS requirement statements into traceable parameterized Java tests. The leverage is structural: every EARS pattern is a (condition → response) tuple, and an SDD4J requirement group already collects statements that share one boundary operation — same arrange/act skeleton, only the data differs. That is the textbook precondition for parameterization, so the mapping is mechanical. This skill owns only the EARS-to-test transform and the requirement trace. The architecture adapter owns where capability code and tests belong. The stack skill owns concrete test syntax, runner, fixtures, and verification.

将SDD4J EARS需求语句转换为可追溯的Java参数化测试。其核心优势在于结构性：每个EARS模式都是一个（条件→响应）元组，而SDD4J需求组已经归集了共享同一边界操作的语句——它们拥有相同的「安排-执行」骨架，仅输入数据不同。这是参数化测试的典型前提，因此二者的映射是机械性的。本技能仅负责EARS到测试的转换以及需求追溯逻辑。架构适配器负责定义能力代码和测试的归属位置。栈技能负责具体的测试语法、测试运行器、测试夹具和验证逻辑。

Input Contract

输入约定

Consume a SDD4J capability spec, usually from

package-info.java

, with this shape:

undefined

接收SDD4J能力规范作为输入，通常来自

package-info.java

，格式如下：

undefined

Boundary

```
place-order
```
- Places an order for a valid cart.

```
place-order
```
- Places an order for a valid cart.

Requirements

R1 Place order

R1.1 - When a cart with at least one item is submitted, the capability shall create and confirm an order.
R1.2 - If the cart is empty, then the capability shall reject the request.


Do not edit the spec and do not coin requirement ids. Missing, duplicate, or malformed ids are spec issues to report back to SDD4J.

R1.1 - When a cart with at least one item is submitted, the capability shall create and confirm an order.
R1.2 - If the cart is empty, then the capability shall reject the request.


请勿编辑规范，也不要自行创建需求ID。缺失、重复或格式错误的ID属于规范问题，应反馈给SDD4J。

Core Mapping

核心映射规则

One requirement group
Rn
maps to one parameterized, table-driven, or grouped test skeleton when the group has multiple statements.
One statement
Rn.m
→ one row in the parameter source.
The statement id
Rn.m
resolves to the row's runner-visible display name, so the spec↔test binding stays per-statement.
The trace may be a literal id or a symbol such as
```
R1_2
```
whose display form is the exact
```
R1.2
```
id.
An id that appears only in JavaDoc or a comment is not a trace.
The EARS pattern fixes the row's role and shape — you do not invent the columns, you read them off the pattern.

The shared test body should exercise the boundary operation or application operation associated with the requirement group, as defined by SDD4J and the architecture adapter.

当一个需求组
Rn
包含多条语句时，映射为一个参数化、表驱动或分组的测试骨架。
一条语句
Rn.m
对应参数源中的一行。
语句ID
Rn.m
将作为测试运行器可见的行显示名称，从而保证规范与测试的绑定粒度精确到每条语句。
追溯标识可以是字面ID，也可以是类似
```
R1_2
```
的符号，其显示形式为精确的
```
R1.2
```
ID。
仅出现在JavaDoc或注释中的ID不属于有效追溯。
EARS模式决定了测试行的角色和结构——你无需自行设计列，只需从模式中提取即可。

共享的测试主体应执行需求组对应的边界操作或应用操作，具体由SDD4J和架构适配器定义。

EARS Pattern To Case Shape

EARS模式到用例结构的映射

Each EARS statement decomposes into arrange, act, assert, and role fields. Do not invent concrete values from prose; use clear TODO/failing stubs when values or assertions are not derivable from existing code or user input.

Pattern	Statement shape	Arrange	Act	Assert	Role
Event-driven	`When <trigger>, the capability shall <response>`	default state	trigger	response	happy
Unwanted behavior	`If <trigger>, then the capability shall <response>`	default state	invalid trigger	rejection/error	unhappy
State-driven	`While <precondition>, the capability shall <response>`	precondition	implicit	response	stateful
Complex	`While <precondition>, when <trigger>, the capability shall <response>`	precondition	trigger	response	full tuple
Optional-feature	`Where <feature is included>, the capability shall <response>`	feature enabled	trigger or implicit	response	gated
Ubiquitous	`The capability shall <response>`	default or global state	implicit	invariant	invariant

Mixing happy and unhappy rows in one group is normal when they share the same operation skeleton.

每条EARS语句都可分解为安排、执行、断言和角色字段。请勿从散文式描述中臆造具体值；当值或断言无法从现有代码或用户输入中推导时，使用清晰的TODO/失败占位符。

模式	语句结构	安排	执行	断言	角色
事件驱动	`当 <触发条件> 时，能力应 <响应动作>`	默认状态	触发操作	响应结果	正常路径
非预期行为	`如果 <触发条件>，则能力应 <响应动作>`	默认状态	非法触发	拒绝/错误	异常路径
状态驱动	`当 <前置条件> 成立时，能力应 <响应动作>`	前置条件	隐式执行	响应结果	有状态
复合模式	`当 <前置条件> 成立时，若 <触发条件> 发生，能力应 <响应动作>`	前置条件	触发操作	响应结果	完整元组
可选特性	`在 <启用某特性> 的情况下，能力应 <响应动作>`	特性已启用	触发或隐式执行	响应结果	门控
普适性	`能力应 <响应动作>`	默认或全局状态	隐式执行	不变量	不变量

当正常路径和异常路径的测试共享同一操作骨架时，将它们放在同一个组中是常见做法。

Deterministic vs Authored

确定性生成 vs 人工编写

Generate without judgment:

Group-to-test skeleton.
Statement-to-row mapping.
Requirement id labels.
EARS role classification.
Bidirectional trace coverage checks between spec ids and test ids.
The shared operation target when SDD4J and the architecture adapter already identify it.

Leave authored or explicit TODOs for:

Concrete fixture values.
Domain object construction when not already obvious.
Exact assertion expression for prose responses.
Error type, status code, or message when the spec does not define it.

Prefer a failing TODO, disabled placeholder with a visible reason, or stack-idiomatic red test over a fabricated green assertion.

以下内容可无判断自动生成：

需求组到测试骨架的映射。
需求语句到测试行的映射。
需求ID标签。
EARS角色分类。
规范ID与测试ID之间的双向追溯覆盖率检查。
当SDD4J和架构适配器已明确操作目标时，共享的操作目标。

以下内容需人工编写或显式标注TODO：

具体的测试夹具值。
尚不明确的领域对象构造逻辑。
散文式响应对应的精确断言表达式。
规范未定义的错误类型、状态码或错误消息。

优先使用失败的TODO、带可见原因的禁用占位符，或符合技术栈惯例的红色测试，而非编造的绿色断言。

Composition

组合协作

SDD4J owns the spec, stable ids, gap workflow, and drift policy.
The architecture adapter owns whether the operation is a controller method, application service method, BCE boundary method, listener, command, or another entrypoint.
The stack skill owns test syntax and the verification command.
This skill consumes
```
## Requirements
```
and emits or updates tests with exact runner-visible ids, represented by literals or resolvable symbols.

During

/sdd4j apply

, use this skill when an

Rn.m

statement lacks a test trace or when a requirement group should be represented as table-driven tests.

SDD4J负责规范、稳定ID、缺口处理工作流和漂移策略。
架构适配器负责定义操作的类型：控制器方法、应用服务方法、BCE边界方法、监听器、命令或其他入口点。
栈技能负责测试语法和验证命令。
本技能消费
```
## Requirements
```
章节，生成或更新带有测试运行器可见的精确ID的测试，ID以字面量或可解析符号的形式表示。

在执行

/sdd4j apply

时，若某条

Rn.m

语句缺少测试追溯，或某个需求组应实现为表驱动测试，则使用本技能。

Realization Rules

实现规则

Read

references/realizations.md

when concrete examples are useful. Use the project's existing test idiom; never introduce a second framework or style just because an example uses it.

The parameter-source mechanism and display-name form belong to the composed stack skill — read

references/realizations.md

for the per-stack shape (JUnit 5

@ParameterizedTest

@MethodSource

). Java stacks materialize the

Rn.m

ids as a generated per-BC

{BC name in CamelCase}Requirement

annotation with a nested

Rn

enum — the label contract is unchanged because the enum's display form is the literal id; web stacks and the black-box

-st

module keep literal strings. Pick the one the project already uses; never introduce a second test idiom.

当需要具体示例时，请阅读

references/realizations.md

。使用项目现有的测试风格；切勿因为示例使用了某种框架或风格就引入第二套。

参数源机制和显示名称形式由组合的栈技能决定——请查阅

references/realizations.md

了解各技术栈的实现形式（JUnit 5的

@ParameterizedTest

@MethodSource

）。Java技术栈将

Rn.m

ID具体化为每个BC生成的

{驼峰命名的BC名称}Requirement

注解，其中包含嵌套的

Rn

枚举——标签契约保持不变，因为枚举的显示形式就是字面ID；Web技术栈和黑盒

-st

模块使用字面字符串。选择项目已采用的方式；切勿引入第二套测试风格。

Trace Coverage Check

追溯覆盖率检查

Before and after editing tests, check:

Every
```
Rn.m
```
in the spec resolves to at least one runner-visible test trace.
Every literal or symbolic test trace resolves to an existing statement in the corresponding capability spec.
For symbolic traces such as
```
R1_2
```
, resolve the symbol's configured display form before comparing it with the spec id.
One statement can have multiple tests only when each test covers a distinct level or scenario and the duplication is intentional.
A test must not claim an id from another capability unless the project explicitly has cross-capability system tests.

Report orphan test ids as drift. Do not edit the spec to absorb orphan ids.

在编辑测试前后，需检查以下内容：

规范中的每个
```
Rn.m
```
都至少对应一个测试运行器可见的测试追溯。
每个字面或符号形式的测试追溯都能对应到相应能力规范中的现有语句。
对于类似
```
R1_2
```
的符号追溯，在与规范ID比较前，需先解析符号的配置显示形式。
仅当每个测试覆盖不同的层级或场景，且这种重复是有意为之的情况下，一条语句才可以对应多个测试。
除非项目明确存在跨能力的系统测试，否则测试不得声明来自其他能力的ID。

将孤立的测试ID报告为漂移。请勿通过编辑规范来吸收孤立ID。