playwright-bdd-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright BDD Configuration

Playwright BDD 配置

Expert knowledge of Playwright BDD configuration, project setup, and integration with Playwright's testing framework for behavior-driven development.

具备Playwright BDD配置、项目搭建以及与Playwright测试框架集成以实现行为驱动开发的专业知识。

Overview

概述

Playwright BDD enables running Gherkin-syntax BDD tests with Playwright Test. Configuration is done through the

playwright.config.ts

file using the

defineBddConfig()

function, which generates Playwright test files from your

.feature

files.

Playwright BDD支持使用Playwright Test运行Gherkin语法的BDD测试。配置通过

playwright.config.ts

文件中的

defineBddConfig()

函数完成，该函数会从你的

.feature

文件生成Playwright测试文件。

Installation

安装

bash

undefined

bash

undefined

Install playwright-bdd

npm install -D playwright-bdd

Or with specific Playwright version

npm install -D playwright-bdd @playwright/test

undefined

npm install -D playwright-bdd @playwright/test

undefined

Basic Configuration

基础配置

Minimal Setup

最小化设置

typescript

// 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,
});

typescript

// 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,
});

Generated Test Directory

生成的测试目录

The

defineBddConfig()

function returns a path to the generated test directory. By default, this is

.features-gen

in your project root:

typescript

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

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

defineBddConfig()

函数会返回生成的测试目录路径。默认情况下，该目录位于项目根目录下的

.features-gen

：

typescript

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

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

Custom Output Directory

自定义输出目录

typescript

const testDir = defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  outputDir: '.generated-tests', // Custom output directory
});

typescript

const testDir = defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  outputDir: '.generated-tests', // Custom output directory
});

Configuration Options

配置选项

Feature Files

特性文件

Configure where to find feature files:

typescript

defineBddConfig({
  // Single pattern
  features: 'features/**/*.feature',

  // Multiple patterns
  features: [
    'features/**/*.feature',
    'specs/**/*.feature',
  ],

  // Exclude patterns
  features: {
    include: 'features/**/*.feature',
    exclude: 'features/**/skip-*.feature',
  },
});

配置特性文件的查找位置：

typescript

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

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

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

Step Definitions

步骤定义

Configure step definition locations:

typescript

defineBddConfig({
  // Single pattern
  steps: 'steps/**/*.ts',

  // Multiple patterns
  steps: [
    'steps/**/*.ts',
    'features/**/*.steps.ts',
  ],

  // Mixed JavaScript and TypeScript
  steps: [
    'steps/**/*.ts',
    'steps/**/*.js',
  ],
});

配置步骤定义文件的位置：

typescript

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

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

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

Import Test Instance

导入测试实例

When using custom fixtures, import the test instance:

typescript

defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  importTestFrom: 'steps/fixtures.ts', // Path to your custom test instance
});

The fixtures file should export the test instance:

typescript

// 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);

使用自定义fixture时，导入测试实例：

typescript

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

fixture文件需要导出测试实例：

typescript

// 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);

Advanced Configuration

高级配置

Multiple Feature Sets

多特性集

Configure different feature sets for different test projects:

typescript

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,
    },
  ],
});

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

typescript

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,
    },
  ],
});

Language Configuration

语言配置

Configure the Gherkin language:

typescript

defineBddConfig({
  features: 'features/**/*.feature',
  steps: 'steps/**/*.ts',
  language: 'de', // German keywords (Gegeben, Wenn, Dann)
});

Supported languages follow the Gherkin specification:

```
en
```
(English - default)
```
de
```
(German)
```
fr
```
(French)
```
es
```
(Spanish)
```
ru
```
(Russian)
And many more...

配置Gherkin语言：

typescript

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

支持的语言遵循Gherkin规范：

```
en
```
（英语 - 默认）
```
de
```
（德语）
```
fr
```
（法语）
```
es
```
（西班牙语）
```
ru
```
（俄语）
以及更多...

Quote Style

引号风格

Configure quote style in generated test files:

typescript

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

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

typescript

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

Verbose Mode

详细模式

Enable verbose output during generation:

typescript

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

在生成过程中启用详细输出：

typescript

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

Integration with Playwright Config

与Playwright配置集成

Full Configuration Example

完整配置示例

typescript

// 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,
  },
});

