playwright-bdd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright BDD

Phase 0: BDD Necessity Check

Phase 0: BDD必要性检查

For every user-requested task, first decide whether the requested outcome needs to be specified in new or updated BDD scenarios. Base this decision on changes to observable product behavior, not on the size of the code change or the number of files involved.

BDD feature-file changes are needed when the task:

Adds, removes, or changes user-observable behavior or an end-to-end user outcome.
Changes a user flow, acceptance criterion, validation rule, permission, or user-visible error behavior.
Fixes a bug whose expected behavior is missing from, or inaccurately described by, the existing scenarios.

BDD feature-file changes are not needed when the task:

Refactors or reorganizes implementation while preserving existing observable behavior.
Changes documentation, comments, formatting, tooling, or other development infrastructure without changing product behavior.
Implements or fixes behavior that is already accurately specified by existing scenarios and does not require their wording or coverage to change.
Changes only step definitions or test infrastructure while leaving the specified product behavior unchanged.

After making this assessment:

If BDD feature-file changes are not needed, continue with the user's task immediately without creating or modifying any
```
.feature
```
files and without stopping for confirmation.
If BDD feature-file changes are needed, or the assessment is genuinely unclear, ask only: "Is BDD scenarios update needed for this change?" Then wait for the user's answer. Do not explain why the question is being asked or provide any details, reasoning, or recommendation with it.
If the user answers yes, continue to Phase 1. If the user answers no, continue with the user's task without changing
```
.feature
```
files.

对于每个用户提出的任务，首先判断所需的结果是否需要通过新增或更新BDD场景来明确。此判断基于产品可观测行为的变化，而非代码变更的规模或涉及文件的数量。

BDD特性文件需要变更的情况：

添加、移除或更改用户可观测的行为，或者端到端的用户结果。
更改用户流程、验收标准、验证规则、权限或用户可见的错误行为。
修复现有场景未描述或描述不准确的预期行为相关的bug。

BDD特性文件无需变更的情况：

在保留现有可观测行为的前提下进行重构或代码重组。
修改文档、注释、格式、工具或其他开发基础设施，但未改变产品行为。
实现或修复的行为已被现有场景准确描述，无需修改场景的表述或覆盖范围。
仅修改步骤定义或测试基础设施，未改变已明确的产品行为。

完成评估后：

如果无需修改BDD特性文件，立即继续执行用户的任务，无需创建或修改任何
```
.feature
```
文件，也无需等待确认。
如果需要修改BDD特性文件，或者评估结果不明确，仅需询问："此变更是否需要更新BDD场景？" 然后等待用户回复。无需解释提问原因，也无需提供任何细节、理由或建议。
如果用户回答"是"，进入第一阶段。如果用户回答"否"，继续执行用户的任务，不修改
```
.feature
```
文件。

Phase 1: Planning

Phase 1: 规划

Discover project configuration — Search
```
playwright.config.ts
```
(or
```
playwright.config.js
```
) for
```
defineBddConfig(...)
```
calls. This reveals the features directory and the
```
steps
```
glob patterns pointing to step definition files.
- If multiple
```
defineBddConfig
```
  calls exist, pick the most suitable one based on context (e.g. match directory names to the described feature area). Only ask the user to clarify if it is genuinely ambiguous.
