appbuilder-e2e-testing

App Builder 端到端测试

基于 Playwright 的浏览器端端到端测试，适用于 Adobe App Builder SPA 和 AEM 扩展。此技能可生成 Playwright 配置、测试文件和 CI 工作流，用于浏览器级验证。

模式快速参考

识别用户的意图，然后阅读相关章节以生成定制测试。

用户需求	参考资料	文件
为 ExC Shell SPA 编写端到端测试	references/e2e-testing-patterns.md	assets/playwright.config.ts、assets/e2e-test-template.spec.ts
在浏览器中测试 AEM 扩展	references/aem-extension-testing.md	assets/playwright.config.ts
在 CI 流水线中运行端到端测试	references/ci-integration.md	assets/e2e-ci-workflow.yml

快速流程（适用于明确的请求）

当用户说“添加端到端测试”或“编写 Playwright 测试”，且意图明确时：

1. 扫描项目，查找 web-src/（SPA）或依赖项中的 @adobe/uix-guest（AEM 扩展）
2. 如果尚未安装 Playwright，则安装：npm install -D @playwright/test && npx playwright install chromium
3. 根据 assets/playwright.config.ts 生成 playwright.config.ts
4. 对于 ExC Shell SPA：阅读 references/e2e-testing-patterns.md，生成包含 iframe 导航、Shell 等待和 Spectrum ARIA 选择器的测试
5. 对于 AEM 扩展：阅读 references/aem-extension-testing.md，生成包含 Extension Tester URL、嵌套 iframe 处理和模态框流程的测试
6. 运行测试：npx playwright test
7. 如果用户要求配置 CI，则根据 assets/e2e-ci-workflow.yml 生成 GitHub Actions 工作流

快速参考

• 测试目录： 项目根目录下的 e2e/（与 Jest 的 test/ 分开）
• 配置文件： 项目根目录下的 playwright.config.ts
• 安装命令： npm install -D @playwright/test && npx playwright install chromium（安装 Playwright 和 Chromium 浏览器）
• 运行命令： npx playwright test（无头模式）或 npx playwright test --headed（显示浏览器）
• 调试命令： npx playwright test --debug（逐步执行模式）
• 报告命令： npx playwright show-report（打开 HTML 报告）
• ExC Shell iframe： 通过 page.frameLocator('iframe') 访问 Shell 内的 SPA；确切的选择器因情况而异，参见 references/e2e-testing-patterns.md
• Spectrum 选择器： 使用 ARIA 角色，而非 CSS 类：getByRole('button', { name: 'Save' })、getByRole('grid')、getByRole('textbox')
• 身份验证说明： 完整自动化 ExC Shell 身份验证较为复杂，建议先针对 aio app dev（本地环境）进行测试。参见 references/e2e-testing-patterns.md § 身份验证。
• AEM 扩展： 使用带有 devMode=true 的 Extension Tester URL。参见 references/aem-extension-testing.md。

完整工作流（适用于意图不明确或复杂的请求）

1. 扫描项目 — 检查 web-src/（SPA）、@adobe/uix-guest（AEM 扩展）、现有测试配置以及 app.config.yaml 扩展类型
2. 确认范围 — 要测试哪些页面或流程？使用本地开发环境还是已部署环境？是否需要 CI？
3. 安装 Playwright — 如果尚未安装，则运行 npm install -D @playwright/test && npx playwright install chromium
4. 生成配置 — 复制并按项目定制 assets/playwright.config.ts
5. 生成测试文件 — 阅读相应参考文档，并根据项目结构生成测试：
   • ExC Shell SPA → references/e2e-testing-patterns.md
   • AEM 扩展 → references/aem-extension-testing.md
6. 添加操作桩 — 如果测试需要确定性的后端响应，则添加 page.route() 拦截
7. 运行并迭代 — 运行 npx playwright test，按需修复选择器或时序问题
8. 添加 CI 工作流 — 如果用户提出要求，则阅读 references/ci-integration.md，并根据 assets/e2e-ci-workflow.yml 生成工作流
9. 验证 — 确保所有测试通过、使用 ARIA 选择器、包含断言且没有硬编码等待

需要收集的信息

• 当前仓库路径和项目类型（SPA 还是 AEM 扩展）
• 需要覆盖端到端测试的页面或用户流程
• 测试应针对本地开发环境还是已部署环境运行
• 是否需要集成 CI

交付内容

• 为项目配置的 playwright.config.ts
• e2e/ 目录中的 E2E 测试文件
• GitHub Actions 工作流（如果用户要求 CI）
• 通过的测试运行输出

质量标准

• 所有测试都使用 ARIA 选择器（getByRole、getByLabel）——不使用 CSS 类选择器
• iframe 导航使用 frameLocator()——不使用带索引的 frame()
• 所有测试都有 await expect() 断言——不允许没有断言的测试
• 使用 page.route() 模拟操作响应，确保结果可确定
• 不使用硬编码的 page.waitForTimeout()——改用 waitForSelector、waitForResponse 或 Playwright 自动等待
• 测试在本地机器上的运行时间少于 60 秒

参考资料

• 使用 references/e2e-testing-patterns.md 查阅 ExC Shell SPA 的 Playwright E2E 模式（iframe 导航、Spectrum 选择器、身份验证、操作模拟）。
• 使用 references/aem-extension-testing.md 查阅 AEM 扩展测试模式（Extension Tester、嵌套 iframe、模态框生命周期、扩展点）。
• 使用 references/ci-integration.md 查阅如何在 GitHub Actions 中运行 Playwright（浏览器安装、制品上传、无头配置）。
• 使用 assets/playwright.config.ts 作为 Playwright 配置模板的基础。
• 使用 assets/e2e-ci-workflow.yml 作为 E2E 测试的 GitHub Actions 工作流模板。

常见问题

• 找不到 iframe： ExC Shell 的 iframe 选择器因情况而异——使用 DevTools 检查。尝试 page.frameLocator('iframe[src*="your-app"]')，或使用 page.frames() 查找。
• Shell 加载指示器一直不消失： 确保在 SPA 中调用 runtime.done()。对于 E2E 测试，请等待 iframe 内的内容，而不是 Shell 本身。
• Spectrum 组件无法点击： React Spectrum 组件会渲染 ARIA 角色——使用 getByRole()，而非 CSS 选择器。请参阅 references/e2e-testing-patterns.md § Spectrum 选择器。
• 身份验证弹窗阻止测试： 使用本地开发环境（aio app dev）进行测试，该环境会跳过 Shell 身份验证。请参阅 references/e2e-testing-patterns.md 中的身份验证部分。
• AEM 扩展未加载： Extension Tester 需要 IMS 登录。扩展加载时请使用较长的超时（10 秒以上）。请参阅 references/aem-extension-testing.md § 常见问题。
• 测试在 CI 中不稳定： 添加重试（retries: 1），对操作调用使用 waitForResponse()，并参阅 references/ci-integration.md 中的无头配置。

链接关系

• 链接自 appbuilder-ui-scaffolder（生成 UI 组件后，添加 E2E 测试）
• 链接自 appbuilder-testing（用户需要 Jest 单元测试之外的浏览器级验证时）
• 链接至 appbuilder-cicd-pipeline（向 CI/CD 流水线添加 E2E 测试任务）