e2e-cucumber-playwright

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dify E2E Cucumber + Playwright

Use this skill for Dify's repository-level E2E suite in

e2e/

. Use

e2e/AGENTS.md

as the canonical guide for local architecture and conventions, then apply Playwright/Cucumber best practices only where they fit the current suite.

本技能适用于Dify仓库

e2e/

目录下的仓库级端到端测试套件。请将

e2e/AGENTS.md

作为本地架构和约定的权威指南，仅在符合当前套件的情况下应用Playwright/Cucumber最佳实践。

Scope

适用范围

Use this skill for
```
.feature
```
files, Cucumber step definitions,
```
DifyWorld
```
, hooks, tags, and E2E review work under
```
e2e/
```
.
Do not use this skill for Vitest or React Testing Library work under
```
web/
```
; use
```
frontend-testing
```
instead.
Do not use this skill for backend test or API review tasks under
```
api/
```
.

本技能适用于
```
e2e/
```
目录下的
```
.feature
```
文件、Cucumber步骤定义、
```
DifyWorld
```
、钩子、标签以及端到端测试评审工作。
请勿将本技能用于
```
web/
```
目录下的Vitest或React Testing Library相关工作；请改用
```
frontend-testing
```
技能。
请勿将本技能用于
```
api/
```
目录下的后端测试或API评审任务。

Read Order

阅读顺序

Read
```
e2e/AGENTS.md
```
first.
Read only the files directly involved in the task:
- target
```
.feature
```
  files under
```
e2e/features/
```
- related step files under
```
e2e/features/step-definitions/
```
- ```
e2e/features/support/hooks.ts
```
  and
```
e2e/features/support/world.ts
```
  when session lifecycle or shared state matters
- ```
e2e/scripts/run-cucumber.ts
```
  and
```
e2e/cucumber.config.ts
```
  when tags or execution flow matter
Read
```
references/playwright-best-practices.md
```
only when locator, assertion, isolation, or waiting choices are involved.
Read
```
references/cucumber-best-practices.md
```
only when scenario wording, step granularity, tags, or expression design are involved.
Re-check official docs with Context7 before introducing a new Playwright or Cucumber pattern.

首先阅读
```
e2e/AGENTS.md
```
。
仅阅读与任务直接相关的文件：
- ```
e2e/features/
```
  目录下的目标
```
.feature
```
  文件
- ```
e2e/features/step-definitions/
```
  目录下的相关步骤文件
- 当涉及会话生命周期或共享状态时，阅读
```
e2e/features/support/hooks.ts
```
  和
```
e2e/features/support/world.ts
```
- 当涉及标签或执行流程时，阅读
```
e2e/scripts/run-cucumber.ts
```
  和
```
e2e/cucumber.config.ts
```
仅在涉及定位器、断言、隔离或等待选择时，阅读
```
references/playwright-best-practices.md
```
。
仅在涉及场景措辞、步骤粒度、标签或表达式设计时，阅读
```
references/cucumber-best-practices.md
```
。
在引入新的Playwright或Cucumber模式之前，请先通过Context7查阅官方文档。

Local Rules

本地规则

```
e2e/
```
uses Cucumber for scenarios and Playwright as the browser layer.
```
DifyWorld
```
is the per-scenario context object. Type
```
this
```
as
```
DifyWorld
```
and use
```
async function
```
, not arrow functions.
Keep glue organized by capability under
```
e2e/features/step-definitions/
```
; use
```
common/
```
only for broadly reusable steps.
Browser session behavior comes from
```
features/support/hooks.ts
```
:
- default: authenticated session with shared storage state
- ```
@unauthenticated
```
  : clean browser context
- ```
@authenticated
```
  : readability/selective-run tag only unless implementation changes
- ```
@fresh
```
  : only for
```
e2e:full*
```
  flows
Do not import Playwright Test runner patterns that bypass the current Cucumber +
```
DifyWorld
```
architecture unless the task is explicitly about changing that architecture.

```
e2e/
```
目录使用Cucumber定义场景，Playwright作为浏览器层。
```
DifyWorld
```
是每个场景的上下文对象。请将
```
this
```
类型声明为
```
DifyWorld
```
，并使用
```
async function
```
而非箭头函数。
将胶水代码（glue）按功能分类组织在
```
e2e/features/step-definitions/
```
目录下；仅将广泛可复用的步骤放在
```
common/
```
目录中。
浏览器会话行为来自
```
features/support/hooks.ts
```
：
- 默认：带有共享存储状态的已认证会话
- ```
@unauthenticated
```
  ：干净的浏览器上下文
