Playwright Test 测试参数化实战：数据驱动用例、项目级参数与 CSV 驱动测试

Playwright Test 的参数化能力分为两个层次：在测试级别用数据数组循环生成一组独立用例，以及在项目级别通过 test.extend() 自定义 option + projects 配置实现多配置并发运行。本文基于官方文档 test-parameterize-js.md 展开，并深入当前仓库源码，解释 { option: true } 的校验机制、use 配置如何覆盖 option 值，以及 1.18 版本参数化行为变更的来龙去脉，读完后可直接落地数据驱动测试、多环境参数化与 CSV 驱动测试三种实战方案。

一、两种参数化方式概览

官方文档开篇即给出结论：参数化既可以在测试级别做，也可以在项目级别做（You can either parameterize tests on a test level or on a project level）。

• 测试级参数化：本质是"动态生成多个 test 用例"，每个参数对应一条独立测试，天然支持并行、重试与失败隔离；
• 项目级参数化：本质是"同一份测试代码、多份配置运行"，适合在 Alice/Bob 两种身份、staging/production 两种环境等场景下复用全部用例。

两者并不互斥：数据差异小用测试级 forEach 即可；配置差异大且需要独立执行（独立浏览器配置、独立 reporter、独立并发度）时用 projects。

二、测试级参数化：用 forEach 生成一组用例

文档给出的标准模式是"数据数组 + forEach + 模板字符串命名"：

[
  { name: 'Alice', expected: 'Hello, Alice!' },
  { name: 'Bob', expected: 'Hello, Bob!' },
  { name: 'Charlie', expected: 'Hello, Charlie!' },
].forEach(({ name, expected }) => {
  // You can also do it with test.describe() or with multiple tests as long the test name is unique.
  test(`testing with ${name}`, async ({ page }) => {
    await page.goto(`https://example.com/greet?name=${name}`);
    await expect(page.getByRole('heading')).toHaveText(expected);
  });
});

关键要点（继承自原文档）：

1. 用例名必须唯一。每个参数迭代都会注册一个真实的 test 用例，test('testing with Alice')、test('testing with Bob') 是并列的三条用例，因此模板字符串中必须包含能区分参数的变量；
2. 文档同时注明：也可以改用 test.describe() 包裹、或者在 forEach 里注册多条 test，前提同样是每个 test 名字唯一；
3. 参数化用例在运行结果、报告、--grep 过滤中都以独立用例身份出现，可以单独重跑（如 npx playwright test -g "testing with Bob"）。

Before / After 钩子的两种摆放位置

钩子的作用域由它注册在哪个 suite 决定，这直接决定它是"跑一次"还是"每个参数跑一次"。

方式一（推荐）：钩子放在 forEach 之外，只执行一次。 文档指出大多数场景都应如此，钩子挂在文件级 suite 上，对所有参数化用例生效：

test.beforeEach(async ({ page }) => {
  // ...
});

test.afterEach(async ({ page }) => {
  // ...
});

[
  { name: 'Alice', expected: 'Hello, Alice!' },
  { name: 'Bob', expected: 'Hello, Bob!' },
  { name: 'Charlie', expected: 'Hello, Charlie!' },
].forEach(({ name, expected }) => {
  test(`testing with ${name}`, async ({ page }) => {
    await page.goto(`https://example.com/greet?name=${name}`);
    await expect(page.getByRole('heading')).toHaveText(expected);
  });
});

方式二：钩子放进 describe，每次迭代各执行一次。 如果每次迭代需要独立的 setup/teardown，就把 beforeEach 放进 forEach 内的 test.describe() 中：

[
  { name: 'Alice', expected: 'Hello, Alice!' },
  { name: 'Bob', expected: 'Hello, Bob!' },
  { name: 'Charlie', expected: 'Hello, Charlie!' },
].forEach(({ name, expected }) => {
  test.describe(() => {
    test.beforeEach(async ({ page }) => {
      await page.goto(`https://example.com/greet?name=${name}`);
    });
    test(`testing with ${expected}`, async ({ page }) => {
      await expect(page.getByRole('heading')).toHaveText(expected);
    });
  });
});