Write BDD scenarios — Check the existing feature files and create or update BDD scenarios according to the input. Strictly follow the "Scenario Writing Rules" section.
Show feature-file changes to the user and use the question tool with the question "Approve the proposed feature-file changes?" — Show the exact new or changed Gherkin content to the user for negotiation:
- When presenting changes to existing scenarios, use unified diff format (```diff) to clearly show additions and removals. For entirely new scenarios, show them in plain Gherkin format.
- Always show the target feature file path, so it's clear where the scenario will be added or modified.
- In the question tool use a concise approval question: "Approve the proposed feature-file changes?", don't show the full diff in the question itself.
- If the user asks for a plan, do not finalize the plan until these feature-file changes have been shown and explicitly approved.
- Do not substitute a summary, checklist, or implementation plan for the feature-file diff/Gherkin. The user must see the proposed
```
.feature
```
  file update itself.
- If the user requests changes, revise the proposed scenario text and re-present it.
- Iterate until the user explicitly approves the scenarios. Do not proceed to implementation planning or implementation until the user confirms the scenarios are correct.
Only after scenario approval, plan implementation — Once the user approves the Gherkin, produce or execute the implementation plan as requested. The plan should reference the approved scenarios as the source of truth.

探索项目配置 — 搜索
```
playwright.config.ts
```
（或
```
playwright.config.js
```
）中的
```
defineBddConfig(...)
```
调用。这会显示特性文件目录和指向步骤定义文件的
```
steps
```
通配符模式。
- 如果存在多个
```
defineBddConfig
```
  调用，根据上下文选择最合适的一个（例如，将目录名称与所描述的功能区域匹配）。只有在确实存在歧义时，才请求用户澄清。
编写BDD场景 — 检查现有特性文件，根据输入创建或更新BDD场景。严格遵循"场景编写规则"部分的要求。
向用户展示特性文件的变更，并使用提问工具询问"是否批准所提议的特性文件变更？" — 向用户展示确切的新增或修改后的Gherkin内容，以便协商：
- 当展示对现有场景的变更时，使用统一差异格式（```diff）清晰显示新增和删除的内容。对于全新的场景，使用纯Gherkin格式展示。
- 始终显示目标特性文件的路径，明确场景将被添加或修改的位置。
- 在提问工具中使用简洁的批准问题："是否批准所提议的特性文件变更？"，不要在问题中显示完整差异。
- 如果用户要求提供计划，在展示并获得这些特性文件变更的明确批准之前，不要确定最终计划。
- 不要用摘要、清单或实现计划来替代特性文件的差异/Gherkin内容。用户必须看到提议的
```
.feature
```
  文件更新内容本身。
- 如果用户要求修改，调整提议的场景文本并重新展示。
- 反复迭代，直到用户明确批准场景。在用户确认场景正确之前，不要进行实现规划或实施。
仅在场景批准后，进行实现规划 — 一旦用户批准Gherkin内容，按照要求生成或执行实现计划。计划应以已批准的场景为事实依据。

Phase 2: Implementation

Phase 2: 实现

Implement the feature — Write the actual feature implementation code, follow project guidelines, not this skill.
Implement step definitions — Write or update step definitions for the steps used in the scenarios. Follow the existing steps writing patterns. Suggest the most appropriate file to add new steps to, inferred from existing file naming.

实现功能 — 编写实际的功能实现代码，遵循项目指南，而非本技能的要求。
实现步骤定义 — 为场景中使用的步骤编写或更新步骤定义。遵循现有的步骤编写模式。根据现有文件命名推断最合适的文件来添加新步骤。

Phase 3: Verification

Phase 3: 验证

Execute

npx bddgen && npx playwright test

to generate test files from features and run them with Playwright.

Run only the relevant subset of tests by passing the paths of generated spec files to the Playwright CLI. The generated directory is defined by

defineBddConfig()

playwright.config.ts

(the

testDir

value).

Example:

shell

npx bddgen && npx playwright test .features-gen/@homepage/homepage.feature.spec.js

执行

npx bddgen && npx playwright test

，从特性文件生成测试文件并使用Playwright运行它们。

通过将生成的规范文件路径传递给Playwright CLI，仅运行相关的测试子集。生成目录由

playwright.config.ts

中的

defineBddConfig()

定义（即

testDir

的值）。

示例：

shell

npx bddgen && npx playwright test .features-gen/@homepage/homepage.feature.spec.js

Scenario Writing Rules

场景编写规则

Scenarios must cover complete end-to-end user flows with a meaningful outcome. A scenario should describe a user-facing behavior or outcome, not checking intermediate states.
Keep the number of scenarios minimal. Use the fewest scenarios needed to cover the main user flows for the feature.
Reuse existing steps when composing scenarios. Discover existing step definitions and feature files for steps that can be reused in new scenarios before inventing new phrasing. Use
```
npx bddgen export
```
or file search tool to list all registered step definitions.

Prefer business-aware step names over technical, heavily parameterized ones. Bad:

When('I click {string} on {string}', ...)

Good:

When('I click the "Add" button in the product list', ...)

For multiple similar actions, prefer single step with a data table instead of multiple steps. When a scenario involves providing several values of the same kind (e.g. filling form fields, adding list items), consolidate them into one step with a DataTable rather than repeating a step for each value. Bad:
gherkin
```
When I fill "Name" with "Alice"
And I fill "Email" with "alice@example.com"
And I fill "Role" with "Admin"
```
Good:
gherkin
```
When I fill the form with:
  | Name  | Alice             |
  | Email | alice@example.com |
  | Role  | Admin             |
```
Add a short description to every feature. Immediately below each
```
Feature:
```
line, add an indented one- or two-sentence description of the feature's main user-facing purpose. Use simple, concrete statements and the project's existing domain terms. Describe the feature as a whole; do not list scenarios, edge cases, or implementation details. Leave a blank line before and after the description.
Append new scenarios. When adding a scenario to an existing feature file, place it after all existing scenarios. Do not insert it at the beginning or between existing scenarios unless the user explicitly requests a specific location.

场景必须涵盖完整的端到端用户流程和有意义的结果。 场景应描述用户面向的行为或结果，而非检查中间状态。
尽量减少场景数量。 使用最少的场景来覆盖该功能的主要用户流程。
编写场景时重用现有步骤。 在发明新表述之前，先查找可在新场景中重用的现有步骤定义和特性文件。使用
```
npx bddgen export
```
或文件搜索工具列出所有已注册的步骤定义。
优先使用业务相关的步骤名称，而非技术性、参数化程度高的名称。 不良示例：
```
When('I click {string} on {string}', ...)
```
良好示例：
```
When('I click the "Add" button in the product list', ...)
```
对于多个类似操作，优先使用带有数据表的单个步骤，而非多个步骤。 当场景涉及提供多个同类值时（例如填写表单字段、添加列表项），将它们合并到一个带有DataTable的步骤中，而非为每个值重复一个步骤。不良示例：
gherkin
```
When I fill "Name" with "Alice"
And I fill "Email" with "alice@example.com"
And I fill "Role" with "Admin"
```
良好示例：
gherkin
```
When I fill the form with:
  | Name  | Alice             |
  | Email | alice@example.com |
  | Role  | Admin             |
```
为每个特性添加简短描述。 在每个
```
Feature:
```
行下方，添加一个缩进的一到两句话的描述，说明该特性的主要用户面向用途。使用简单、具体的表述和项目现有的领域术语。描述整个特性；不要列出场景、边缘情况或实现细节。在描述前后各留一个空行。
追加新场景。 当向现有特性文件添加场景时，将其放在所有现有场景之后。除非用户明确要求特定位置，否则不要将其插入开头或现有场景之间。

Scoped Step Definitions

作用域步骤定义

Prefer

-prefixed directories to scope step definitions to specific feature domains. This avoids conflicts when common step names (e.g.

I should see {string} text

) need different implementations depending on context. More details on scoped steps: https://vitalets.github.io/playwright-bdd/#/writing-steps/scoped?id=tags-from-path

Example structure with scoped steps

features/
├── fixtures.ts
├── @homepage/
│   ├── homepage.feature
│   └── steps.ts
├── @profile/
│   ├── profile.feature
│   └── steps.ts
└── shared-steps.ts

Steps defined inside

features/@homepage/steps.ts

are automatically scoped to features in the same directory — no explicit

{ tags: '@homepage' }

needed.

优先使用

开头的目录，将步骤定义限定在特定的功能领域内。这样可以避免当通用步骤名称（例如

I should see {string} text

）需要根据上下文进行不同实现时产生冲突。有关作用域步骤的更多详细信息：https://vitalets.github.io/playwright-bdd/#/writing-steps/scoped?id=tags-from-path

带作用域步骤的示例结构

features/
├── fixtures.ts
├── @homepage/
│   ├── homepage.feature
│   └── steps.ts
├── @profile/
│   ├── profile.feature
│   └── steps.ts
└── shared-steps.ts

在

features/@homepage/steps.ts

中定义的步骤会自动限定在同一目录下的特性中 — 无需显式添加

{ tags: '@homepage' }

。

Example Feature File

示例特性文件

gherkin

Feature: Shopping cart
  Customers can collect products they intend to buy and review the current cart contents.

  Scenario: Add item to cart
    Given I am on a product page
    And the cart is empty
    When I add the product "banana" to the cart
    Then the cart contains "banana"
    And the cart badge shows 1

gherkin

Feature: Shopping cart
  Customers can collect products they intend to buy and review the current cart contents.

  Scenario: Add item to cart
    Given I am on a product page
    And the cart is empty
    When I add the product "banana" to the cart
    Then the cart contains "banana"
    And the cart badge shows 1

Example Step Definitions

示例步骤定义

typescript

import { Given, When, Then } from './fixtures';

Given('I am on a product page', async ({ page }) => {
  await page.goto('/product');
});

When('I add the product {string} to the cart', async ({ page }, name: string) => {
  await page.getByRole('button', { name: `Add ${name}` }).click();
});

Then('the cart badge should show {int}', async ({ page }, count: number) => {
  await expect(page.locator('.cart-badge')).toHaveText(String(count));
});

typescript

import { Given, When, Then } from './fixtures';

Given('I am on a product page', async ({ page }) => {
  await page.goto('/product');
});

When('I add the product {string} to the cart', async ({ page }, name: string) => {
  await page.getByRole('button', { name: `Add ${name}` }).click();
});

Then('the cart badge should show {int}', async ({ page }, count: number) => {
  await expect(page.locator('.cart-badge')).toHaveText(String(count));
});