跳到主要内容

Fixture

简介​

Playwright Test 基于测试 fixture 的概念。测试 fixture 用于为每个测试建立环境，为测试提供所需的一切，而不需要其他任何东西。测试 fixture 在测试之间是隔离的。使用 fixture，您可以根据测试的含义而不是它们的共同设置对测试进行分组。

内置 fixture​

您已经在您的第一个测试中使用了测试 fixture。

import { test, expect } from '@playwright/test';

test('basic test', async ({ page }) => {
  await page.goto('https://playwright.net.cn/');

  await expect(page).toHaveTitle(/Playwright/);
});

{ page } 参数告诉 Playwright Test 设置 page fixture 并将其提供给您的测试函数。

以下是您最有可能使用的大多数预定义 fixture 的列表

Fixture类型描述
pagePage此测试运行的隔离页面。
contextBrowserContext此测试运行的隔离上下文。page fixture 也属于此上下文。了解如何配置上下文。
browserBrowser浏览器在测试之间共享，以优化资源。了解如何配置浏览器。
browserNamestring当前运行测试的浏览器的名称。可以是 chromium、firefox 或 webkit。
requestAPIRequestContext此测试运行的隔离 APIRequestContext 实例。

没有 fixture​

以下是传统测试风格和基于 fixture 的风格之间，典型测试环境设置的不同之处。

TodoPage 是一个类，它有助于与 Web 应用程序的“待办事项列表”页面进行交互，遵循 Page Object Model 模式。它在内部使用 Playwright 的 page。

点击展开 TodoPage 的代码
todo-page.ts
import type { Page, Locator } from '@playwright/test';

export class TodoPage {
  private readonly inputBox: Locator;
  private readonly todoItems: Locator;

  constructor(public readonly page: Page) {
    this.inputBox = this.page.locator('input.new-todo');
    this.todoItems = this.page.getByTestId('todo-item');
  }

  async goto() {
    await this.page.goto('https://demo.playwright.dev/todomvc/');
  }

  async addToDo(text: string) {
    await this.inputBox.fill(text);
    await this.inputBox.press('Enter');
  }

  async remove(text: string) {
    const todo = this.todoItems.filter({ hasText: text });
    await todo.hover();
    await todo.getByLabel('Delete').click();
  }

  async removeAll() {
    while ((await this.todoItems.count()) > 0) {
      await this.todoItems.first().hover();
      await this.todoItems.getByLabel('Delete').first().click();
    }
  }
}
todo.spec.ts
const { test } = require('@playwright/test');
const { TodoPage } = require('./todo-page');

test.describe('todo tests', () => {
  let todoPage;

  test.beforeEach(async ({ page }) => {
    todoPage = new TodoPage(page);
    await todoPage.goto();
    await todoPage.addToDo('item1');
    await todoPage.addToDo('item2');
  });

  test.afterEach(async () => {
    await todoPage.removeAll();
  });

  test('should add an item', async () => {
    await todoPage.addToDo('my item');
    // ...
  });

  test('should remove an item', async () => {
    await todoPage.remove('item1');
    // ...
  });
});

使用 fixture​

与 before/after 钩子相比，fixture 有许多优点

  • Fixture 将 setup 和 teardown 封装 在同一位置，因此更容易编写。因此，如果您有一个 after 钩子来拆除在 before 钩子中创建的内容，请考虑将它们转换为 fixture。
  • Fixture 在测试文件之间是可重用的 - 您可以定义一次并在所有测试中使用。这就是 Playwright 的内置 page fixture 的工作方式。因此，如果您有一个在多个测试中使用的辅助函数，请考虑将其转换为 fixture。
  • Fixture 是按需的 - 您可以定义任意数量的 fixture，Playwright Test 将仅设置您的测试所需的 fixture，而不会设置其他 fixture。
  • Fixture 是可组合的 - 它们可以相互依赖以提供复杂的行为。
  • Fixture 是灵活的。测试可以使用 fixture 的任何组合来定制它们需要的精确环境，而不会影响其他测试。
  • Fixture 简化了分组。您不再需要将测试包装在设置环境的 describe 中，并且可以自由地根据测试的含义对测试进行分组。