从源码结构看，这种"钩子作用域随 suite 嵌套变化"的行为与 runner 的 suite 树实现一致：每个 test.describe() 都是一个独立的 Suite，钩子注册在哪个 suite 上，就只对属于该 suite 的用例生效。可以推断，把钩子放在 forEach 内部时会为每个参数创建一层子 suite，因此钩子按参数分别执行。

三、项目级参数化：option fixture + projects 配置

当参数不是"数据"而是"运行配置"（身份、环境、浏览器选项）时，应使用 Playwright Test 的项目机制。官方流程分四步：定义 option → 测试中消费 → 用 projects 覆盖 → （可选）在 fixture 中消费。

3.1 定义自定义 option 并提供默认值

JavaScript 版（my-test.js 中的示例）：

const base = require('@playwright/test');

exports.test = base.test.extend({
  // Define an option and provide a default value.
  // We can later override it in the config.
  person: ['John', { option: true }],
});

TypeScript 版则通过 TestOptions 类型约束 option 的名称与取值类型：

import { test as base } from '@playwright/test';

export type TestOptions = {
  person: string;
};

export const test = base.extend<TestOptions>({
  // Define an option and provide a default value.
  // We can later override it in the config.
  person: ['John', { option: true }],
});

要点：

• ['John', { option: true }] 是 fixture 的 tuple 注册形式：数组第一项是默认值/实现，第二项是注册选项；
• { option: true } 是参数化的关键标记，没有这个标记，配置文件里的 use 就无法覆盖该 fixture（下文源码一节会解释为什么）；
• 默认值 'John' 在没有任何项目覆盖时生效，保证测试在脱离配置（如直接 npx playwright test 某个文件之外的上下文）时也能运行。

3.2 在测试中消费 option

用法与 fixtures 完全一致——在测试函数的参数中按名字解构即可：

import { test } from './my-test';

test('test 1', async ({ page, person }) => {
  await page.goto(`/index.html`);
  await expect(page.locator('#node')).toContainText(person);
  // ...
});

3.3 用 projects 跑多份配置

文档示例声明两个项目 alice 与 bob，各自通过 use 覆盖 person 的值：

// @ts-check

module.exports = defineConfig({
  projects: [
    {
      name: 'alice',
      use: { person: 'Alice' },
    },
    {
      name: 'bob',
      use: { person: 'Bob' },
    },
  ]
});

import { defineConfig } from '@playwright/test';
import type { TestOptions } from './my-test';

export default defineConfig<TestOptions>({
  projects: [
    {
      name: 'alice',
      use: { person: 'Alice' },
    },
    {
      name: 'bob',
      use: { person: 'Bob' },
    },
  ]
});

注意 defineConfig<TestOptions>() 的泛型把自定义 option 纳入了类型系统，use 中写错 key 或类型不匹配会直接报编译错误。

从源码结构看，覆盖发生在两处：

1. 配置合并：config.ts 中 const use = mergeObjects(config.use, projectConfig.use, configCLIOverrides.use)，即"全局 use ← 项目级 use ← 命令行 -- 覆盖"三层依次合并，项目级值优先于全局值；
2. option 注入：poolBuilder.ts 的 _buildTestTypePool 会取 this._project?.project?.use 作为 optionOverrides.overrides 传入 FixturePool。也就是说每个项目构建出自己独立的 fixture 池，option 的"值"来自所在项目的 use，这正是"同一份测试代码、按项目取不同参数"的实现基础。

3.4 在 fixture 中消费 option

文档还展示了在 fixture 内部读取 option 的典型用法：重写 page fixture，用 person 值自动完成"进入聊天室"的操作，使每个用例拿到的 page 已完成初始化：

const base = require('@playwright/test');

exports.test = base.test.extend({
  // Define an option and provide a default value.
  // We can later override it in the config.
  person: ['John', { option: true }],

  // Override default "page" fixture.
  page: async ({ page, person }, use) => {
    await page.goto('/chat');
    // We use "person" parameter as a "name" for the chat room.
    await page.getByLabel('User Name').fill(person);
    await page.getByText('Enter chat room').click();
    // Each test will get a "page" that already has the person name.
    await use(page);
  },
});

