Skip to main content

Playwright 测试

Playwright Test 提供了 test 函数来声明测试和 expect 函数来编写断言。

Playwright Test provides a test function to declare tests and expect function to write assertions.

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

test('basic test', async ({ page }) => {
await page.goto('https://playwright.nodejs.cn/');
const name = await page.innerText('.navbar__title');
expect(name).toBe('Playwright');
});

方法

Methods

test

Added in: v1.10 test.test

宣布进行测试。

Declares a test.

用法

Usage

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

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

参数

Arguments

测试标题。

Test title.

测试带有一个或两个参数的函数:带有夹具和可选 TestInfo 的对象。

Test function that takes one or two arguments: an object with fixtures and optional TestInfo.


test.afterAll(hookFunction)

Added in: v1.10 test.test.afterAll(hookFunction)

声明一个 afterAll 钩子,在所有测试后每个工作线程执行一次。

Declares an afterAll hook that is executed once per worker after all tests.

用法

Usage

test.afterAll(async () => {
console.log('Done with tests');
// ...
});

参数

Arguments

带有一个或两个参数的钩子函数:带有工作线程夹具和可选 TestInfo 的对象。

Hook function that takes one or two arguments: an object with worker fixtures and optional TestInfo.

细节

Details

在测试文件范围内调用时,在文件中的所有测试之后运行。当在 test.describe() 组内调用时,在组中的所有测试之后运行。如果添加了多个 afterAll 钩子,它们将按照注册的顺序运行。

When called in the scope of a test file, runs after all tests in the file. When called inside a test.describe() group, runs after all tests in the group. If multiple afterAll hooks are added, they will run in the order of their registration.

请注意,工作进程在测试失败时重新启动,并且 afterAll 钩子在新工作进程中再次运行。了解有关 工作线程和失败 的更多信息。

Note that worker process is restarted on test failures, and afterAll hook runs again in the new worker. Learn more about workers and failures.

Playwright 将继续运行所有适用的钩子,即使其中一些钩子失败。

Playwright will continue running all applicable hooks even if some of them have failed.


test.afterAll(title, hookFunction)

Added in: v1.38 test.test.afterAll(title, hookFunction)

声明一个带有标题的 afterAll 钩子,在所有测试后每个工作线程执行一次。

Declares an afterAll hook with a title that is executed once per worker after all tests.

用法

Usage

test.afterAll('Teardown', async () => {
console.log('Done with tests');
// ...
});

参数

Arguments

钩子标题。

Hook title.

带有一个或两个参数的钩子函数:带有工作线程夹具和可选 TestInfo 的对象。

Hook function that takes one or two arguments: an object with worker fixtures and optional TestInfo.

细节

Details

参见 test.afterAll()

See test.afterAll().


test.afterEach(hookFunction)

Added in: v1.10 test.test.afterEach(hookFunction)

声明每次测试后执行的 afterEach 钩子。

Declares an afterEach hook that is executed after each test.

用法

Usage

example.spec.ts
import { test, expect } from '@playwright/test';

test.afterEach(async ({ page }, testInfo) => {
console.log(`Finished ${testInfo.title} with status ${testInfo.status}`);

if (testInfo.status !== testInfo.expectedStatus)
console.log(`Did not run as expected, ended up at ${page.url()}`);
});

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

参数

Arguments

带有一个或两个参数的钩子函数:带有夹具和可选 TestInfo 的对象。

Hook function that takes one or two arguments: an object with fixtures and optional TestInfo.

细节

Details

在测试文件范围内调用时,在文件中的每个测试之后运行。当在 test.describe() 组内调用时,在组中的每个测试之后运行。如果添加了多个 afterEach 钩子,它们将按照注册的顺序运行。

When called in the scope of a test file, runs after each test in the file. When called inside a test.describe() group, runs after each test in the group. If multiple afterEach hooks are added, they will run in the order of their registration.

你可以访问与测试函数本身相同的所有 夹具,以及提供大量有用信息的 TestInfo 对象。例如,你可以检查测试是否成功或失败。

You can access all the same Fixtures as the test function itself, and also the TestInfo object that gives a lot of useful information. For example, you can check whether the test succeeded or failed.

Playwright 将继续运行所有适用的钩子,即使其中一些钩子失败。

Playwright will continue running all applicable hooks even if some of them have failed.


test.afterEach(title, hookFunction)

Added in: v1.38 test.test.afterEach(title, hookFunction)

声明一个带有标题的 afterEach 钩子,该钩子在每次测试后执行。

Declares an afterEach hook with a title that is executed after each test.

用法

Usage

example.spec.ts
import { test, expect } from '@playwright/test';

