本文档概述了将 Jest + Puppeteer 测试迁移到 Playwright 的典型流程。请注意，迁移过程也是重构或重写部分测试的好机会。在开始迁移之前，请先阅读最佳实践指南。

测试的迁移步骤

  1. 在 packages/e2e-tests/specs 中选择要迁移的测试套件，将 .test.js 重命名为 .spec.js，并将其放入 test/e2e/specs 中相同的文件夹结构内。
  2. 从 @wordpress/e2e-test-utils-playwright 引入测试辅助函数：
    js
    const { test, expect } = require( '@wordpress/e2e-test-utils-playwright' );
  3. 将所有出现的 describe、beforeAll、beforeEach、afterEach 和 afterAll 更改为带 test. 前缀的形式。例如，describe 变为 test.describe。
  4. 使用 fixtures API 来获取以前的全局变量（如 page 和 browser）。
  5. 删除所有对 e2e-test-utils 的导入。改为使用 fixtures API 直接获取 admin、editor、pageUtils 和 requestUtils。（但是，admin、editor 和 pageUtils 不允许在 beforeAll 和 afterAll 中使用，请改用 requestUtils 重写它们。）
  6. 如果缺少某个工具函数，且步骤不多，请尝试将这些操作直接内联到测试中。如果你认为它值得实现为测试工具函数，请按照下面的指南操作。
  7. 按照所建议的最佳实践手动迁移测试中的其他细节。请注意，尽管 Playwright 和 Puppeteer 的 API 差异很相似，但仍需要进行一些手动更改。

测试工具函数的迁移步骤

在迁移测试工具函数之前，请慎重考虑是否有必要。Playwright 提供了许多可读性强且功能强大的 API，这使得许多工具函数变得过时。请先尝试在测试中直接内联实现相同的功能。只有在这样做不奏效时，才遵循下面的指南。一些值得在 e2e-test-utils-playwright 包中实现的工具函数示例包括复杂的浏览器 API（如 pageUtils.dragFiles 和 pageUtils.pressKeys）以及设置状态的 API（requestUtils.*）。

e2e-test-utils-playwright 包并非 Jest + Puppeteer 的 e2e-test-utils 包的直接替代品。一些工具函数只是为了简化迁移过程而创建的，并不一定是必需的。

Playwright 的工具函数组织方式与 e2e-test-utils 包中的略有不同。e2e-test-utils-playwright 包包含以下文件夹，工具函数被划分到这些文件夹中：
– admin – 与 WordPress 管理后台或 WordPress 管理后台用户界面相关的工具函数（例如 visitAdminPage）。
– editor – 用于区块编辑器的工具函数（例如 clickBlockToolbarButton）。
– pageUtils – 与浏览器交互的通用工具函数（例如 pressKeys）。
– requestUtils – 用于发起 REST API 请求的工具函数（例如 activatePlugin）。这些工具函数用于测试的 setup（设置）和 teardown（清理）。

  1. 将 e2e-test-utils 中的现有文件复制，并根据工具函数的类型粘贴到 e2e-test-utils-playwright 中的 admin、editor、page 或 request 文件夹中。
  2. 更新工具函数中需要重写的任何部分：
    • page 和 browser 变量在 admin、editor 和 pageUtils 中可通过 this.page 和 this.browser 访问。
    • 同一类中的所有其他工具函数都可通过 this 访问，并绑定到同一实例。你可以移除任何 import 语句，使用 this 来访问它们。
    • 如果你愿意，可以考虑将工具函数更新为使用 TypeScript。
  3. 在 index.ts 中导入新迁移的工具函数，并将其作为实例字段放入 Admin/Editor/PageUtils/RequestUtils 类中。