TypeScript 版本逻辑相同，仅在 extend<TestOptions> 中声明类型。这种"option 作为 fixture 参数"的模式说明：option 本质上就是一种可以被依赖注入的 fixture，任何 fixture 只要把 person 声明为形参就能拿到当前项目的取值。

3.5 源码深挖：{ option: true } 的校验与覆盖机制

{ option: true } 之所以是硬性要求，源于当前版本 fixture 注册时的显式校验。在 fixtures.ts 中可以找到完整证据链：

（1）识别 option 元组：

// packages/playwright/src/common/fixtures.ts
function isFixtureTuple(value: any): value is FixtureTuple {
  return Array.isArray(value) && typeof value[1] === 'object';
}

function isFixtureOption(value: any): value is FixtureTuple {
  return isFixtureTuple(value) && !!value[1].option;
}

（2）只把"配置中出现且声明为 option"的 fixture 注入覆盖层：

// Process option overrides immediately after original option definitions,
// so that any test.use() override it.
const selectedOverrides: Fixtures = {};
for (const [key, value] of Object.entries(list.fixtures)) {
  if (isFixtureOption(value) && overrideKeys.has(key))
    (selectedOverrides as any)[key] = [(allOverrides as any)[key], value[1]];
}

（3）非 option fixture 出现在 use 中直接报加载错误：

if (registration && !isOptionFixture(registration))
  this._addLoadError(`Fixture "${key}" cannot be overridden in the configuration "use" section. Only fixtures registered with { option: true } can be set in the config.`, optionOverrides.location);

此外，isOptionFixture 会沿 registration.super 链向上追溯，因此继承的 option（如在派生 fixture 类型中未重新注册、但父类型中标记了 option: true）同样被视为可配置项。而"用 undefined 覆盖 option"被刻意定义为"回退到配置或原始默认值"：

// Overriding option with "undefined" value means setting it to the default value
// from the config or from the original declaration of the option.
if (fn === undefined && previous && isOptionFixture(previous)) {
  let original = previous;
  while (!original.optionOverride && original.super)
    original = original.super;
  fn = original.fn;
}

这解释了 test.use({ person: undefined }) 这类写法的语义：不是清空值，而是撤销覆盖、回归默认。

3.6 版本注意：1.18 的参数化行为变更

文档明确提示：Parameterized projects 的行为在 1.18 版本发生了变化，详见 release notes 中的 Breaking change: custom config options。查阅该节的实际内容（release-notes-js.md 的 "Breaking change: custom config options" 小节），变更要点是：

• 1.18 之前的错误写法：任何通过 test.extend 引入的 fixture 都能在 use 中被覆盖，例如 myParameter: 'default'（无 tuple、无 option 标记）配合 use: { myParameter: 'value' } 曾可工作；
• 1.18 起：必须显式声明 myParameter: ['default', { option: true }]，use 才能覆盖它。

这与上文源码中的加载错误逻辑完全对应——当前仓库的实现已经按"白名单制"执行，只有带 option: true 的 fixture 允许进入 use 覆盖通道。阅读旧版教程或迁移旧项目时，凡是 use 中配置自定义 fixture 却不生效、或报 "cannot be overridden in the configuration 'use' section" 错误的，都应检查是否缺少 { option: true } 标记。

四、用环境变量传参：命令行注入与 .env 文件

文档的第三部分讲解"参数从命令行/环境注入"，适用于密码、环境开关等不宜硬编码进源码的值。

4.1 命令行设置环境变量

示例测试读取 process.env.USER_NAME 与 process.env.PASSWORD 填充登录表单：

test(`example test`, async ({ page }) => {
  // ...
  await page.getByLabel('User Name').fill(process.env.USER_NAME);
  await page.getByLabel('Password').fill(process.env.PASSWORD);
});

三种 shell 的等价写法（文档原文完整给出）：

USER_NAME=me PASSWORD=secret npx playwright test

set USER_NAME=me
set PASSWORD=secret
npx playwright test

$env:USER_NAME=me
$env:PASSWORD=secret
npx playwright test

4.2 配置文件也可以读环境变量

