⚡

PlaywrightBDD配置Skill playwright-bdd-configuration

这个技能用于配置Playwright行为驱动开发项目，通过设置defineBddConfig()函数，管理特征文件和步骤文件路径，并与Playwright测试框架集成，支持Gherkin语法的BDD测试。关键词包括Playwright BDD、行为驱动开发、测试自动化、Gherkin、配置管理、测试框架、项目设置。

测试 0 次安装 0 次浏览 更新于 3/25/2026

名称: playwright-bdd配置 用户可调用: false 描述: 在配置Playwright BDD项目时使用，用于设置defineBddConfig()、配置特征文件和步骤文件路径，并与Playwright配置集成。 允许工具: [Read, Write, Edit, Bash, Glob, Grep]

Playwright BDD 配置

关于Playwright BDD配置、项目设置和与Playwright测试框架集成的专家知识，用于行为驱动开发。

概述

Playwright BDD 允许使用Gherkin语法的BDD测试与Playwright Test运行。配置通过 playwright.config.ts 文件使用 defineBddConfig() 函数完成，该函数从您的 .feature 文件生成Playwright测试文件。

安装

# 安装 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：

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

// testDir = '.features-gen/features'

自定义输出目录

const testDir = defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  outputDir: '.generated-tests', // 自定义输出目录
});

配置选项

特征文件

配置特征文件的位置：

defineBddConfig({
  // 单个模式
  features: 'features/**/*.feature',

  // 多个模式
  features: [
    'features/**/*.feature',
    'specs/**/*.feature',
  ],

  // 排除模式
  features: {
    include: 'features/**/*.feature',
    exclude: 'features/**/skip-*.feature',
  },
});

步骤定义

配置步骤定义位置：

defineBddConfig({
  // 单个模式
  steps: 'steps/**/*.ts',

  // 多个模式
  steps: [
    'steps/**/*.ts',
    'features/**/*.steps.ts',
  ],

  // 混合JavaScript和TypeScript
  steps: [
    'steps/**/*.ts',
    'steps/**/*.js',
  ],
});

导入测试实例

当使用自定义夹具时，导入测试实例：

defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  importTestFrom: 'steps/fixtures.ts', // 自定义测试实例的路径
});

夹具文件应导出测试实例：

// steps/fixtures.ts
import { test as base, createBdd } from 'playwright-bdd';

export const test = base.extend<{
  todoPage: TodoPage;
}>({
  todoPage: async ({ page }, use) => {
    const todoPage = new TodoPage(page);
    await use(todoPage);
  },
});

export const { Given, When, Then } = createBdd(test);

高级配置

多个特征集

为不同的测试项目配置不同的特征集：

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

const coreTestDir = defineBddConfig({
  features: 'features/core/**/*.feature',
  steps: 'steps/core/**/*.ts',
  outputDir: '.features-gen/core',
});

const adminTestDir = defineBddConfig({
  features: 'features/admin/**/*.feature',
  steps: 'steps/admin/**/*.ts',
  outputDir: '.features-gen/admin',
});

export default defineConfig({
  projects: [
    {
      name: 'core',
      testDir: coreTestDir,
    },
    {
      name: 'admin',
      testDir: adminTestDir,
    },
  ],
});

语言配置

配置Gherkin语言：

defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  language: 'de', // 德语关键字（Gegeben, Wenn, Dann）
});

支持的语言遵循Gherkin规范：

  • en（英语 - 默认）
  • de（德语）
  • fr（法语）
  • es（西班牙语）
  • ru（俄语）
  • 等等…

引号风格

配置生成测试文件中的引号风格：

defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  quotes: 'single', // 'single' | 'double' | 'backtick'
});

详细模式

在生成期间启用详细输出：

defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  verbose: true,
});

与Playwright配置集成

完整配置示例

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

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

export default defineConfig({
  testDir,
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ['html'],
    ['json', { outputFile: 'test-results/results.json' }],
  ],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

环境特定配置

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

const isCI = !!process.env.CI;

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

export default defineConfig({
  testDir,
  timeout: isCI ? 60000 : 30000,
  retries: isCI ? 2 : 0,
  workers: isCI ? 4 : undefined,
});

运行测试

生成和运行

# 从特征文件生成测试文件
npx bddgen

# 运行Playwright测试
npx playwright test

# 或两者结合
npx bddgen && npx playwright test

监视模式

在开发期间，在文件更改时重新生成：

# 监视特征和步骤文件
npx bddgen --watch

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

导出步骤定义

导出所有步骤定义以供文档使用：

npx bddgen export

目录结构

推荐的项目结构：

project/
├── playwright.config.ts
├── features/
│   ├── auth/
│   │   ├── login.feature
│   │   └── logout.feature
│   └── products/
│       └── catalog.feature
├── steps/
│   ├── auth/
│   │   ├── login.steps.ts
│   │   └── logout.steps.ts
│   ├── products/
│   │   └── catalog.steps.ts
│   └── fixtures.ts
└── .features-gen/          # 生成的（gitignore这个）
    └── features/
        ├── auth/
        │   ├── login.feature.spec.js
        │   └── logout.feature.spec.js
        └── products/
            └── catalog.feature.spec.js

Gitignore生成的文件

添加到 .gitignore：

# Playwright BDD生成的文件
.features-gen/

常见配置模式

Monorepo设置

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

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

export default defineConfig({
  testDir,
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
  },
});

组件测试

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

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

export default defineConfig({
  testDir,
  use: {
    ctPort: 3100,
  },
});

API测试

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

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

export default defineConfig({
  testDir,
  use: {
    baseURL: 'https://api.example.com',
  },
});

故障排除

步骤未找到

如果步骤未被匹配：

  1. 验证步骤模式是否匹配您的目录结构
  2. 检查步骤定义文本中的拼写错误
  3. 确保步骤文件包含在 steps 配置中
  4. 运行 npx bddgen export 查看所有注册步骤

导入错误

如果在生成的文件中导入失败：

  1. 验证 importTestFrom 路径是否正确
  2. 确保文件导出 test 和步骤函数
  3. 检查TypeScript配置是否包含步骤文件

生成错误

如果 bddgen 失败：

  1. 验证特征文件语法
  2. 检查缺失的步骤定义
  3. 运行 verbose: true 以获取详细信息
  4. 验证步骤文件中的所有导入

最佳实践

  1. 按特征组织 - 按领域分组特征和步骤
  2. 使用夹具 - 通过Playwright夹具共享设置逻辑
  3. 保持步骤简单 - 每个步骤定义一个动作
  4. 重用步骤 - 编写通用的步骤，跨特征工作
  5. 版本生成的文件 - 可选地提交用于调试
  6. CI集成 - 在CI中运行 bddgen 在测试之前
  7. 类型安全 - 使用TypeScript进行步骤定义
  8. 文档化 - 导出步骤供团队参考
  9. 并行执行 - 让Playwright处理并行性
  10. 清理输出 - Gitignore生成目录

何时使用此技能

  • 设置新的Playwright BDD项目
  • 配置多个特征集
  • 将自定义夹具与BDD集成
  • 故障排除配置问题
  • 优化测试生成
  • 设置monorepo测试
  • 配置语言/i18n支持