点击展开 TodoPage 的代码
todo-page.ts
import type { Page, Locator } from '@playwright/test';

export class TodoPage {
  private readonly inputBox: Locator;
  private readonly todoItems: Locator;

  constructor(public readonly page: Page) {
    this.inputBox = this.page.locator('input.new-todo');
    this.todoItems = this.page.getByTestId('todo-item');
  }

  async goto() {
    await this.page.goto('https://demo.playwright.dev/todomvc/');
  }

  async addToDo(text: string) {
    await this.inputBox.fill(text);
    await this.inputBox.press('Enter');
  }

  async remove(text: string) {
    const todo = this.todoItems.filter({ hasText: text });
    await todo.hover();
    await todo.getByLabel('Delete').click();
  }

  async removeAll() {
    while ((await this.todoItems.count()) > 0) {
      await this.todoItems.first().hover();
      await this.todoItems.getByLabel('Delete').first().click();
    }
  }
}
example.spec.ts
import { test as base } from '@playwright/test';
import { TodoPage } from './todo-page';

// Extend basic test by providing a "todoPage" fixture.
const test = base.extend<{ todoPage: TodoPage }>({
  todoPage: async ({ page }, use) => {
    const todoPage = new TodoPage(page);
    await todoPage.goto();
    await todoPage.addToDo('item1');
    await todoPage.addToDo('item2');
    await use(todoPage);
    await todoPage.removeAll();
  },
});

test('should add an item', async ({ todoPage }) => {
  await todoPage.addToDo('my item');
  // ...
});

test('should remove an item', async ({ todoPage }) => {
  await todoPage.remove('item1');
  // ...
});

创建 fixture​

要创建您自己的 fixture，请使用 test.extend() 创建一个新的 test 对象，其中将包含它。

下面我们创建两个遵循 Page Object Model 模式的 fixture todoPage 和 settingsPage。

点击展开 TodoPage 和 SettingsPage 的代码
todo-page.ts
import type { Page, Locator } from '@playwright/test';

export class TodoPage {
  private readonly inputBox: Locator;
  private readonly todoItems: Locator;

  constructor(public readonly page: Page) {
    this.inputBox = this.page.locator('input.new-todo');
    this.todoItems = this.page.getByTestId('todo-item');
  }

  async goto() {
    await this.page.goto('https://demo.playwright.dev/todomvc/');
  }

  async addToDo(text: string) {
    await this.inputBox.fill(text);
    await this.inputBox.press('Enter');
  }

  async remove(text: string) {
    const todo = this.todoItems.filter({ hasText: text });
    await todo.hover();
    await todo.getByLabel('Delete').click();
  }

  async removeAll() {
    while ((await this.todoItems.count()) > 0) {
      await this.todoItems.first().hover();
      await this.todoItems.getByLabel('Delete').first().click();
    }
  }
}

SettingsPage 类似

settings-page.ts
import type { Page } from '@playwright/test';

export class SettingsPage {
  constructor(public readonly page: Page) {
  }

  async switchToDarkMode() {
    // ...
  }
}
my-test.ts
import { test as base } from '@playwright/test';
import { TodoPage } from './todo-page';
import { SettingsPage } from './settings-page';

// Declare the types of your fixtures.
type MyFixtures = {
  todoPage: TodoPage;
  settingsPage: SettingsPage;
};

// Extend base test by providing "todoPage" and "settingsPage".
// This new "test" can be used in multiple test files, and each of them will get the fixtures.
export const test = base.extend<MyFixtures>({
  todoPage: async ({ page }, use) => {
    // Set up the fixture.
    const todoPage = new TodoPage(page);
    await todoPage.goto();
    await todoPage.addToDo('item1');
    await todoPage.addToDo('item2');

    // Use the fixture value in the test.
    await use(todoPage);

    // Clean up the fixture.
    await todoPage.removeAll();
  },

  settingsPage: async ({ page }, use) => {
    await use(new SettingsPage(page));
  },
});
export { expect } from '@playwright/test';
注意

自定义 fixture 名称应以字母或下划线开头，并且只能包含字母、数字、下划线。

使用 fixture​

