Playwright Test
Playwright Test 提供了一个 test
函数来声明测试,以及一个 expect
函数来编写断言。
import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {
await page.goto('https://playwright.net.cn/');
const name = await page.innerText('.navbar__title');
expect(name).toBe('Playwright');
});
方法
test
新增于: v1.10声明一个测试。
test(title, body)
test(title, details, body)
用法
import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {
await page.goto('https://playwright.net.cn/');
// ...
});
标签
您可以通过提供额外的测试详情来标记测试。或者,您可以将标签包含在测试标题中。请注意,每个标签必须以 @
符号开头。
import { test, expect } from '@playwright/test';
test('basic test', {
tag: '@smoke',
}, async ({ page }) => {
await page.goto('https://playwright.net.cn/');
// ...
});
test('another test @smoke', async ({ page }) => {
await page.goto('https://playwright.net.cn/');
// ...
});
测试标签会显示在测试报告中,并通过 TestCase.tags
属性提供给自定义报告器。
您还可以在测试执行期间按标签过滤测试
- 在命令行中;
- 在配置文件中使用testConfig.grep和testProject.grep;
了解更多关于标记的信息。
注解
您可以通过提供额外的测试详情来注释测试。
import { test, expect } from '@playwright/test';
test('basic test', {
annotation: {
type: 'issue',
description: 'https://github.com/microsoft/playwright/issues/23180',
},
}, async ({ page }) => {
await page.goto('https://playwright.net.cn/');
// ...
});
测试注释显示在测试报告中,并通过 TestCase.annotations
属性提供给自定义报告器。
您还可以在运行时通过操作 testInfo.annotations 添加注释。
了解更多关于测试注释的信息。
参数
-
测试标题。
-
附加测试详情。
-
测试主体,接受一个或两个参数:一个包含夹具的对象和可选的 TestInfo。
test.afterAll
新增于: v1.10声明一个 afterAll
钩子,它在所有测试完成后,每个 worker 执行一次。
在测试文件范围内调用时,在文件中所有测试之后运行。在 test.describe() 组内调用时,在组内所有测试之后运行。
用法
test.afterAll(async () => {
console.log('Done with tests');
// ...
});
或者,您可以声明一个 带标题的 钩子。
test.afterAll('Teardown', async () => {
console.log('Done with tests');
// ...
});
参数
详情
当添加多个 afterAll
钩子时,它们将按照注册的顺序运行。
请注意,在测试失败时会重启 worker 进程,并且 afterAll
钩子会在新的 worker 中再次运行。了解更多关于worker 和失败的信息。
Playwright 将继续运行所有适用的钩子,即使其中一些已失败。
test.afterAll(hookFunction)
test.afterAll(title, hookFunction)
test.afterEach
新增于: v1.10声明一个 afterEach
钩子,它在每个测试之后执行。
在测试文件范围内调用时,在文件中每个测试之后运行。在 test.describe() 组内调用时,在组内每个测试之后运行。
您可以访问所有与测试主体相同的 Fixtures,以及提供许多有用信息的 TestInfo 对象。例如,您可以检查测试是成功还是失败。
test.afterEach(hookFunction)
test.afterEach(title, hookFunction)
用法
import { test, expect } from '@playwright/test';
test.afterEach(async ({ page }) => {
console.log(`Finished ${test.info().title} with status ${test.info().status}`);
if (test.info().status !== test.info().expectedStatus)
console.log(`Did not run as expected, ended up at ${page.url()}`);
});
test('my test', async ({ page }) => {
// ...
});
或者,您可以声明一个 带标题的 钩子。
test.afterEach('Status check', async ({ page }) => {
if (test.info().status !== test.info().expectedStatus)
console.log(`Did not run as expected, ended up at ${page.url()}`);
});
参数
详情
当添加多个 afterEach
钩子时,它们将按照注册的顺序运行。
Playwright 将继续运行所有适用的钩子,即使其中一些已失败。
test.beforeAll
新增于: v1.10声明一个 beforeAll
钩子,它在所有测试之前,每个 worker 进程执行一次。
在测试文件范围内调用时,在文件中所有测试之前运行。在 test.describe() 组内调用时,在组内所有测试之前运行。
您可以使用 test.afterAll() 来拆卸在 beforeAll
中设置的任何资源。
test.beforeAll(hookFunction)
test.beforeAll(title, hookFunction)
用法
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 }) => {
// ...
});
或者,您可以声明一个 带标题的 钩子。
test.beforeAll('Setup', async () => {
console.log('Before tests');
});
参数
详情
当添加多个 beforeAll
钩子时,它们将按照注册的顺序运行。
请注意,在测试失败时会重启 worker 进程,并且 beforeAll
钩子会在新的 worker 中再次运行。了解更多关于worker 和失败的信息。
Playwright 将继续运行所有适用的钩子,即使其中一些已失败。
test.beforeEach
新增于: v1.10声明一个 beforeEach
钩子,它在每个测试之前执行。
在测试文件范围内调用时,在文件中每个测试之前运行。在 test.describe() 组内调用时,在组内每个测试之前运行。
您可以访问所有与测试主体相同的 Fixtures,以及提供许多有用信息的 TestInfo 对象。例如,您可以在测试开始前导航页面。
您可以使用 test.afterEach() 来拆卸在 beforeEach
中设置的任何资源。
test.beforeEach(hookFunction)
test.beforeEach(title, hookFunction)
用法
import { test, expect } from '@playwright/test';
test.beforeEach(async ({ page }) => {
console.log(`Running ${test.info().title}`);
await page.goto('https://my.start.url/');
});
test('my test', async ({ page }) => {
expect(page.url()).toBe('https://my.start.url/');
});
或者,您可以声明一个 带标题的 钩子。
test.beforeEach('Open start URL', async ({ page }) => {
console.log(`Running ${test.info().title}`);
await page.goto('https://my.start.url/');
});
参数
详情
当添加多个 beforeEach
钩子时,它们将按照注册的顺序运行。
Playwright 将继续运行所有适用的钩子,即使其中一些已失败。
test.describe
新增于: v1.10声明一个测试组。
test.describe(title, callback)
test.describe(callback)
test.describe(title, details, callback)
用法
您可以声明一个带有标题的测试组。该标题将作为每个测试标题的一部分显示在测试报告中。
test.describe('two tests', () => {
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
});
匿名组
您也可以声明一个没有标题的测试组。这方便为一组测试使用 test.use() 提供一个通用选项。
test.describe(() => {
test.use({ colorScheme: 'dark' });
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
});
标签
您可以通过提供额外的详细信息来标记组中的所有测试。请注意,每个标签必须以 @
符号开头。
import { test, expect } from '@playwright/test';
test.describe('two tagged tests', {
tag: '@smoke',
}, () => {
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
});
了解更多关于标记的信息。
注解
您可以通过提供附加细节来标注组中的所有测试。
import { test, expect } from '@playwright/test';
test.describe('two annotated tests', {
annotation: {
type: 'issue',
description: 'https://github.com/microsoft/playwright/issues/23180',
},
}, () => {
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
});
了解更多关于测试注释的信息。
参数
-
组标题。
-
组中所有测试的附加详细信息。
-
调用 test.describe() 时立即运行的回调。在此回调中声明的任何测试都将属于该组。
test.describe.configure
新增于: v1.10配置封闭范围。可以在顶层或 describe 内部执行。配置适用于整个范围,无论它是在测试声明之前还是之后运行。
在此处了解有关执行模式的更多信息:这里。
用法
-
并行运行测试。
// 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 }) => {}); -
按顺序运行测试,独立重试每个失败的测试。
这是默认模式。显式设置它以覆盖使用
fullyParallel
的项目配置会很有用。// Tests in this file run in order. Retries, if any, run independently.
test.describe.configure({ mode: 'default' });
test('runs first', async ({ page }) => {});
test('runs second', async ({ page }) => {}); -
串行运行测试,从头开始重试。如果其中一个串行测试失败,则所有后续测试都将跳过。
注意不建议串行运行。通常最好让您的测试独立,以便它们可以独立运行。
// Annotate tests as inter-dependent.
test.describe.configure({ mode: 'serial' });
test('runs first', async ({ page }) => {});
test('runs second', async ({ page }) => {}); -
为每个测试配置重试次数和超时时间。
// 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 }) => {}); -
并行运行多个 describe,但每个 describe 内部的测试按顺序运行。
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 }) => {});
});
参数
options
对象 (可选)-
mode
"default" | "parallel" | "serial" (可选)#执行模式。在此处了解有关执行模式的更多信息:这里。
-
每个测试的重试次数。
-
每个测试的超时时间(毫秒)。覆盖 testProject.timeout 和 testConfig.timeout。
-
test.describe.fixme
新增于: v1.25声明一个测试组,类似于 test.describe()。此组中的测试标记为“fixme”,并且不会执行。
test.describe.fixme(title, callback)
test.describe.fixme(callback)
test.describe.fixme(title, details, callback)
用法
test.describe.fixme('broken tests that should be fixed', () => {
test('example', async ({ page }) => {
// This test will not run
});
});
您也可以省略标题。
test.describe.fixme(() => {
// ...
});
参数
-
组标题。
-
请参阅 test.describe() 了解详细描述。
-
调用 test.describe.fixme() 时立即运行的回调。在此回调中添加的任何测试都将属于该组,并且不会运行。
test.describe.only
新增于: v1.10声明一个焦点测试组。如果存在一些焦点测试或套件,则只运行这些测试或套件,其他都不运行。
test.describe.only(title, callback)
test.describe.only(callback)
test.describe.only(title, details, callback)
用法
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
});
您也可以省略标题。
test.describe.only(() => {
// ...
});
参数
-
组标题。
-
请参阅 test.describe() 了解详细描述。
-
调用 test.describe.only() 时立即运行的回调。在此回调中添加的任何测试都将属于该组。
test.describe.skip
新增于: v1.10声明一个跳过的测试组,类似于 test.describe()。跳过的组中的测试永远不会运行。
test.describe.skip(title, callback)
test.describe.skip(title)
test.describe.skip(title, details, callback)
用法
test.describe.skip('skipped group', () => {
test('example', async ({ page }) => {
// This test will not run
});
});
您也可以省略标题。
test.describe.skip(() => {
// ...
});
参数
-
组标题。
-
请参阅 test.describe() 了解详细描述。
-
调用 test.describe.skip() 时立即运行的回调。在此回调中添加的任何测试都将属于该组,并且不会运行。
test.extend
新增于: v1.10通过定义可在测试中使用的夹具和/或选项来扩展 test
对象。
用法
首先定义一个夹具和/或一个选项。
- TypeScript
- JavaScript
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();
},
});
const base = require('@playwright/test');
const { TodoPage } = require('./todo-page');
// Extend basic test by providing a "defaultItem" option and a "todoPage" fixture.
exports.test = base.test.extend({
// 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();
},
});
然后,在测试中使用该夹具。
import { test } from './my-test';
test('test 1', async ({ todoPage }) => {
await todoPage.addToDo('my todo');
// ...
});
在配置文件中配置选项。
- TypeScript
- JavaScript
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!' },
},
]
});
// @ts-check
module.exports = defineConfig({
projects: [
{
name: 'shopping',
use: { defaultItem: 'Buy milk' },
},
{
name: 'wellbeing',
use: { defaultItem: 'Exercise!' },
},
]
});
参数
返回
test.fail
新增于: v1.10将测试标记为“应失败”。Playwright 运行此测试并确保它确实失败。这对于文档目的很有用,可以承认某些功能在修复之前是损坏的。
声明一个“失败”测试
test.fail(title, body)
test.fail(title, details, body)
在运行时将测试注释为“失败”
test.fail(condition, description)
test.fail(callback, description)
test.fail()
用法
您可以将测试声明为失败,以便 Playwright 确保它确实失败。
import { test, expect } from '@playwright/test';
test.fail('not yet ready', async ({ page }) => {
// ...
});
如果您的测试在某些配置中失败,但并非全部,您可以在测试主体内根据某些条件将测试标记为失败。在这种情况下,我们建议传递 description
参数。
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');
// ...
});
您可以使用单个 test.fail(callback, description)
调用,根据某个条件将文件或 test.describe() 组中的所有测试标记为“应失败”。
import { test, expect } from '@playwright/test';
test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet');
test('fail in WebKit 1', async ({ page }) => {
// ...
});
test('fail in WebKit 2', async ({ page }) => {
// ...
});
您也可以在测试主体内调用 test.fail()
不带参数,以始终将测试标记为失败。我们建议改用 test.fail(title, body)
声明失败测试。
import { test, expect } from '@playwright/test';
test('less readable', async ({ page }) => {
test.fail();
// ...
});
参数
-
测试标题。
-
请参阅 test() 了解测试详情描述。
-
body
函数(Fixtures, TestInfo) (可选)新增于: v1.42#测试主体,接受一个或两个参数:一个包含夹具的对象和可选的 TestInfo。
-
当条件为
true
时,测试标记为“应失败”。 -
callback
函数(Fixtures):布尔值 (可选)#一个函数,根据测试夹具返回是否标记为“应失败”。当返回值为
true
时,测试或多个测试标记为“应失败”。 -
可选描述,将反映在测试报告中。
test.fail.only
新增于: v1.49您可以使用 test.fail.only
来专注于预期失败的特定测试。这在调试失败测试或处理特定问题时特别有用。
声明一个聚焦的“失败”测试
test.fail.only(title, body)
test.fail.only(title, details, body)
用法
您可以声明一个聚焦的失败测试,这样 Playwright 只会运行此测试并确保它确实失败。
import { test, expect } from '@playwright/test';
test.fail.only('focused failing test', async ({ page }) => {
// This test is expected to fail
});
test('not in the focused group', async ({ page }) => {
// This test will not run
});
参数
-
测试标题。
-
请参阅 test.describe() 了解测试详情描述。
-
body
函数(Fixtures, TestInfo) (可选)#测试主体,接受一个或两个参数:一个包含夹具的对象和可选的 TestInfo。
test.fixme
新增于: v1.10将测试标记为“待修复”,意图修复它。Playwright 不会运行超过 test.fixme()
调用的测试。
声明一个“待修复”测试
test.fixme(title, body)
test.fixme(title, details, body)
在运行时将测试注释为“待修复”
test.fixme(condition, description)
test.fixme(callback, description)
test.fixme()
用法
您可以声明一个待修复的测试,Playwright 将不会运行它。
import { test, expect } from '@playwright/test';
test.fixme('to be fixed', async ({ page }) => {
// ...
});
如果您的测试在某些配置中需要修复,但并非全部,您可以在测试主体内根据某些条件将测试标记为“fixme”。在这种情况下,我们建议传递 description
参数。Playwright 将运行测试,但在 test.fixme
调用后立即中止它。
import { test, expect } from '@playwright/test';
test('to be fixed in Safari', async ({ page, browserName }) => {
test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason');
// ...
});
您可以使用单个 test.fixme(callback, description)
调用,根据某个条件将文件或 test.describe() 组中的所有测试标记为“fixme”。
import { test, expect } from '@playwright/test';
test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue');
test('to be fixed in Safari 1', async ({ page }) => {
// ...
});
test('to be fixed in Safari 2', async ({ page }) => {
// ...
});
您也可以在测试主体内不带参数地调用 test.fixme()
来始终将测试标记为失败。我们建议改用 test.fixme(title, body)
。
import { test, expect } from '@playwright/test';
test('less readable', async ({ page }) => {
test.fixme();
// ...
});
参数
-
测试标题。
-
请参阅 test() 了解测试详情描述。
-
body
函数(Fixtures, TestInfo) (可选)#测试主体,接受一个或两个参数:一个包含夹具的对象和可选的 TestInfo。
-
当条件为
true
时,测试标记为“fixme”。 -
callback
函数(Fixtures):布尔值 (可选)#一个函数,根据测试夹具返回是否标记为“fixme”。当返回值为
true
时,测试或多个测试标记为“fixme”。 -
可选描述,将反映在测试报告中。
test.info
新增于: v1.10返回有关当前运行测试的信息。此方法只能在测试执行期间调用,否则会抛出异常。
用法
test('example test', async ({ page }) => {
// ...
await test.info().attach('screenshot', {
body: await page.screenshot(),
contentType: 'image/png',
});
});
返回
test.only
新增于: v1.10声明一个焦点测试。如果存在一些焦点测试或套件,则只运行这些测试或套件,其他都不运行。
test.only(title, body)
test.only(title, details, body)
用法
test.only('focus this test', async ({ page }) => {
// Run only focused tests in the entire project.
});
参数
test.setTimeout
新增于: v1.10更改测试的超时时间。零表示没有超时。了解更多关于各种超时的信息。
当前运行测试的超时时间可通过 testInfo.timeout 获得。
用法
-
更改测试超时。
test('very slow test', async ({ page }) => {
test.setTimeout(120000);
// ...
}); -
从一个缓慢的
beforeEach
钩子更改超时。请注意,这会影响与beforeEach
钩子共享的测试超时。test.beforeEach(async ({ page }, testInfo) => {
// Extend timeout for all tests running this hook by 30 seconds.
test.setTimeout(testInfo.timeout + 30000);
}); -
更改
beforeAll
或afterAll
钩子的超时。请注意,这会影响钩子的超时,而不是测试超时。test.beforeAll(async () => {
// Set timeout for this hook.
test.setTimeout(60000);
}); -
更改 test.describe() 组中所有测试的超时。
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 () => { /* ... */ });
});
参数
test.skip
新增于: v1.10跳过一个测试。Playwright 不会运行超过 test.skip()
调用的测试。
跳过的测试不应该被运行。如果您打算修复测试,请改用 test.fixme()。
声明一个跳过的测试
test.skip(title, body)
test.skip(title, details, body)
在运行时跳过测试
test.skip(condition, description)
test.skip(callback, description)
test.skip()
用法
您可以声明一个跳过的测试,Playwright 将不会运行它。
import { test, expect } from '@playwright/test';
test.skip('never run', async ({ page }) => {
// ...
});
如果您的测试在某些配置中应该跳过,但并非全部,您可以在测试主体内根据某个条件跳过测试。在这种情况下,我们建议传递 description
参数。Playwright 将运行测试,但在 test.skip
调用后立即中止它。
import { test, expect } from '@playwright/test';
test('Safari-only test', async ({ page, browserName }) => {
test.skip(browserName !== 'webkit', 'This feature is Safari-only');
// ...
});
您可以使用单个 test.skip(callback, description)
调用,根据某个条件跳过文件或 test.describe() 组中的所有测试。
import { test, expect } from '@playwright/test';
test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only');
test('Safari-only test 1', async ({ page }) => {
// ...
});
test('Safari-only test 2', async ({ page }) => {
// ...
});
您也可以在测试主体内不带参数地调用 test.skip()
来始终跳过测试。但是,我们建议改用 test.skip(title, body)
。
import { test, expect } from '@playwright/test';
test('less readable', async ({ page }) => {
test.skip();
// ...
});
参数
-
测试标题。
-
请参阅 test() 了解测试详情描述。
-
body
函数(Fixtures, TestInfo) (可选)#测试主体,接受一个或两个参数:一个包含夹具的对象和可选的 TestInfo。
-
当条件为
true
时,测试标记为“已跳过”。 -
callback
函数(Fixtures):布尔值 (可选)#一个函数,根据测试夹具返回是否标记为“已跳过”。当返回值为
true
时,测试或多个测试标记为“已跳过”。 -
可选描述,将反映在测试报告中。
test.slow
新增于: v1.10将测试标记为“慢速”。慢速测试的默认超时时间将增加三倍。
请注意,test.slow() 不能在 beforeAll
或 afterAll
钩子中使用。请改用 test.setTimeout()。
test.slow()
test.slow(condition, description)
test.slow(callback, description)
用法
您可以通过在测试主体内调用 test.slow()
将测试标记为慢速。
import { test, expect } from '@playwright/test';
test('slow test', async ({ page }) => {
test.slow();
// ...
});
如果您的测试在某些配置中很慢,但并非全部,您可以根据条件将其标记为慢速。在这种情况下,我们建议传递 description
参数。
import { test, expect } from '@playwright/test';
test('slow in Safari', async ({ page, browserName }) => {
test.slow(browserName === 'webkit', 'This feature is slow in Safari');
// ...
});
您可以通过传递回调,根据某个条件将文件或 test.describe() 组中的所有测试标记为“慢速”。
import { test, expect } from '@playwright/test';
test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari');
test('slow in Safari 1', async ({ page }) => {
// ...
});
test('fail in Safari 2', async ({ page }) => {
// ...
});
参数
-
当条件为
true
时,测试标记为“慢速”。 -
callback
函数(Fixtures):布尔值 (可选)#一个函数,根据测试夹具返回是否标记为“慢速”。当返回值为
true
时,测试或多个测试标记为“慢速”。 -
可选描述,将反映在测试报告中。
test.step
新增于: v1.10声明报告中显示的测试步骤。
用法
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 () => {
// ...
});
});
});
参数
-
步骤名称。
-
body
函数(TestStepInfo):Promise<对象>#步骤主体。
-
options
对象 (可选)-
是否在报告中将该步骤框起来。默认为
false
。当该步骤被框起来时,从该步骤内部抛出的错误将指向该步骤的调用位置。详见下文。 -
为步骤指定在测试报告和追踪查看器中显示的自定义位置。默认情况下,显示 test.step() 调用的位置。
-
允许步骤完成的最大时间(毫秒)。如果步骤未能在指定的超时时间内完成,test.step() 方法将抛出 TimeoutError。默认为
0
(无超时)。
-
返回
详情
此方法返回步骤回调返回的值。
import { test, expect } from '@playwright/test';
test('test', async ({ page }) => {
const user = await test.step('Log in', async () => {
// ...
return 'john';
});
expect(user).toBe('john');
});
装饰器
您可以使用 TypeScript 方法装饰器将方法转换为步骤。每次调用装饰方法都将显示为报告中的一个步骤。
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();
});
装箱
当步骤内部出现问题时,通常会看到错误指向失败的确切操作。例如,考虑以下登录步骤
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 | });
正如我们上面看到的,测试可能会因指向步骤内部的错误而失败。如果您希望错误突出显示“登录”步骤而不是其内部,请使用 box
选项。盒装步骤内的错误指向步骤调用位置。
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 装饰器,类似于上面的常规步骤装饰器
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.step.skip
新增于: v1.50将测试步骤标记为“跳过”以暂时禁用其执行,这对于当前失败并计划短期修复的步骤很有用。Playwright 不会运行该步骤。另请参阅 testStepInfo.skip()。
我们建议使用 testStepInfo.skip()。
用法
您可以声明一个跳过的步骤,Playwright 将不会运行它。
import { test, expect } from '@playwright/test';
test('my test', async ({ page }) => {
// ...
await test.step.skip('not yet ready', async () => {
// ...
});
});
参数
-
步骤名称。
-
步骤主体。
-
options
对象 (可选)
返回
test.use
新增于: v1.10指定要在单个测试文件或 test.describe() 组中使用的选项或夹具。最有用的是设置选项,例如设置 locale
来配置 context
夹具。
用法
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
});
参数
-
options
TestOptions#包含本地选项的对象。
详情
test.use
可以在全局范围或 test.describe
内部调用。在 beforeEach
或 beforeAll
中调用它将导致错误。
也可以通过提供一个函数来覆盖夹具。
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
});
属性
test.expect
新增于: v1.10expect
函数可用于创建测试断言。阅读更多关于测试断言的信息。
用法
test('example', async ({ page }) => {
await test.expect(page).toHaveTitle('Title');
});
类型
已弃用
test.describe.parallel
新增于: v1.10请参阅 test.describe.configure() 以了解配置执行模式的首选方式。
声明一组可以并行运行的测试。默认情况下,单个测试文件中的测试一个接一个地运行,但使用 test.describe.parallel() 允许它们并行运行。
test.describe.parallel(title, callback)
test.describe.parallel(callback)
test.describe.parallel(title, details, callback)
用法
test.describe.parallel('group', () => {
test('runs in parallel 1', async ({ page }) => {});
test('runs in parallel 2', async ({ page }) => {});
});
请注意,并行测试在单独的进程中执行,不能共享任何状态或全局变量。每个并行测试都执行所有相关的钩子。
您也可以省略标题。
test.describe.parallel(() => {
// ...
});
参数
-
组标题。
-
请参阅 test.describe() 了解详细描述。
-
调用 test.describe.parallel() 时立即运行的回调。在此回调中添加的任何测试都将属于该组。
test.describe.parallel.only
新增于: v1.10请参阅 test.describe.configure() 以了解配置执行模式的首选方式。
声明一个可以并行运行的焦点测试组。这类似于 test.describe.parallel(),但它聚焦于该组。如果存在一些焦点测试或套件,则只运行这些测试或套件,其他都不运行。
test.describe.parallel.only(title, callback)
test.describe.parallel.only(callback)
test.describe.parallel.only(title, details, callback)
用法
test.describe.parallel.only('group', () => {
test('runs in parallel 1', async ({ page }) => {});
test('runs in parallel 2', async ({ page }) => {});
});
您也可以省略标题。
test.describe.parallel.only(() => {
// ...
});
参数
-
组标题。
-
请参阅 test.describe() 了解详细描述。
-
调用 test.describe.parallel.only() 时立即运行的回调。在此回调中添加的任何测试都将属于该组。
test.describe.serial
新增于: v1.10请参阅 test.describe.configure() 以了解配置执行模式的首选方式。
声明一组应始终串行运行的测试。如果其中一个测试失败,则所有后续测试都将跳过。组中的所有测试都将一起重试。
不建议串行运行。通常最好让您的测试独立,以便它们可以独立运行。
test.describe.serial(title, callback)
test.describe.serial(title)
test.describe.serial(title, details, callback)
用法
test.describe.serial('group', () => {
test('runs first', async ({ page }) => {});
test('runs second', async ({ page }) => {});
});
您也可以省略标题。
test.describe.serial(() => {
// ...
});
参数
-
组标题。
-
请参阅 test.describe() 了解详细描述。
-
调用 test.describe.serial() 时立即运行的回调。在此回调中添加的任何测试都将属于该组。
test.describe.serial.only
新增于: v1.10请参阅 test.describe.configure() 以了解配置执行模式的首选方式。
声明一个应始终串行运行的焦点测试组。如果其中一个测试失败,则所有后续测试都将被跳过。组中的所有测试都将一起重试。如果存在一些焦点测试或套件,则只运行这些测试或套件,其他都不运行。
不建议串行运行。通常最好让您的测试独立,以便它们可以独立运行。
test.describe.serial.only(title, callback)
test.describe.serial.only(title)
test.describe.serial.only(title, details, callback)
用法
test.describe.serial.only('group', () => {
test('runs first', async ({ page }) => {
});
test('runs second', async ({ page }) => {
});
});
您也可以省略标题。
test.describe.serial.only(() => {
// ...
});
参数