- ```
@authenticated
```
  ：仅作为可读性/选择性运行标签，除非实现有变更
- ```
@fresh
```
  ：仅用于
```
e2e:full*
```
  流程
除非任务明确要求更改架构，否则请勿导入绕过当前Cucumber +
```
DifyWorld
```
架构的Playwright Test运行器模式。

Workflow

工作流程

Rebuild local context.
- Inspect the target feature area.
- Reuse an existing step when wording and behavior already match.
- Add a new step only for a genuinely new user action or assertion.
- Keep edits close to the current capability folder unless the step is broadly reusable.
Write behavior-first scenarios.
- Describe user-observable behavior, not DOM mechanics.
- Keep each scenario focused on one workflow or outcome.
- Keep scenarios independent and re-runnable.
Write step definitions in the local style.
- Keep one step to one user-visible action or one assertion.
- Prefer Cucumber Expressions such as
```
{string}
```
  and
```
{int}
```
  .
- Scope locators to stable containers when the page has repeated elements.
- Avoid page-object layers or extra helper abstractions unless repeated complexity clearly justifies them.
Use Playwright in the local style.
- Prefer user-facing locators:
```
getByRole
```
  ,
```
getByLabel
```
  ,
```
getByPlaceholder
```
  ,
```
getByText
```
  , then
```
getByTestId
```
  for explicit contracts.
- Use web-first
```
expect(...)
```
  assertions.
- Do not use
```
waitForTimeout
```
  , manual polling, or raw visibility checks when a locator action or retrying assertion already expresses the behavior.
Validate narrowly.
- Run the narrowest tagged scenario or flow that exercises the change.
- Run
```
pnpm -C e2e check
```
  .
- Broaden verification only when the change affects hooks, tags, setup, or shared step semantics.

重建本地上下文。
- 检查目标功能区域。
- 当措辞和行为已匹配时，复用现有步骤。
- 仅当存在真正全新的用户操作或断言时，才添加新步骤。
- 除非步骤具有广泛复用性，否则请将编辑内容放在当前功能文件夹附近。
编写以行为为核心的场景。
- 描述用户可观察的行为，而非DOM机制。
- 每个场景聚焦于一个工作流或结果。
- 保持场景独立且可重复运行。
按照本地风格编写步骤定义。
- 每个步骤对应一个用户可见的操作或一个断言。
- 优先使用Cucumber表达式，如
```
{string}
```
  和
```
{int}
```
  。
- 当页面包含重复元素时，将定位器限定在稳定容器内。
- 除非重复的复杂性明确需要，否则避免使用页面对象层或额外的辅助抽象。
按照本地风格使用Playwright。
- 优先使用面向用户的定位器：
```
getByRole
```
  、
```
getByLabel
```
  、
```
getByPlaceholder
```
  、
```
getByText
```
  ，然后使用
```
getByTestId
```
  用于显式约定。
- 使用web-first的
```
expect(...)
```
  断言。
- 当定位器操作或重试断言已能表达行为时，请勿使用
```
waitForTimeout
```
  、手动轮询或原始可见性检查。
窄范围验证。
- 运行能验证变更的最窄范围的带标签场景或流程。
- 运行
```
pnpm -C e2e check
```
  命令。
- 仅当变更影响钩子、标签、设置或共享步骤语义时，才扩大验证范围。

Review Checklist

评审检查清单

Does the scenario describe behavior rather than implementation?
Does it fit the current session model, tags, and
```
DifyWorld
```
usage?
Should an existing step be reused instead of adding a new one?
Are locators user-facing and assertions web-first?
Does the change introduce hidden coupling across scenarios, tags, or instance state?
Does it document or implement behavior that differs from the real hooks or configuration?

Lead findings with correctness, flake risk, and architecture drift.

场景是否描述行为而非实现细节？
它是否符合当前的会话模型、标签和
```
DifyWorld
```
使用方式？
是否应该复用现有步骤而非添加新步骤？
定位器是否面向用户，断言是否为web-first？
变更是否引入了场景、标签或实例状态之间的隐藏耦合？
它是否记录或实现了与实际钩子或配置不同的行为？

评审发现应优先关注正确性、不稳定风险（flake risk）和架构偏移。

References

参考资料

```
references/playwright-best-practices.md
```
```
references/cucumber-best-practices.md
```

```
references/playwright-best-practices.md
```
```
references/cucumber-best-practices.md
```