只需在您的测试函数参数中提及 fixture，测试运行器就会处理它。Fixture 也可在钩子和其他 fixture 中使用。如果您使用 TypeScript，fixture 将具有正确的类型。

下面我们使用上面定义的 todoPage 和 settingsPage fixture。

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

test.beforeEach(async ({ settingsPage }) => {
  await settingsPage.switchToDarkMode();
});

test('basic test', async ({ todoPage, page }) => {
  await todoPage.addToDo('something nice');
  await expect(page.getByTestId('todo-title')).toContainText(['something nice']);
});

覆盖 fixture​

除了创建您自己的 fixture 之外，您还可以覆盖现有的 fixture 以满足您的需求。考虑以下示例，该示例通过自动导航到某些 baseURL 来覆盖 page fixture

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

export const test = base.extend({
  page: async ({ baseURL, page }, use) => {
    await page.goto(baseURL);
    await use(page);
  },
});

请注意，在此示例中，page fixture 能够依赖于其他内置 fixture，例如 testOptions.baseURL。我们现在可以在配置文件中配置 baseURL，或者在测试文件中使用 test.use() 在本地配置。

example.spec.ts

test.use({ baseURL: 'https://playwright.net.cn' });

Fixture 也可以在基本 fixture 完全被其他内容替换的情况下被覆盖。例如，我们可以覆盖 testOptions.storageState fixture 以提供我们自己的数据。

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

export const test = base.extend({
  storageState: async ({}, use) => {
    const cookie = await getAuthCookie();
    await use({ cookies: [cookie] });
  },
});

Worker 作用域的 fixture​

Playwright Test 使用 worker 进程 来运行测试文件。与为单个测试运行设置测试 fixture 类似，为每个 worker 进程设置 worker fixture。您可以在其中设置服务、运行服务器等。Playwright Test 将尽可能多地重用 worker 进程来处理测试文件，前提是它们的 worker fixture 匹配并且环境相同。

下面我们将创建一个 account fixture，该 fixture 将由同一 worker 中的所有测试共享，并覆盖 page fixture 以便为每个测试登录到此帐户。为了生成唯一的帐户，我们将使用任何测试或 fixture 都可用的 workerInfo.workerIndex。请注意 worker fixture 的元组式语法 - 我们必须传递 {scope: 'worker'}，以便测试运行器为每个 worker 设置一次此 fixture。

my-test.ts
import { test as base } from '@playwright/test';

type Account = {
  username: string;
  password: string;
};

// Note that we pass worker fixture types as a second template parameter.
export const test = base.extend<{}, { account: Account }>({
  account: [async ({ browser }, use, workerInfo) => {
    // Unique username.
    const username = 'user' + workerInfo.workerIndex;
    const password = 'verysecure';

    // Create the account with Playwright.
    const page = await browser.newPage();
    await page.goto('/signup');
    await page.getByLabel('User Name').fill(username);
    await page.getByLabel('Password').fill(password);
    await page.getByText('Sign up').click();
    // Make sure everything is ok.
    await expect(page.getByTestId('result')).toHaveText('Success');
    // Do not forget to cleanup.
    await page.close();

    // Use the account value.
    await use({ username, password });
  }, { scope: 'worker' }],

  page: async ({ page, account }, use) => {
    // Sign in with our account.
    const { username, password } = account;
    await page.goto('/signin');
    await page.getByLabel('User Name').fill(username);
    await page.getByLabel('Password').fill(password);
    await page.getByText('Sign in').click();
    await expect(page.getByTestId('userinfo')).toHaveText(username);

    // Use signed-in page in the test.
    await use(page);
  },
});
export { expect } from '@playwright/test';

自动 fixture​

即使测试未直接列出自动 fixture，也会为每个测试/worker 设置自动 fixture。要创建自动 fixture，请使用元组语法并传递 { auto: true }。

这是一个示例 fixture，它在测试失败时自动附加调试日志，以便我们稍后可以在报告器中查看日志。请注意它是如何使用 TestInfo 对象的，该对象在每个测试/fixture 中都可用，以检索有关正在运行的测试的元数据。

my-test.ts
import debug from 'debug';
import fs from 'fs';
import { test as base } from '@playwright/test';