test.afterEach('Status check', async ({ page }, testInfo) => {
console.log(`Finished ${testInfo.title} with status ${testInfo.status}`);

if (testInfo.status !== testInfo.expectedStatus)
console.log(`Did not run as expected, ended up at ${page.url()}`);
});

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

参数

Arguments

钩子标题。

Hook title.

带有一个或两个参数的钩子函数:带有夹具和可选 TestInfo 的对象。

Hook function that takes one or two arguments: an object with fixtures and optional TestInfo.

细节

Details

参见 test.afterEach()

See test.afterEach().


test.beforeAll(hookFunction)

Added in: v1.10 test.test.beforeAll(hookFunction)

声明一个 beforeAll 钩子,在所有测试之前每个工作进程执行一次。

Declares a beforeAll hook that is executed once per worker process before all tests.

用法

Usage

example.spec.ts
import { test, expect } from '@playwright/test';

test.beforeAll(async () => {
console.log('Before tests');
});

test.afterAll(async () => {
console.log('After tests');
});

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

参数

Arguments

带有一个或两个参数的钩子函数:带有工作线程夹具和可选 TestInfo 的对象。

Hook function that takes one or two arguments: an object with worker fixtures and optional TestInfo.

细节

Details

在测试文件范围内调用时,在文件中的所有测试之前运行。当在 test.describe() 组内调用时,在组中的所有测试之前运行。如果添加了多个 beforeAll 钩子,它们将按照注册的顺序运行。

When called in the scope of a test file, runs before all tests in the file. When called inside a test.describe() group, runs before all tests in the group. If multiple beforeAll hooks are added, they will run in the order of their registration.

请注意,工作进程在测试失败时重新启动,并且 beforeAll 钩子在新工作进程中再次运行。了解有关 工作线程和失败 的更多信息。

Note that worker process is restarted on test failures, and beforeAll hook runs again in the new worker. Learn more about workers and failures.

Playwright 将继续运行所有适用的钩子,即使其中一些钩子失败。

Playwright will continue running all applicable hooks even if some of them have failed.

你可以使用 test.afterAll() 拆除 beforeAll 中设置的任何资源。

You can use test.afterAll() to teardown any resources set up in beforeAll.


test.beforeAll(title, hookFunction)

Added in: v1.38 test.test.beforeAll(title, hookFunction)

声明一个带有标题的 beforeAll 钩子,该钩子在所有测试之前每个工作进程执行一次。

Declares a beforeAll hook with a title that is executed once per worker process before all tests.

用法

Usage

example.spec.ts
import { test, expect } from '@playwright/test';

test.beforeAll('Setup', async () => {
console.log('Before tests');
});

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

参数

Arguments

钩子标题。

Hook title.

带有一个或两个参数的钩子函数:带有工作线程夹具和可选 TestInfo 的对象。

Hook function that takes one or two arguments: an object with worker fixtures and optional TestInfo.

细节

Details

参见 test.beforeAll()

See test.beforeAll().


test.beforeEach(hookFunction)

Added in: v1.10 test.test.beforeEach(hookFunction)

声明在每次测试之前执行的 beforeEach 钩子。

Declares a beforeEach hook that is executed before each test.

用法

Usage

example.spec.ts
import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }, testInfo) => {
console.log(`Running ${testInfo.title}`);
await page.goto('https://my.start.url/');
});

test('my test', async ({ page }) => {
expect(page.url()).toBe('https://my.start.url/');
});

参数

Arguments

带有一个或两个参数的钩子函数:带有夹具和可选 TestInfo 的对象。

Hook function that takes one or two arguments: an object with fixtures and optional TestInfo.

细节

Details

在测试文件范围内调用时,在文件中的每个测试之前运行。当在 test.describe() 组内调用时,在组中的每个测试之前运行。如果添加了多个 beforeEach 钩子,它们将按照注册的顺序运行。

When called in the scope of a test file, runs before each test in the file. When called inside a test.describe() group, runs before each test in the group. If multiple beforeEach hooks are added, they will run in the order of their registration.

你可以访问与测试函数本身相同的所有 夹具,以及提供大量有用信息的 TestInfo 对象。例如,你可以在开始测试之前导航页面。

You can access all the same Fixtures as the test function itself, and also the TestInfo object that gives a lot of useful information. For example, you can navigate the page before starting the test.

Playwright 将继续运行所有适用的钩子,即使其中一些钩子失败。

Playwright will continue running all applicable hooks even if some of them have failed.

你可以使用 test.afterEach() 拆除 beforeEach 中设置的任何资源。

You can use test.afterEach() to teardown any resources set up in beforeEach.


test.beforeEach(title, hookFunction)

Added in: v1.38 test.test.beforeEach(title, hookFunction)

声明一个带有标题的 beforeEach 钩子,该钩子在每次测试之前执行。

Declares a beforeEach hook with a title that is executed before each test.

用法

Usage