typescript

// 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,
  },
});

Environment-Specific Configuration

环境特定配置

typescript

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,
});

typescript

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,
});

Running Tests

运行测试

Generate and Run

生成并运行

bash

undefined

bash

undefined

Generate test files from features

npx bddgen

Run Playwright tests

npx playwright test

Or combine both

npx bddgen && npx playwright test

undefined

npx bddgen && npx playwright test

undefined

Watch Mode

监听模式

For development, regenerate on file changes:

bash

undefined

开发时，文件变化时重新生成：

bash

undefined

Watch feature and step files

npx bddgen --watch

In another terminal, run tests

npx playwright test --watch

undefined

npx playwright test --watch

undefined

Export Step Definitions

导出步骤定义

Export all step definitions for documentation:

bash

npx bddgen export

导出所有步骤定义用于文档：

bash

npx bddgen export

Directory Structure

目录结构

Recommended project structure:

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/          # Generated (gitignore this)
    └── features/
        ├── auth/
        │   ├── login.feature.spec.js
        │   └── logout.feature.spec.js
        └── products/
            └── catalog.feature.spec.js

推荐的项目结构：

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/          # Generated (gitignore this)
    └── features/
        ├── auth/
        │   ├── login.feature.spec.js
        │   └── logout.feature.spec.js
        └── products/
            └── catalog.feature.spec.js

Gitignore Generated Files

Git忽略生成文件

Add to

.gitignore

undefined

添加到

.gitignore

：

undefined

Playwright BDD generated files

.features-gen/

undefined

.features-gen/

undefined

Common Configuration Patterns

常见配置模式

Monorepo Setup

单仓库（Monorepo）设置

typescript

// 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',
  },
});

typescript

// 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',
  },
});

Component Testing

组件测试

typescript

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,
  },
});

typescript

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 Testing

API测试

typescript

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',
  },
});

typescript

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',
  },
});

Troubleshooting

故障排除

Steps Not Found

步骤未找到

If steps are not being matched:

Verify step patterns match your directory structure
Check for typos in step definition text
Ensure step files are included in the
```
steps
```
config
Run
```
npx bddgen export
```
to see all registered steps

如果步骤未匹配到：

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

Import Errors

导入错误

If imports fail in generated files:

Verify
```
importTestFrom
```
path is correct
Ensure the file exports
```
test
```
and step functions
Check TypeScript configuration includes step files

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

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

Generation Errors

生成错误

bddgen

fails:

Validate feature file syntax
Check for missing step definitions
Run with
```
verbose: true
```
for details
Verify all imports in step files

如果

bddgen

执行失败：

验证特性文件语法
检查是否缺少步骤定义
启用
```
verbose: true
```
查看详细信息
验证步骤文件中的所有导入

Best Practices

最佳实践

Organize by Feature - Group features and steps by domain
Use Fixtures - Share setup logic via Playwright fixtures
Keep Steps Simple - One action per step definition
Reuse Steps - Write generic steps that work across features
Version Generated Files - Optionally commit for debugging
CI Integration - Run
```
bddgen
```
before tests in CI
Type Safety - Use TypeScript for step definitions
Documentation - Export steps for team reference
Parallel Execution - Let Playwright handle parallelism
Clean Output - Gitignore generated directory

按特性组织 - 按领域分组特性和步骤
使用Fixture - 通过Playwright fixture共享设置逻辑
保持步骤简洁 - 每个步骤定义对应一个操作
复用步骤 - 编写可跨特性使用的通用步骤
版本化生成文件 - 可选择提交以便调试
CI集成 - 在CI中运行测试前先执行
```
bddgen
```
类型安全 - 使用TypeScript编写步骤定义
文档化 - 导出步骤供团队参考
并行执行 - 让Playwright处理并行运行
清理输出 - 将生成目录添加到Git忽略

When to Use This Skill

何时使用此技能

Setting up a new Playwright BDD project
Configuring multiple feature sets
Integrating custom fixtures with BDD
Troubleshooting configuration issues
Optimizing test generation
Setting up monorepo testing
Configuring language/i18n support

搭建新的Playwright BDD项目
配置多个特性集
将自定义fixture与BDD集成
排查配置问题
优化测试生成
搭建单仓库测试
配置语言/国际化支持