export const test = base.extend<{ saveLogs: void }>({
  saveLogs: [async ({}, use, testInfo) => {
    // Collecting logs during the test.
    const logs = [];
    debug.log = (...args) => logs.push(args.map(String).join(''));
    debug.enable('myserver');

    await use();

    // After the test we can check whether the test passed or failed.
    if (testInfo.status !== testInfo.expectedStatus) {
      // outputPath() API guarantees a unique file name.
      const logFile = testInfo.outputPath('logs.txt');
      await fs.promises.writeFile(logFile, logs.join('\n'), 'utf8');
      testInfo.attachments.push({ name: 'logs', contentType: 'text/plain', path: logFile });
    }
  }, { auto: true }],
});
export { expect } from '@playwright/test';

Fixture 超时​

默认情况下，fixture 与测试共享超时。但是，对于慢速 fixture，尤其是 worker 作用域的 fixture，拥有单独的超时是很方便的。这样，您可以保持整体测试超时时间较短，并为慢速 fixture 提供更多时间。

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

const test = base.extend<{ slowFixture: string }>({
  slowFixture: [async ({}, use) => {
    // ... perform a slow operation ...
    await use('hello');
  }, { timeout: 60000 }]
});

test('example test', async ({ slowFixture }) => {
  // ...
});

Fixture 选项​

Playwright Test 支持运行可以单独配置的多个测试项目。您可以使用“选项”fixture 使您的配置选项具有声明性和类型检查。了解有关参数化测试的更多信息。

下面，除了其他示例中的 todoPage fixture 之外，我们还将创建一个 defaultItem 选项。此选项将在配置文件中设置。请注意元组语法和 { option: true } 参数。

点击展开 TodoPage 的代码
todo-page.ts
import type { Page, Locator } from '@playwright/test';

export class TodoPage {
  private readonly inputBox: Locator;
  private readonly todoItems: Locator;

  constructor(public readonly page: Page) {
    this.inputBox = this.page.locator('input.new-todo');
    this.todoItems = this.page.getByTestId('todo-item');
  }

  async goto() {
    await this.page.goto('https://demo.playwright.dev/todomvc/');
  }

  async addToDo(text: string) {
    await this.inputBox.fill(text);
    await this.inputBox.press('Enter');
  }

  async remove(text: string) {
    const todo = this.todoItems.filter({ hasText: text });
    await todo.hover();
    await todo.getByLabel('Delete').click();
  }

  async removeAll() {
    while ((await this.todoItems.count()) > 0) {
      await this.todoItems.first().hover();
      await this.todoItems.getByLabel('Delete').first().click();
    }
  }
}
my-test.ts
import { test as base } from '@playwright/test';
import { TodoPage } from './todo-page';

// Declare your options to type-check your configuration.
export type MyOptions = {
  defaultItem: string;
};
type MyFixtures = {
  todoPage: TodoPage;
};

// Specify both option and fixture types.
export const test = base.extend<MyOptions & MyFixtures>({
  // Define an option and provide a default value.
  // We can later override it in the config.
  defaultItem: ['Something nice', { option: true }],

  // Our "todoPage" fixture depends on the option.
  todoPage: async ({ page, defaultItem }, use) => {
    const todoPage = new TodoPage(page);
    await todoPage.goto();
    await todoPage.addToDo(defaultItem);
    await use(todoPage);
    await todoPage.removeAll();
  },
});
export { expect } from '@playwright/test';

我们现在可以像往常一样使用 todoPage fixture，并在配置文件中设置 defaultItem 选项。

playwright.config.ts
import { defineConfig } from '@playwright/test';
import type { MyOptions } from './my-test';

export default defineConfig<MyOptions>({
  projects: [
    {
      name: 'shopping',
      use: { defaultItem: 'Buy milk' },
    },
    {
      name: 'wellbeing',
      use: { defaultItem: 'Exercise!' },
    },
  ]
});

数组作为选项值

如果您的选项的值是一个数组，例如 [{ name: 'Alice' }, { name: 'Bob' }]，则在提供值时，您需要将其包装到一个额外的数组中。这最好用一个例子来说明。

type Person = { name: string };
const test = base.extend<{ persons: Person[] }>({
  // Declare the option, default value is an empty array.
  persons: [[], { option: true }],
});