example.spec.ts
import { test, expect } from '@playwright/test';

test.beforeEach('Open start URL', async ({ page }, testInfo) => {
console.log(`Running ${testInfo.title}`);
await page.goto('https://my.start.url/');
});

test('my test', async ({ page }) => {
expect(page.url()).toBe('https://my.start.url/');
});

参数

Arguments

钩子标题。

Hook title.

带有一个或两个参数的钩子函数:带有夹具和可选 TestInfo 的对象。

Hook function that takes one or two arguments: an object with fixtures and optional TestInfo.

细节

Details

参见 test.beforeEach()

See test.beforeEach().


test.describe(title, callback)

Added in: v1.10 test.test.describe(title, callback)

声明一组测试。

Declares a group of tests.

用法

Usage

test.describe('two tests', () => {
test('one', async ({ page }) => {
// ...
});

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

参数

Arguments

组标题。

Group title.

调用 test.describe() 时立即运行的回调。此回调中添加的任何测试都将属于该组。

A callback that is run immediately when calling test.describe(). Any tests added in this callback will belong to the group.


test.describe(callback)

Added in: v1.24 test.test.describe(callback)

声明一组匿名测试。这样可以方便地为一组测试提供 test.use() 的通用选项。

Declares an anonymous group of tests. This is convenient to give a group of tests a common option with test.use().

用法

Usage

test.describe(() => {
test.use({ colorScheme: 'dark' });

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

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

参数

Arguments

调用 test.describe() 时立即运行的回调。此回调中添加的任何测试都将属于该组。

A callback that is run immediately when calling test.describe(). Any tests added in this callback will belong to the group.


test.describe.configure

Added in: v1.10 test.test.describe.configure

配置封闭范围。可以在顶层或在描述内执行。配置适用于整个范围,无论它是在测试声明之前还是之后运行。

Configures the enclosing scope. Can be executed either on the top level or inside a describe. Configuration applies to the entire scope, regardless of whether it run before or after the test declaration.

了解有关执行模式 此处 的更多信息。

Learn more about the execution modes here.

用法

Usage

  • 并行运行测试。

    Running tests in parallel.

    // Run all the tests in the file concurrently using parallel workers.
    test.describe.configure({ mode: 'parallel' });
    test('runs in parallel 1', async ({ page }) => {});
    test('runs in parallel 2', async ({ page }) => {});
  • 连续运行测试,从头开始重试。

    Running tests serially, retrying from the start.

    note

    Running serially is not recommended. It is usually better to make your tests isolated, so they can be run independently.

    // Annotate tests as inter-dependent.
    test.describe.configure({ mode: 'serial' });
    test('runs first', async ({ page }) => {});
    test('runs second', async ({ page }) => {});
  • 为每个测试配置重试和超时。

    Configuring retries and timeout for each test.

    // Each test in the file will be retried twice and have a timeout of 20 seconds.
    test.describe.configure({ retries: 2, timeout: 20_000 });
    test('runs first', async ({ page }) => {});
    test('runs second', async ({ page }) => {});
  • 并行运行多个描述,但每个描述内的测试按顺序进行。

    Run multiple describes in parallel, but tests inside each describe in order.

    test.describe.configure({ mode: 'parallel' });

    test.describe('A, runs in parallel with B', () => {
    test.describe.configure({ mode: 'default' });
    test('in order A1', async ({ page }) => {});
    test('in order A2', async ({ page }) => {});
    });

    test.describe('B, runs in parallel with A', () => {
    test.describe.configure({ mode: 'default' });
    test('in order B1', async ({ page }) => {});
    test('in order B2', async ({ page }) => {});
    });

参数

Arguments

  • mode "default"|"parallel"|"serial"(可选)#

    mode "default"|"parallel"|"serial" (optional)#

    执行模式。了解有关执行模式 此处 的更多信息。

    Execution mode. Learn more about the execution modes here.

    • retries number (optional) Added in: v1.28#

每次测试的重试次数。

The number of retries for each test.

  • timeout number (optional) Added in: v1.28#

每个测试的超时时间(以毫秒为单位)。覆盖 testProject.timeouttestConfig.timeout

Timeout for each test in milliseconds. Overrides testProject.timeout and testConfig.timeout.


test.describe.fixme

Added in: v1.25 test.test.describe.fixme

test.describe() 类似地声明一个测试组。该组中的测试被标记为 "fixme" 并且不会被执行。

Declares a test group similarly to test.describe(). Tests in this group are marked as "fixme" and will not be executed.

用法

Usage

test.describe.fixme('broken tests', () => {
test('example', async ({ page }) => {
// This test will not run
});
});

参数

Arguments

组标题。

Group title.

调用 test.describe.fixme() 时立即运行的回调。此回调中添加的任何测试都将属于该组,并且不会运行。

A callback that is run immediately when calling test.describe.fixme(). Any tests added in this callback will belong to the group, and will not be run.


test.describe.only

Added in: v1.10 test.test.describe.only

声明一组重点测试。如果有一些重点测试或套件,那么所有这些测试或套件都将运行,但不会运行其他测试。

Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing else.

用法

Usage

test.describe.only('focused group', () => {
test('in the focused group', async ({ page }) => {
// This test will run
});
});
test('not in the focused group', async ({ page }) => {
// This test will not run
});

参数

Arguments

组标题。

Group title.

调用 test.describe.only() 时立即运行的回调。此回调中添加的任何测试都将属于该组。

A callback that is run immediately when calling test.describe.only(). Any tests added in this callback will belong to the group.


test.describe.skip

Added in: v1.10 test.test.describe.skip

声明一个跳过的测试组,类似于 test.describe()。跳过组中的测试永远不会运行。

Declares a skipped test group, similarly to test.describe(). Tests in the skipped group are never run.

用法

Usage

test.describe.skip('skipped group', () => {
test('example', async ({ page }) => {
// This test will not run
});
});

参数

Arguments

组标题。

Group title.

调用 test.describe.skip() 时立即运行的回调。此回调中添加的任何测试都将属于该组,并且不会运行。

A callback that is run immediately when calling test.describe.skip(). Any tests added in this callback will belong to the group, and will not be run.


test.extend

Added in: v1.10 test.test.extend

通过定义可在测试中使用的夹具和/或选项来扩展 test 对象。

Extends the test object by defining fixtures and/or options that can be used in the tests.

用法

Usage

首先定义一个夹具和/或一个选项。

First define a fixture and/or an option.

import { test as base } from '@playwright/test';
import { TodoPage } from './todo-page';

export type Options = { defaultItem: string };

// Extend basic test by providing a "defaultItem" option and a "todoPage" fixture.
export const test = base.extend<Options & { todoPage: TodoPage }>({
// Define an option and provide a default value.
// We can later override it in the config.
defaultItem: ['Do stuff', { option: true }],

// Define a fixture. Note that it can use built-in fixture "page"
// and a new option "defaultItem".
todoPage: async ({ page, defaultItem }, use) => {
const todoPage = new TodoPage(page);
await todoPage.goto();
await todoPage.addToDo(defaultItem);
await use(todoPage);
await todoPage.removeAll();
},
});

然后在测试中使用夹具。

Then use the fixture in the test.

example.spec.ts
import { test } from './my-test';

test('test 1', async ({ todoPage }) => {
await todoPage.addToDo('my todo');
// ...
});

配置配置文件中的选项。

Configure the option in config file.

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

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

了解有关 fixtures参数化测试 的更多信息。

Learn more about fixtures and parametrizing tests.

参数

Arguments

包含装置和/或选项的对象。了解有关 赛程格式 的更多信息。

An object containing fixtures and/or options. Learn more about fixtures format.

返回

Returns


test.fail()

Added in: v1.10 test.test.fail()

无条件地将测试标记为 "应该失败"。Playwright Test 运行此测试并确保它确实失败。这对于文档目的很有用,可以确认某些功能在修复之前已损坏。

Unconditionally marks a test as "should fail". Playwright Test runs this test and ensures that it is actually failing. This is useful for documentation purposes to acknowledge that some functionality is broken until it is fixed.

用法

Usage

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

test('not yet ready', async ({ page }) => {
test.fail();
// ...
});

test.fail(condition)

Added in: v1.10 test.test.fail(condition)

有条件地将测试标记为 "应该失败",并带有可选描述。

Conditionally mark a test as "should fail" with an optional description.

用法

Usage

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

test('fail in WebKit', async ({ page, browserName }) => {
test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet');
// ...
});

参数

Arguments

当条件为 true 时,测试标记为 "应该失败"。

Test is marked as "should fail" when the condition is true.

将反映在测试报告中的可选描述。

Optional description that will be reflected in a test report.


test.fail(callback)

Added in: v1.10 test.test.fail(callback)

有条件地将文件或 test.describe() 组中的所有测试标记为 "应该失败"。

Conditionally mark all tests in a file or test.describe() group as "should fail".

用法

Usage

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

test.fail(({ browserName }) => browserName === 'webkit');

test('fail in WebKit 1', async ({ page }) => {
// ...
});
test('fail in WebKit 2', async ({ page }) => {
// ...
});

参数

Arguments

一个函数,根据测试夹具返回是否标记为 "应该失败"。当返回值为 true 时,一个或多个测试被标记为 "应该失败"。

A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as "should fail" when the return value is true.

将反映在测试报告中的可选描述。

Optional description that will be reflected in a test report.


test.fixme(title, testFunction)

Added in: v1.10 test.test.fixme(title, testFunction)

声明要修复的测试,类似于 test()。将不会运行此测试。

Declares a test to be fixed, similarly to test(). This test will not be run.

用法

Usage

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

test.fixme('test to be fixed', async ({ page }) => {
// ...
});

参数

Arguments

测试标题。

Test title.

测试带有一个或两个参数的函数:带有夹具和可选 TestInfo 的对象。

Test function that takes one or two arguments: an object with fixtures and optional TestInfo.


test.fixme()

Added in: v1.10 test.test.fixme()

将测试标记为 "fixme",旨在修复它。当你调用 test.fixme() 时,测试立即中止。

Mark a test as "fixme", with the intention to fix it. Test is immediately aborted when you call test.fixme().

用法

Usage

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

test('test to be fixed', async ({ page }) => {
test.fixme();
// ...
});

将文件或 test.describe() 组中的所有测试标记为 "fixme"。

Mark all tests in a file or test.describe() group as "fixme".

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

test.fixme();

test('test to be fixed 1', async ({ page }) => {
// ...
});
test('test to be fixed 2', async ({ page }) => {
// ...
});

test.fixme(condition)

Added in: v1.10 test.test.fixme(condition)

有条件地将测试标记为 "fixme",并带有可选描述。

Conditionally mark a test as "fixme" with an optional description.

用法

Usage

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

test('broken in WebKit', async ({ page, browserName }) => {
test.fixme(browserName === 'webkit', 'This feature is not implemented on Mac yet');
// ...
});

参数

Arguments

当条件为 true 时,测试标记为 "fixme"。

Test is marked as "fixme" when the condition is true.

将反映在测试报告中的可选描述。

Optional description that will be reflected in a test report.


test.fixme(callback)

Added in: v1.10 test.test.fixme(callback)

有条件地将文件或 test.describe() 组中的所有测试标记为 "fixme"。

Conditionally mark all tests in a file or test.describe() group as "fixme".

用法

Usage

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

test.fixme(({ browserName }) => browserName === 'webkit');

test('broken in WebKit 1', async ({ page }) => {
// ...
});
test('broken in WebKit 2', async ({ page }) => {
// ...
});

参数

Arguments

一个函数,根据测试夹具返回是否标记为 "fixme"。当返回值为 true 时,一个或多个测试被标记为 "fixme"。

A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme" when the return value is true.

将反映在测试报告中的可选描述。

Optional description that will be reflected in a test report.


test.info

Added in: v1.10 test.test.info

返回有关当前正在运行的测试的信息。该方法只能在测试执行期间调用,否则会抛出异常。

Returns information about the currently running test. This method can only be called during the test execution, otherwise it throws.

用法

Usage

test('example test', async ({ page }) => {
// ...
await test.info().attach('screenshot', {
body: await page.screenshot(),
contentType: 'image/png',
});
});

返回

Returns


test.only

Added in: v1.10 test.test.only

宣布进行重点测试。如果有一些重点测试或套件,那么所有这些测试或套件都将运行,但不会运行其他测试。

Declares a focused test. If there are some focused tests or suites, all of them will be run but nothing else.

用法

Usage

test.only('focus this test', async ({ page }) => {
// Run only focused tests in the entire project.
});

参数

Arguments

测试标题。

Test title.

测试带有一个或两个参数的函数:带有夹具和可选 TestInfo 的对象。

Test function that takes one or two arguments: an object with fixtures and optional TestInfo.


test.setTimeout

Added in: v1.10 test.test.setTimeout

更改测试的超时。零意味着没有超时。了解有关 各种超时 的更多信息。

Changes the timeout for the test. Zero means no timeout. Learn more about various timeouts.

当前正在运行的测试的超时可通过 testInfo.timeout 获得。

Timeout for the currently running test is available through testInfo.timeout.

用法

Usage

  • 更改测试超时。

    Changing test timeout.

    test('very slow test', async ({ page }) => {
    test.setTimeout(120000);
    // ...
    });
  • 更改慢速 beforeEachafterEach 钩子的超时。请注意,这会影响与 beforeEach/afterEach 钩子共享的测试超时。

    Changing timeout from a slow beforeEach or afterEach hook. Note that this affects the test timeout that is shared with beforeEach/afterEach hooks.

    test.beforeEach(async ({ page }, testInfo) => {
    // Extend timeout for all tests running this hook by 30 seconds.
    test.setTimeout(testInfo.timeout + 30000);
    });
  • 更改 beforeAllafterAll 钩子的超时。请注意,这会影响钩子的超时,而不是测试超时。

    Changing timeout for a beforeAll or afterAll hook. Note this affects the hook's timeout, not the test timeout.

    test.beforeAll(async () => {
    // Set timeout for this hook.
    test.setTimeout(60000);
    });
  • 更改 test.describe() 组中所有测试的超时。

    Changing timeout for all tests in a test.describe() group.

    test.describe('group', () => {
    // Applies to all tests in this group.
    test.describe.configure({ timeout: 60000 });

    test('test one', async () => { /* ... */ });
    test('test two', async () => { /* ... */ });
    test('test three', async () => { /* ... */ });
    });

参数

Arguments

超时(以毫秒为单位)。

Timeout in milliseconds.


test.skip(title, testFunction)

Added in: v1.10 test.test.skip(title, testFunction)

声明跳过测试,类似于 test()。跳过的测试永远不会运行。

Declares a skipped test, similarly to test(). Skipped test is never run.

用法

Usage

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

test.skip('broken test', async ({ page }) => {
// ...
});

参数

Arguments

测试标题。

Test title.

测试带有一个或两个参数的函数:带有夹具和可选 TestInfo 的对象。

Test function that takes one or two arguments: an object with fixtures and optional TestInfo.


test.skip()

Added in: v1.10 test.test.skip()

无条件跳过测试。当你调用 test.skip() 时,测试立即中止。

Unconditionally skip a test. Test is immediately aborted when you call test.skip().

用法

Usage

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

test('skipped test', async ({ page }) => {
test.skip();
// ...
});

无条件跳过文件或 test.describe() 组中的所有测试:

Unconditionally skip all tests in a file or test.describe() group:

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

test.skip();

test('skipped test 1', async ({ page }) => {
// ...
});
test('skipped test 2', async ({ page }) => {
// ...
});

test.skip(condition)

Added in: v1.10 test.test.skip(condition)

有条件地跳过带有可选描述的测试。

Conditionally skip a test with an optional description.

用法

Usage

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

test('skip in WebKit', async ({ page, browserName }) => {
test.skip(browserName === 'webkit', 'This feature is not implemented for Mac');
// ...
});

test.beforeEach() 钩子跳过:

Skip from test.beforeEach() hook:

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

test.beforeEach(async ({ page }) => {
test.skip(process.env.APP_VERSION === 'v1', 'There are no settings in v1');
await page.goto('/settings');
});

参数

Arguments

跳过条件。当条件为 true 时跳过测试。

A skip condition. Test is skipped when the condition is true.

将反映在测试报告中的可选描述。

Optional description that will be reflected in a test report.


test.skip(callback)

Added in: v1.10 test.test.skip(callback)

有条件地跳过文件或 test.describe() 组中的所有测试。

Conditionally skips all tests in a file or test.describe() group.

用法

Usage

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

test.skip(({ browserName }) => browserName === 'webkit');

test('skip in WebKit 1', async ({ page }) => {
// ...
});
test('skip in WebKit 2', async ({ page }) => {
// ...
});

参数

Arguments

根据测试装置返回是否跳过的函数。当返回值为 true 时,将跳过一个或多个测试。

A function that returns whether to skip, based on test fixtures. Test or tests are skipped when the return value is true.

将反映在测试报告中的可选描述。

Optional description that will be reflected in a test report.


test.slow()

Added in: v1.10 test.test.slow()

无条件地将测试标记为 "slow"。慢速测试将给予默认超时的三倍。

Unconditionally marks a test as "slow". Slow test will be given triple the default timeout.

用法

Usage

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

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

细节

Details

test.slow() 不能用于 beforeAllafterAll 钩子。请改用 test.setTimeout()

test.slow() cannot be used in a beforeAll or afterAll hook. Use test.setTimeout() instead.


test.slow(condition)

Added in: v1.10 test.test.slow(condition)

有条件地将测试标记为 "slow",并带有可选描述。慢速测试将给予默认超时的三倍。

Conditionally mark a test as "slow" with an optional description. Slow test will be given triple the default timeout.

用法

Usage

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

test('slow in WebKit', async ({ page, browserName }) => {
test.slow(browserName === 'webkit', 'This feature is slow on Mac');
// ...
});

参数

Arguments

当条件为 true 时,测试标记为 "slow"。

Test is marked as "slow" when the condition is true.

将反映在测试报告中的可选描述。

Optional description that will be reflected in a test report.


test.slow(callback)

Added in: v1.10 test.test.slow(callback)

有条件地将文件或 test.describe() 组中的所有测试标记为 "slow"。慢速测试的超时时间将是默认超时的三倍。

Conditionally mark all tests in a file or test.describe() group as "slow". Slow tests will be given triple the default timeout.

用法

Usage

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

test.slow(({ browserName }) => browserName === 'webkit');

test('slow in WebKit 1', async ({ page }) => {
// ...
});
test('fail in WebKit 2', async ({ page }) => {
// ...
});

参数

Arguments

一个函数,根据测试夹具返回是否标记为 "slow"。当返回值为 true 时,一个或多个测试被标记为 "slow"。

A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when the return value is true.

将反映在测试报告中的可选描述。

Optional description that will be reflected in a test report.


test.step

Added in: v1.10 test.test.step

声明报告中显示的测试步骤。

Declares a test step that is shown in the report.

用法

Usage

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

test('test', async ({ page }) => {
await test.step('Log in', async () => {
// ...
});

await test.step('Outer step', async () => {
// ...
// You can nest steps inside each other.
await test.step('Inner step', async () => {
// ...
});
});
});

参数

Arguments

步骤名称。

Step name.

步体。

Step body.

是否在报告中对步骤进行框选。默认为 false。当步骤被装箱时,从步骤内部抛出的错误指向步骤调用站点。请参阅下面的更多细节。

Whether to box the step in the report. Defaults to false. When the step is boxed, errors thrown from the step internals point to the step call site. See below for more details.

返回

Returns

细节

Details

该方法返回步骤回调返回的值。

The method returns the value returned by the step callback.

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

test('test', async ({ page }) => {
const user = await test.step('Log in', async () => {
// ...
return 'john';
});
expect(user).toBe('john');
});

装饰器

Decorator

你可以使用 TypeScript 方法装饰器将方法转变为步骤。对修饰方法的每次调用都将显示为报告中的一个步骤。

You can use TypeScript method decorators to turn a method into a step. Each call to the decorated method will show up as a step in the report.

function step(target: Function, context: ClassMethodDecoratorContext) {
return function replacementMethod(...args: any) {
const name = this.constructor.name + '.' + (context.name as string);
return test.step(name, async () => {
return await target.call(this, ...args);
});
};
}

class LoginPage {
constructor(readonly page: Page) {}

@step
async login() {
const account = { username: 'Alice', password: 's3cr3t' };
await this.page.getByLabel('Username or email address').fill(account.username);
await this.page.getByLabel('Password').fill(account.password);
await this.page.getByRole('button', { name: 'Sign in' }).click();
await expect(this.page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
}
}

test('example', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.login();
});

装入盒中

Boxing

当步骤内的某些内容失败时,你通常会看到错误指向失败的确切操作。例如,考虑以下登录步骤:

When something inside a step fails, you would usually see the error pointing to the exact action that failed. For example, consider the following login step:

async function login(page) {
await test.step('login', async () => {
const account = { username: 'Alice', password: 's3cr3t' };
await page.getByLabel('Username or email address').fill(account.username);
await page.getByLabel('Password').fill(account.password);
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
});
}

test('example', async ({ page }) => {
await page.goto('https://github.com/login');
await login(page);
});
Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
... error details omitted ...

8 | await page.getByRole('button', { name: 'Sign in' }).click();
> 9 | await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
| ^
10 | });

正如我们在上面看到的,测试可能会失败,并出现指向步骤内部的错误。如果你希望错误高亮 "login" 步骤而不是其内部,请使用 box 选项。装箱步骤内的错误指向步骤调用站点。

As we see above, the test may fail with an error pointing inside the step. If you would like the error to highlight the "login" step instead of its internals, use the box option. An error inside a boxed step points to the step call site.

async function login(page) {
await test.step('login', async () => {
// ...
}, { box: true }); // Note the "box" option here.
}
Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
... error details omitted ...

14 | await page.goto('https://github.com/login');
> 15 | await login(page);
| ^
16 | });

