playwright-bdd-configuration

用途

Playwright BDD 让开发者能够使用 Gherkin 语法编写 BDD 测试，并通过 Playwright Test 运行。本技能聚焦于该工具的配置、项目搭建以及与 Playwright 测试框架的集成。配置通过 playwright.config.ts 文件中的 defineBddConfig() 函数完成，该函数会从 .feature 文件生成 Playwright 测试文件。

安装

使用 npm 安装 playwright-bdd：

npm install -D playwright-bdd

或指定 Playwright 版本：

npm install -D playwright-bdd @playwright/test

主要能力

基础配置

最小化配置示例：

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { defineBddConfig } from 'playwright-bdd';

const testDir = defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
});

export default defineConfig({
  testDir,
});

defineBddConfig() 返回生成测试目录的路径，默认位于项目根目录的 .features-gen。可通过 outputDir 自定义输出目录。

配置选项

Feature 文件：支持单个模式、多个模式，以及 include/exclude 排除模式。
Step 定义：支持单个或多个模式，可混合 JavaScript 与 TypeScript。
导入测试实例：使用自定义 fixtures 时，通过 importTestFrom 指定自定义测试实例路径。fixtures 文件需导出 test 实例，并使用 createBdd(test) 生成 Given、When、Then。
多 Feature 集合：可为不同测试项目配置不同的 feature 集合与输出目录。
语言配置：通过 language 选项配置 Gherkin 语言，支持 en（默认）、de、fr、es、ru 等遵循 Gherkin 规范的语言。
引号风格：通过 quotes 选项配置生成文件中的引号风格，可选 'single'、'double'、'backtick'。
详细模式：通过 verbose: true 在生成期间启用详细输出。

与 Playwright 配置集成

可将 defineBddConfig() 返回的 testDir 与 Playwright 的 fullyParallel、retries、workers、reporter、use、projects、webServer 等配置组合使用。也支持按环境（如 CI）区分配置，例如设置不同的超时、重试次数与 worker 数量。

使用方式

运行测试

# 从 feature 生成测试文件
npx bddgen

# 运行 Playwright 测试
npx playwright test

# 或合并执行
npx bddgen && npx playwright test

监听模式

# 监听 feature 与 step 文件
npx bddgen --watch

# 在另一个终端运行测试
npx playwright test --watch

导出 Step 定义

npx bddgen export

适用场景

搭建新的 Playwright BDD 项目
配置多个 feature 集合
将自定义 fixtures 与 BDD 集成
排查配置问题
优化测试生成
搭建 monorepo 测试
配置语言/i18n 支持
组件测试与 API 测试配置

常见配置模式

Monorepo 设置：在 packages/e2e/playwright.config.ts 中配置，使用环境变量指定 baseURL。
组件测试：指定组件相关的 feature 与 step 路径，并配置 ctPort。
API 测试：指定 API 相关的 feature 与 step 路径，并配置 baseURL。

故障排查

找不到 Step：检查 step 模式是否匹配目录结构、step 定义文本是否有拼写错误、step 文件是否包含在 steps 配置中，可运行 npx bddgen export 查看所有已注册的 step。
导入错误：检查 importTestFrom 路径是否正确、文件是否导出 test 与 step 函数、TypeScript 配置是否包含 step 文件。
生成错误：验证 feature 文件语法、检查缺失的 step 定义、使用 verbose: true 查看详情、验证 step 文件中的所有导入。

最佳实践

按功能组织 feature 与 step
使用 fixtures 共享 setup 逻辑
保持 step 简单，每个 step 定义一个动作
复用 step，编写跨 feature 通用的 step
可选地提交生成文件以便调试
在 CI 中先运行 bddgen 再运行测试
使用 TypeScript 编写 step 定义以获得类型安全
导出 step 供团队参考
让 Playwright 处理并行执行
将生成目录加入 gitignore

限制

本技能资料未提供关于收费、价格、平台支持范围或具体效果保证的信息。

技能介绍

用途

安装