// Option value is an array of persons.
const actualPersons = [{ name: 'Alice' }, { name: 'Bob' }];
test.use({
  // CORRECT: Wrap the value into an array and pass the scope.
  persons: [actualPersons, { scope: 'test' }],
});

test.use({
  // WRONG: passing an array value directly will not work.
  persons: actualPersons,
});

执行顺序​

每个 fixture 都有一个 setup 和 teardown 阶段，由 fixture 中的 await use() 调用分隔。Setup 在测试/钩子使用 fixture 之前执行，而 teardown 在测试/钩子不再使用 fixture 时执行。

Fixture 遵循以下规则来确定执行顺序

  • 当 fixture A 依赖于 fixture B 时：B 始终在 A 之前设置，并在 A 之后拆除。
  • 非自动 fixture 是延迟执行的，仅当测试/钩子需要它们时才执行。
  • 测试作用域的 fixture 在每个测试之后拆除，而 worker 作用域的 fixture 仅在执行测试的 worker 进程关闭时拆除。

考虑以下示例

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

const test = base.extend<{
  testFixture: string,
  autoTestFixture: string,
  unusedFixture: string,
}, {
  workerFixture: string,
  autoWorkerFixture: string,
}>({
  workerFixture: [async ({ browser }) => {
    // workerFixture setup...
    await use('workerFixture');
    // workerFixture teardown...
  }, { scope: 'worker' }],

  autoWorkerFixture: [async ({ browser }) => {
    // autoWorkerFixture setup...
    await use('autoWorkerFixture');
    // autoWorkerFixture teardown...
  }, { scope: 'worker', auto: true }],

  testFixture: [async ({ page, workerFixture }) => {
    // testFixture setup...
    await use('testFixture');
    // testFixture teardown...
  }, { scope: 'test' }],

  autoTestFixture: [async () => {
    // autoTestFixture setup...
    await use('autoTestFixture');
    // autoTestFixture teardown...
  }, { scope: 'test', auto: true }],

  unusedFixture: [async ({ page }) => {
    // unusedFixture setup...
    await use('unusedFixture');
    // unusedFixture teardown...
  }, { scope: 'test' }],
});

test.beforeAll(async () => { /* ... */ });
test.beforeEach(async ({ page }) => { /* ... */ });
test('first test', async ({ page }) => { /* ... */ });
test('second test', async ({ testFixture }) => { /* ... */ });
test.afterEach(async () => { /* ... */ });
test.afterAll(async () => { /* ... */ });

通常，如果所有测试都通过且没有抛出错误，则执行顺序如下。

  • worker setup 和 beforeAll 部分
    • browser setup，因为它被 autoWorkerFixture 需要。
    • autoWorkerFixture setup，因为自动 worker fixture 始终在任何其他内容之前设置。
    • beforeAll 运行。
  • first test 部分
    • autoTestFixture setup，因为自动测试 fixture 始终在测试和 beforeEach 钩子之前设置。
    • page setup，因为它在 beforeEach 钩子中是必需的。
    • beforeEach 运行。
    • first test 运行。
    • afterEach 运行。
    • page teardown，因为它是测试作用域的 fixture，应该在测试完成后拆除。
    • autoTestFixture teardown，因为它是测试作用域的 fixture，应该在测试完成后拆除。
  • second test 部分
    • autoTestFixture setup，因为自动测试 fixture 始终在测试和 beforeEach 钩子之前设置。
    • page setup，因为它在 beforeEach 钩子中是必需的。
    • beforeEach 运行。
    • workerFixture setup，因为它被 testFixture 需要，而 testFixture 又被 second test 需要。
    • testFixture setup，因为它被 second test 需要。
    • second test 运行。
    • afterEach 运行。
    • testFixture teardown，因为它是测试作用域的 fixture，应该在测试完成后拆除。
    • page teardown，因为它是测试作用域的 fixture，应该在测试完成后拆除。
    • autoTestFixture teardown，因为它是测试作用域的 fixture，应该在测试完成后拆除。
  • afterAll 和 worker teardown 部分
    • afterAll 运行。
    • workerFixture teardown，因为它是 worker 作用域的 fixture，应该在最后拆除一次。
    • autoWorkerFixture teardown，因为它是 worker 作用域的 fixture，应该在最后拆除一次。
    • browser teardown，因为它是 worker 作用域的 fixture，应该在最后拆除一次。