你还可以为盒装步骤创建 TypeScript 装饰器,类似于上面的常规步骤装饰器:

You can also create a TypeScript decorator for a boxed step, similar to a regular step decorator above:

function boxedStep(target: Function, context: ClassMethodDecoratorContext) {
return function replacementMethod(...args: any) {
const name = this.constructor.name + '.' + (context.name as string);
return test.step(name, async () => {
return await target.call(this, ...args);
}, { box: true }); // Note the "box" option here.
};
}

class LoginPage {
constructor(readonly page: Page) {}

@boxedStep
async login() {
// ....
}
}

test('example', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.login(); // <-- Error will be reported on this line.
});

test.use

Added in: v1.10 test.test.use

指定要在单个测试文件或 test.describe() 组中使用的选项或装置。最有用的是设置一个选项,例如设置 locale 来配置 context 夹具。

Specifies options or fixtures to use in a single test file or a test.describe() group. Most useful to set an option, for example set locale to configure context fixture.

用法

Usage

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

test.use({ locale: 'en-US' });

test('test with locale', async ({ page }) => {
// Default context and page have locale as specified
});

参数

Arguments

具有本地选项的对象。

An object with local options.

细节

Details

test.use 可以在全局作用域内调用,也可以在 test.describe 内部调用。在 beforeEachbeforeAll 内调用是错误的。

