woocommerce/packages/js/email-editor/zh-cn/writing-e2e-tests.md

为 WooCommerce 邮件编辑器撰写 E2E 测试

目录

1. 前置条件
2. 测试结构
3. 撰写测试
4. 最佳实践
5. 调试测试

前置条件

1. 环境设置:

   # 从仓库根目录
   nvm use
   pnpm install
   pnpm --filter='@woocommerce/plugin-woocommerce' build
   cd plugins/woocommerce
   pnpm env:start 
   

   或

   # 从任意位置
   pnpm --filter='@woocommerce/plugin-woocommerce' build
   pnpm --filter='@woocommerce/plugin-woocommerce' wp-env start
   

2. 必填依赖项:

   • Node
   • PNPM
   • Docker
   • WordPress 环境 (wp-env)

测试结构

1. 基本测试文件结构

const { test, expect } = require('@playwright/test');
const { ADMIN_STATE_PATH } = require('../../playwright.config');
const { 
    enableEmailEditor,
    disableEmailEditor 
} = require('./helpers/enable-email-editor-feature');
const { 
    accessTheEmailEditor,
    ensureEmailEditorSettingsPanelIsOpened 
} = require('../../utils/email');

test.describe('WooCommerce 邮件编辑器', () => {
    test.use({ storageState: ADMIN_STATE_PATH });

    test.beforeAll(async ({ baseURL }) => {
        await enableEmailEditor(baseURL);
    });

    test.afterAll(async ({ baseURL }) => {
        await disableEmailEditor(baseURL);
    });

    test('你的测试名称', async ({ page }) => {
        // 测试实现
    });
});

2. 测试组织

• 将测试放在 tests/e2e-pw/tests/email-editor/ 中
• 使用描述性的文件名，扩展名为 .spec.js
• 使用 test.describe() 对相关测试进行分组
• 为常见操作使用辅助函数

撰写测试

1. 基本测试结构

test('Can perform specific action', async ({ page }) => {
    // 设置
    await accessTheEmailEditor(page, 'New order');

    // 操作
    await page.getByRole('button', { name: 'Settings' }).click();

    // 断言
    await expect(page.locator('.editor-post-status__toggle'))
        .toContainText('Enabled');
});

2. 常见测试样板

测试邮件编辑访问

test('Can access the email editor', async ({ page }) => {
    await accessTheEmailEditor(page, 'New order');
    await page.getByRole('tab', { name: 'Email' }).click();
    await expect(page.locator('.editor-post-card-panel__title'))
        .toContainText('New order');
});

测试电子邮件设置

test('可以更新电子邮件设置', async ({ page }) => {
    await accessTheEmailEditor(page, 'Customer note');
    await page.getByLabel('Email')
        .getByRole('button', { name: 'Settings' })
        .click();
    await ensureEmailEditorSettingsPanelIsOpened(page);
    
    // 更新设置
    await page.locator('[data-automation-id="email_subject"]')
        .fill('New Subject');
    
    // 保存更改
    await page.getByRole('button', { name: 'Save' }).click();
    
    // 验证更改
    await expect(page.locator('[data-automation-id="email_subject"]'))
        .toContainText('New Subject');
});

注意：如果更新 WC_Email 选项，请记得重置为默认。可以通过以下方式完成：

test.afterAll( async ( { baseURL } ) => {
		await resetWCTransactionalEmail( baseURL, EMAIL_ID );
	} );

最佳实践

1. 测试隔离：

   • 每个测试应保持独立
   • 使用 beforeAll 和 afterAll 进行设置/清理
   • 在测试之间重置状态

2. 选择器：

   • 优先使用基于角色的选择器：getByRole()
   • 使用数据属性：[data-automation-id="..."] 或 page.getByTestId(...)
   • 尽可能避免使用 CSS 选择器

3. 断言：

   • 使用显式断言
   • 等待元素准备就绪
   • 验证状态和内容

4. 错误处理：

   • 添加适当的超时
   • 正确处理异步操作
   • 清理资源

调试测试

1. 在调试模式下运行测试:

   pnpm test:e2e --debug
   

2. 在浏览器窗口可见的情况下运行测试:

   pnpm test:e2e --headed
   

3. 截图:

   await page.screenshot({ path: 'debug-screenshot.png' });
   

4. 查看测试报告:

   pnpm test:e2e --ui
   

5. 运行单个文件测试:

   pnpm test:e2e email-editor-loads.spec
   

6. 运行特定文件夹:

   pnpm test:e2e email-editor
   

实用链接

• UI 报告：http://localhost:9323/
• 本地 E2E 站点：http://localhost:8086/
• VSCode 插件：https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright 指南
• Playwright 入门：https://playwright.dev/docs/writing-tests
  • 定位器指南
  • 断言指南