一些观察

  • page 和 autoTestFixture 被设置为测试作用域的 fixture，并在每个测试中 setup 和 teardown。
  • unusedFixture 永远不会被 setup，因为它没有被任何测试/钩子使用。
  • testFixture 依赖于 workerFixture 并触发其 setup。
  • workerFixture 在第二个测试之前延迟 setup，但在 worker 关闭期间拆除一次，作为 worker 作用域的 fixture。
  • autoWorkerFixture 为 beforeAll 钩子设置，但 autoTestFixture 没有设置。

从多个模块组合自定义 fixture​

您可以合并来自多个文件或模块的测试 fixture

fixtures.ts
import { mergeTests } from '@playwright/test';
import { test as dbTest } from 'database-test-utils';
import { test as a11yTest } from 'a11y-test-utils';

export const test = mergeTests(dbTest, a11yTest);
test.spec.ts
import { test } from './fixtures';

test('passes', async ({ database, page, a11y }) => {
  // use database and a11y fixtures.
});

Box fixture​

通常，自定义 fixture 在 UI 模式、Trace Viewer 和各种测试报告中报告为单独的步骤。它们也会出现在测试运行器的错误消息中。对于经常使用的 fixture，这可能意味着很多噪音。您可以通过“boxing”来阻止 fixture 步骤在 UI 中显示。

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

export const test = base.extend({
  helperFixture: [async ({}, use, testInfo) => {
    // ...
  }, { box: true }],
});

这对于非有趣的辅助 fixture 很有用。例如，一个 自动 fixture，用于设置一些通用数据，可以安全地从测试报告中隐藏。

自定义 fixture 标题​

您可以为 fixture 提供自定义标题，而不是通常的 fixture 名称，该标题将显示在测试报告和错误消息中。

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

export const test = base.extend({
  innerFixture: [async ({}, use, testInfo) => {
    // ...
  }, { title: 'my fixture' }],
});

添加全局 beforeEach/afterEach 钩子​

test.beforeEach() 和 test.afterEach() 钩子在同一文件和同一 test.describe() 代码块（如果有）中声明的每个测试之前/之后运行。如果您想声明全局运行的每个测试之前/之后的钩子，您可以像这样将它们声明为自动 fixture

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

export const test = base.extend<{ forEachTest: void }>({
  forEachTest: [async ({ page }, use) => {
    // This code runs before every test.
    await page.goto('https://127.0.0.1:8000');
    await use();
    // This code runs after every test.
    console.log('Last URL:', page.url());
  }, { auto: true }],  // automatically starts for every test.
});

然后将 fixture 导入到您的所有测试中

mytest.spec.ts
import { test } from './fixtures';
import { expect } from '@playwright/test';

test('basic', async ({ page }) => {
  expect(page).toHaveURL('https://127.0.0.1:8000');
  await page.goto('https://playwright.net.cn');
});

添加全局 beforeAll/afterAll 钩子​

test.beforeAll() 和 test.afterAll() 钩子在同一文件和同一 test.describe() 代码块（如果有）中声明的所有测试之前/之后运行，每个 worker 进程一次。如果您想声明在每个文件中所有测试之前/之后运行的钩子，您可以将它们声明为具有 scope: 'worker' 的自动 fixture，如下所示

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

export const test = base.extend<{}, { forEachWorker: void }>({
  forEachWorker: [async ({}, use) => {
    // This code runs before all the tests in the worker process.
    console.log(`Starting test worker ${test.info().workerIndex}`);
    await use();
    // This code runs after all the tests in the worker process.
    console.log(`Stopping test worker ${test.info().workerIndex}`);
  }, { scope: 'worker', auto: true }],  // automatically starts for every worker.
});

然后将 fixture 导入到您的所有测试中

mytest.spec.ts
import { test } from './fixtures';
import { expect } from '@playwright/test';

test('basic', async ({ }) => {
  // ...
});

请注意，fixture 仍将每个 worker 进程 运行一次，但您无需在每个文件中重新声明它们。