test.use can be called either in the global scope or inside test.describe. It is an error to call it within beforeEach or beforeAll.

还可以通过提供函数来覆盖夹具。

It is also possible to override a fixture by providing a function.

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

test.use({
locale: async ({}, use) => {
// Read locale from some configuration file.
const locale = await fs.promises.readFile('test-locale', 'utf-8');
await use(locale);
},
});

test('test with locale', async ({ page }) => {
// Default context and page have locale as specified
});

属性

Properties

test.expect

Added in: v1.10 test.test.expect

expect 函数可用于创建测试断言。了解有关 测试断言 的更多信息。

expect function can be used to create test assertions. Read more about test assertions.

用法

Usage

test('example', async ({ page }) => {
await test.expect(page).toHaveTitle('Title');
});

类型

Type


已弃用

Deprecated

test.describe.parallel

Added in: v1.10 test.test.describe.parallel
劝阻

请参阅 test.describe.configure() 了解配置执行模式的首选方法。

See test.describe.configure() for the preferred way of configuring the execution mode.

声明一组可以并行运行的测试。默认情况下,单个测试文件中的测试依次运行,但使用 test.describe.parallel() 允许它们并行运行。

Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after another, but using test.describe.parallel() allows them to run in parallel.

用法

Usage

test.describe.parallel('group', () => {
test('runs in parallel 1', async ({ page }) => {});
test('runs in parallel 2', async ({ page }) => {});
});