playwright.config.ts 本身就是 Node.js 模块，可以在加载时读取环境，实现"环境变量切换 baseURL"：

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    baseURL: process.env.STAGING === '1' ? 'http://staging.example.test/' : 'http://example.test/',
  }
});

STAGING=1 npx playwright test

（batch/powershell 写法分别为 set STAGING=1 与 $env:STAGING=1，后接 npx playwright test。）

4.3 .env 文件：用 dotenv 集中管理变量

文档推荐用 dotenv 一类的包在配置文件最前面读取 .env：

import { defineConfig } from '@playwright/test';
import dotenv from 'dotenv';
import path from 'path';

// Read from ".env" file.
dotenv.config({ path: path.resolve(__dirname, '.env') });

// Alternatively, read from "../my.env" file.
dotenv.config({ path: path.resolve(__dirname, '..', 'my.env') });

export default defineConfig({
  use: {
    baseURL: process.env.STAGING === '1' ? 'http://staging.example.test/' : 'http://example.test/',
  }
});

.env 文件内容示例：

# .env file
STAGING=0
USER_NAME=me
PASSWORD=secret

之后照常运行 npx playwright test 即可。需要强调的适用前提：dotenv 属于第三方依赖，Playwright 官方文档以"consider something like .env files"的措辞推荐该模式，而不是内置能力——即 Playwright 本身不自动加载 .env，加载动作发生在你的配置文件里。

五、CSV 文件驱动测试生成

最后一节利用"test-runner 运行在 Node.js 中"这一事实：可以在加载测试文件时直接读取文件系统，用任意 CSV 库把外部数据表展开为用例。

示例数据文件 input.csv（文档原文）：

"title=CSV file"
"test_case","some_value","some_other_value"
"value 1","value 11","foobar1"
"value 2","value 22","foobar21"
"value 3","value 33","foobar321"
"value 4","value 44","foobar4321"

（注：以上以 txt 代码块呈现，首行为表头，其余每行是一条参数记录。）

使用 npm 的 csv-parse 库生成用例：

import fs from 'fs';
import path from 'path';
import { test } from '@playwright/test';
import { parse } from 'csv-parse/sync';

const records = parse(fs.readFileSync(path.join(__dirname, 'input.csv')), {
  columns: true,
  skip_empty_lines: true
});

for (const record of records) {
  test(`foo: ${record.test_case}`, async ({ page }) => {
    console.log(record.test_case, record.some_value, record.some_other_value);
  });
}

参数说明（结合示例补充）：

• columns: true：把首行作为列名，每行解析为以列名为 key 的对象（所以能用 record.test_case 访问）；
• skip_empty_lines: true：忽略空行，避免把空行解析成空用例；
• 用例名模板 foo: ${record.test_case} 依赖 test_case 列的唯一性，与第二节"test 名字必须唯一"的约束同理。

从运行时机看，这段代码在测试文件被加载、用例被收集（collection）阶段同步执行，即 CSV 在 npx playwright test 启动时读一次，而不是每个 worker 各自读取。这带来两个实践要点：一是 CSV 路径建议用 path.join(__dirname, ...) 基于测试文件定位，避免依赖进程工作目录；二是数据量很大时，用例总数会等于 CSV 行数，应评估报告与并发压力。

六、选型小结与验证入口

场景	推荐方式	关键机制
同一页面的多种输入数据	forEach + 模板命名	动态生成独立用例，名字必须唯一
每个参数需要独立 setup	forEach 内 test.describe() + 内部钩子	钩子作用域随 suite 嵌套
多身份/多环境跑全套用例	option: true fixture + projects	每项目独立 fixture 池，use 覆盖 option
密钥、环境开关	环境变量 / dotenv	配置与测试代码均读 process.env
外部数据表	CSV + csv-parse	收集阶段读文件循环注册用例

如需进一步深入，可查阅仓库中对应实现与文档：option 校验与覆盖逻辑在 fixtures.ts，项目级 use 的 option 注入在 poolBuilder.ts，配置三层合并在 config.ts；1.18 的 breaking change 全文见 release-notes-js.md；fixture 基础概念见 test-fixtures-js.md。