gutenberg-docs/docs/contributors/code/e2e

title	post_status	comment_status	taxonomy
端到端测试	publish	open	category post_tag gutenberg-docs E2E Code Contributors

端到端测试

本文档旨在为 Gutenberg 项目中如何使用 Playwright 编写端到端（E2E）测试提供指导和最佳实践。

运行测试

# 运行所有可用测试。
npm run test:e2e

# 在 headed 模式下运行。
npm run test:e2e -- --headed

# 使用特定浏览器运行测试（`chromium`、`firefox` 或 `webkit`）。
npm run test:e2e -- --project=webkit --project=firefox

# 运行单个测试文件。
npm run test:e2e -- <path_to_test_file> # 例如：npm run test:e2e -- site-editor/title.spec.js

# 调试模式。
npm run test:e2e -- --debug

如果您在 Linux 环境下开发，目前需要在 headed 模式下测试 Webkit 浏览器。如果您不希望或无法使用 GUI 运行（例如，没有图形界面），请在命令前添加 xvfb-run 以在虚拟环境中运行。

# 运行所有可用测试。
xvfb-run npm run test:e2e

# 仅运行 webkit 测试。
xvfb-run -- npm run test:e2e -- --project=webkit

如果您已经在 VS Code 中编辑，可能会发现 Playwright 扩展 对运行、编写和调试测试很有帮助。

最佳实践

阅读 Playwright 的最佳实践指南。

禁止使用 $，改用 locator

实际上，任何返回 ElementHandle 的 API 都不推荐使用。这包括 $、$$、$eval、$$eval 等。Locator 是更好的 API，可与 Playwright 的断言一起使用。这在页面对象模型中也非常好用，因为定位器是惰性的且不返回 Promise。

使用无障碍选择器

尽可能使用 getByRole 来构建查询。这使我们能够编写无障碍查询，而无需依赖内部实现。

// 选择一个包含无障碍名称 "Hello World" 的按钮（不区分大小写）。
page.getByRole( 'button', { name: 'Hello World' } );

它也可以链式调用以执行复杂查询：

// 在 "Block Library" 区域下选择一个名称为 "Buttons" 的选项。
page.getByRole( 'region', { name: 'Block Library' } )
	.getByRole( 'option', { name: 'Buttons' } )

有关如何使用它们的更多信息，请参阅官方文档。

选择器默认采用严格模式

为鼓励采用更佳的元素查询实践，选择器默认采用严格模式，这意味着当查询返回多个元素时将抛出错误。

内联简单工具辅助函数

大多数工具函数足够简单，可以直接内联在测试中。借助可访问的选择器，现在编写简单工具函数更加容易。对于仅在特定页面使用的工具函数，请改用页面对象模型。否则，只有当操作足够复杂且重复时，才创建工具函数。

优先使用页面对象模型而非工具函数

如上所述，页面对象模型是在特定页面上创建可复用工具函数的首选方法。

使用 POM 的核心原理是将工具函数按命名空间分组，使其更易于发现和使用。实际上，e2e-test-utils-playwright 包中的 PageUtils 也是一个 POM，它避免了全局变量的使用，并且工具函数可以通过 this 相互引用。

用于清除或设置状态的 Restify 操作

在测试前后手动设置状态速度较慢，尤其是在测试间重复多次时。建议通过 API 调用来设置。请使用 requestUtils.rest 和 requestUtils.batchRest 来调用 REST API（如有需要可将其添加到 requestUtils 中）。我们仍应添加手动设置状态的测试，但只需测试一次。

避免使用全局变量

在之前的 E2E 设置中，page 和 browser 是全局变量，这使得处理多个页面或并行测试变得更加困难。

@playwright/test 使用 fixture 将 page、browser 和其他参数注入到测试中。

明确声明断言

我们可以在单个测试中插入任意数量的断言。尽可能进行明确声明是更好的做法。例如，若要在点击按钮前断言其存在，可在执行 locator.click() 前使用 expect( locator ).toBeVisible()。这能使测试流程更顺畅且更易阅读。

常见陷阱

过度使用快照

Cross-browser testing

By default, tests are only run in chromium. You can tag tests to run them in different browsers. Use @browser anywhere in the test title to run it in that browser. Tests will always run in chromium by default, append -chromium to disable testing in chromium. Available browsers are chromium, firefox, and webkit.

test( 'I will run in @firefox and @webkit (and chromium by default)', async ( { page } ) => {
	// ...
} );

test( 'I will only run in @firefox but not -chromium', async ( { page } ) => {
	// ...
} );

test.describe( 'Grouping tests (@webkit, -chromium)', () => {
	test( 'I will only run in webkit', async ( { page } ) => {
		// ...
	} );
} );