请注意,并行测试在单独的进程中执行,不能共享任何状态或全局变量。每个并行测试都会执行所有相关的钩子。

Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of the parallel tests executes all relevant hooks.

参数

Arguments

组标题。

Group title.

调用 test.describe.parallel() 时立即运行的回调。此回调中添加的任何测试都将属于该组。

A callback that is run immediately when calling test.describe.parallel(). Any tests added in this callback will belong to the group.


test.describe.parallel.only

Added in: v1.10 test.test.describe.parallel.only
劝阻

请参阅 test.describe.configure() 了解配置执行模式的首选方法。

See test.describe.configure() for the preferred way of configuring the execution mode.

声明一组可以并行运行的重点测试。这与 test.describe.parallel() 类似,但以群体为重点。如果有一些重点测试或套件,那么所有这些测试或套件都将运行,但不会运行其他测试。

Declares a focused group of tests that could be run in parallel. This is similar to test.describe.parallel(), but focuses the group. If there are some focused tests or suites, all of them will be run but nothing else.

用法

Usage

test.describe.parallel.only('group', () => {
test('runs in parallel 1', async ({ page }) => {});
test('runs in parallel 2', async ({ page }) => {});
});

参数

Arguments

组标题。

Group title.

调用 test.describe.parallel.only() 时立即运行的回调。此回调中添加的任何测试都将属于该组。

