playwright-validation

Playwright 验证技能

此技能将指导你验证 UI 更改，并确保 Playwright E2E 测试覆盖全面。

使用时机

• 完成 UI 功能开发后
• 为 UI 更改创建 PR 前
• 审查与 UI 相关的分支时
• 验证现有 Playwright 测试是否覆盖所有场景

工作流

阶段 1：审查分支更改

1. 确定与 main 相比发生更改的文件：

   git diff main --stat
   git diff main --name-only | grep -E "\.(tsx?|less|css|scss)$"
   

2. 重点关注 UI 组件更改：

   git diff main -- "openmetadata-ui/src/main/resources/ui/src/components/**" --stat
   

3. 检查是否已有 Playwright 测试：

   git diff main --name-only | grep -E "playwright.*\.spec\.ts$"
   

4. 阅读已更改的组件文件，了解 UI 修改内容

阶段 2：审查现有 Playwright 测试

1. 定位相关测试文件：

   • 检查 playwright/e2e/Pages/ 中的页面级测试
   • 检查 playwright/e2e/Features/ 中的功能专属测试
   • 使用 Glob/Grep 查找与该功能相关的测试

2. 分析测试覆盖情况：

   • 阅读现有测试文件
   • 确定已覆盖的测试场景
   • 根据 UI 更改记录覆盖方面的遗漏

3. 审查测试工具：

   • 检查 playwright/utils/ 中的辅助函数
   • 检查 playwright/support/ 中的实体类和固定装置

阶段 3：使用 Playwright MCP 进行验证

1. 启动浏览器并导航：

   mcp__playwright__browser_navigate to http://localhost:8585
   

2. 如有需要，进行身份验证：

   • 使用 mcp__playwright__browser_fill_form 登录
   • 默认管理员账号：[email protected] / admin

3. 导航到功能区域：

   • 使用 mcp__playwright__browser_click 进行导航
   • 使用 mcp__playwright__browser_snapshot 检查页面状态

4. 验证 UI 行为：

   • 测试主要用户流程
   • 验证视觉元素（图标、徽章、标签）
   • 检查交互元素（按钮、下拉菜单、表单）
   • 验证状态更改和 API 调用

5. 记录发现：

   • 记录正常运行的内容
   • 找出问题或缺失的功能
   • 列出现有测试未覆盖的场景

阶段 4：添加缺失的测试用例

1. 使用 TodoWrite 创建缺失测试场景的清单

2. 对于每个缺失的测试用例：

   a. 在 beforeAll 中添加必要的测试固定装置：

   • 创建新的实体实例（TableClass、DataProduct 等）
   • 设置所需的关系（域、资产）

   b. 在 afterAll 中添加清理逻辑：

   • 按相反顺序删除已创建的实体

   c. 按照以下模式编写测试：

   test('Descriptive Test Name - What it validates', async ({ page }) => {
     test.setTimeout(300000);
   
     await test.step('Step description', async () => {
       // Test actions and assertions
     });
   
     await test.step('Next step', async () => {
       // More actions and assertions
     });
   });
   

3. 应覆盖的测试模式：

   • 正常流程（预期行为）
   • 边缘情况（空状态、最大值）
   • 错误处理（无效输入、请求失败）
   • 状态转换（操作前后）
   • UI 反馈（加载状态、成功/错误消息）
   • 权限（禁用的按钮、受限的操作）

4. 运行 Playwright lint 检查：

   yarn lint:playwright
   

   每条 playwright/* 和 om-playwright/* 防护规则的严重级别均为 error。整个代码库中的 openmetadata-playwright/* 规则会单独设置严重级别，在相关调用点迁移期间可能为 warn；请查阅手册中的 ESLint Enforcement 表格里的严重级别列，不要想当然。

常用测试工具

导航

import { sidebarClick } from '../../utils/sidebar';
import { redirectToHomePage } from '../../utils/common';
import { selectDataProduct, selectDomain } from '../../utils/domain';

等待

import { waitForAllLoadersToDisappear } from '../../utils/entity';
await waitForAllLoadersToDisappear(page);
await expect(page.getByTestId('content')).toBeVisible();
// NEVER use: page.waitForLoadState('networkidle') — blocked by ESLint

API 响应

const response = page.waitForResponse('/api/v1/endpoint*');
await someAction();
await response;
expect((await response).status()).toBe(200);

断言

await expect(page.getByTestId('element')).toBeVisible();
await expect(page.getByTestId('element')).toContainText('text');
await expect(page.locator('.class')).not.toBeVisible();

完成前检查清单

• 所有 UI 更改都有相应的测试覆盖
• 测试覆盖正向和负向场景
• 测试验证视觉指示器（图标、徽章、状态）
• 测试验证 API 交互
• yarn lint:playwright 通过且无错误
• 未使用 networkidle、page.pause() 或 test.only()（ESLint 会阻止）
• 测试夹具已正确创建并清理
• 测试超时使用 test.slow()（首选）或 test.setTimeout()

示例：数据契约继承测试

参考以下文件中的全面测试覆盖： playwright/e2e/Pages/DataContractInheritance.spec.ts

此文件展示了：

• 在 beforeAll 中设置多个实体
• 域分配补丁
• 契约创建与验证
• 继承图标验证
• 操作按钮状态验证（禁用／启用）
• API 响应验证（POST 与 PATCH）
• 回退行为测试