A callback that is run immediately when calling test.describe.parallel.only(). Any tests added in this callback will belong to the group.


test.describe.serial

Added in: v1.10 test.test.describe.serial
劝阻

请参阅 test.describe.configure() 了解配置执行模式的首选方法。

See test.describe.configure() for the preferred way of configuring the execution mode.

声明一组应始终串行运行的测试。如果其中一项测试失败,则跳过所有后续测试。一组中的所有测试都会一起重试。

Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together.

注意

不建议使用串口。通常最好将测试隔离起来,这样它们就可以独立运行。

Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently.

用法

Usage

test.describe.serial('group', () => {
test('runs first', async ({ page }) => {});
test('runs second', async ({ page }) => {});
});

参数

Arguments

组标题。

Group title.

调用 test.describe.serial() 时立即运行的回调。此回调中添加的任何测试都将属于该组。

A callback that is run immediately when calling test.describe.serial(). Any tests added in this callback will belong to the group.


test.describe.serial.only

Added in: v1.10 test.test.describe.serial.only
劝阻

请参阅 test.describe.configure() 了解配置执行模式的首选方法。

See test.describe.configure() for the preferred way of configuring the execution mode.

声明一组应始终连续运行的重点测试。如果其中一项测试失败,则跳过所有后续测试。一组中的所有测试都会一起重试。如果有一些重点测试或套件,那么所有这些测试或套件都将运行,但不会运行其他测试。

Declares a focused group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together. If there are some focused tests or suites, all of them will be run but nothing else.

注意

不建议使用串口。通常最好将测试隔离起来,这样它们就可以独立运行。

Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently.

用法

Usage

test.describe.serial.only('group', () => {
test('runs first', async ({ page }) => {
});
test('runs second', async ({ page }) => {
});
});

参数

Arguments

组标题。

Group title.

调用 test.describe.serial.only() 时立即运行的回调。此回调中添加的任何测试都将属于该组。

A callback that is run immediately when calling test.describe.serial.only(). Any tests added in this callback will belong to the group.