appbuilder-testing

App Builder 测试

为 Adobe App Builder 操作和 React Spectrum UI 组件生成并运行 Jest 测试。搭建单元测试、集成测试、组件测试和 Adobe SDK 模拟辅助工具。

模式速查

选择与用户意图匹配的模板或参考文档。对于通用测试请求，默认使用 assets/unit-test-template.js。

用户需求	参考文档	模板 / 资源
为现有操作编写单元测试	references/testing-patterns.md	assets/unit-test-template.js
针对已部署操作进行集成测试	references/testing-patterns.md	assets/integration-test-template.js
为 React Spectrum UI 编写组件测试	references/component-testing-patterns.md	assets/component-test-template.js
在测试中模拟 ExC Shell 上下文	references/component-testing-patterns.md	assets/shell-mock-helper.js
在测试中模拟 AEM 扩展上下文	references/component-testing-patterns.md	assets/uix-guest-mock-helper.js
在测试中模拟 State SDK	references/mock-catalog.md	assets/mock-state-sdk.js
在测试中模拟 Files SDK	references/mock-catalog.md	assets/mock-files-sdk.js
在测试中模拟 Events SDK	references/mock-catalog.md	assets/mock-events-sdk.js
在测试中模拟 Database SDK	references/mock-catalog.md	assets/mock-database-sdk.js
完整模拟目录（所有 SDK）	references/mock-catalog.md	—
API 交互契约测试	references/testing-patterns.md	—
部署前验证	references/checklist.md	—
调试测试失败	references/debugging.md	—

快速路径（适用于明确的请求）

如果用户的请求明确对应上方的某一种模式——他们指定了测试类型、引用了模板，或描述了与某个条目明确匹配的用例——请跳过后续步骤，直接生成。使用匹配的模板并立即开始。

快速路径触发示例：

• “为我的操作编写测试” → 阅读操作源码，使用 assets/unit-test-template.js，立即生成
• “帮我模拟 State SDK” → 使用 assets/mock-state-sdk.js，注入测试文件
• “添加集成测试” → 使用 assets/integration-test-template.js，配置已部署的操作
• “运行测试并生成覆盖率” → 执行 npx jest --coverage 或 aio app test
• “测试我的组件 / 页面 / 表单 / 表格” → 阅读组件源码，使用 assets/component-test-template.js，并用 Provider 包装
• “模拟 Shell 上下文” → 使用 assets/shell-mock-helper.js，注入测试文件
• “测试我的 AEM 扩展组件” → 使用 assets/uix-guest-mock-helper.js + assets/component-test-template.js

如果存在任何歧义——需要多种测试类型、项目结构不明确，或用户没有提供足够信息——则转到下方的完整工作流。

快速参考

• 测试目录： 将测试文件放在 test/ 中，并镜像操作路径，例如 test/actions/<action-name>/index.test.js。
• Jest 配置： App Builder 项目默认使用 Jest。配置位于 package.json 或 jest.config.js 中。
• 测试命令： aio app test（封装命令）或 npx jest --coverage（直接运行）。
• 模拟模式： 在测试文件顶部使用 jest.mock()，在导入操作前模拟 Adobe SDK 依赖项。
• 响应格式： 所有操作均返回 { statusCode, body }——每项测试都要断言这两个字段。
• 错误路径： 始终测试 200（成功）、400（输入错误）和 500（SDK 失败）场景。
• CommonJS： 操作测试文件使用 require() 和 module.exports（而非 ES imports）。
• 组件测试目录： test/web-src/components/<ComponentName>.test.js（或 test/components/）。
• Provider 包装器： 始终使用 <Provider theme={defaultTheme}> 包装——没有它，Spectrum 不会渲染任何内容。
• ARIA 选择器： 使用 getByRole()，不要使用 CSS 类——请参阅 references/component-testing-patterns.md 中的选择器表。
• 异步测试： 对异步出现的数据使用 findBy*，对不存在的内容使用 queryBy*，对状态更改使用 waitFor。

完整工作流（适用于模糊或复杂的请求）

1. 扫描项目结构 — 检查是否存在 test/ 目录、jest.config.js 和 package.json 中的测试脚本。扫描 src/ 中的操作以及 web-src/ 中的 UI 组件。
2. 确定测试目标 — 解析 ext.config.yaml（或 app.config.yaml），获取声明的操作及其源文件路径。检查 web-src/src/components/ 中的 React 组件。
3. 确定所需的测试类型 — 针对逻辑编写单元测试，针对已部署的操作编写集成测试，针对 API 交互编写契约测试。
4. **对于每个操作：**a. 阅读操作源代码，确定 SDK 依赖项（State、Files、Events、Logger 等）。b. 以 assets/unit-test-template.js 为基础生成单元测试。c. 根据检测到的依赖项，从 references/mock-catalog.md 注入合适的模拟。d. 添加错误场景测试（缺少参数、身份验证失败、SDK 错误）。
5. **对于每个 UI 组件：**a. 阅读组件源代码，确定依赖项（shell 上下文、UIX guest、操作调用）。b. 以 assets/component-test-template.js 为基础生成组件测试。c. 将所有渲染内容包裹在 <Provider theme={defaultTheme}> 中 — 没有它，Spectrum 不会渲染任何内容。d. 按需注入 shell 模拟（assets/shell-mock-helper.js）或 UIX guest 模拟（assets/uix-guest-mock-helper.js）。e. 使用 findBy* 和 waitFor 为异步数据添加加载、成功和错误状态测试。
6. 运行测试 — 执行 aio app test 或 npx jest --coverage，并报告结果。
7. 验证 — 完成前对照 references/checklist.md 检查。

用户提示词示例

• “为我的通用操作编写单元测试”
• “为我已部署的操作添加集成测试”
• “我的操作使用 State SDK — 帮我在测试中模拟它”
• “运行测试并显示覆盖率”
• “为我的 App Builder 项目配置 Jest”
• “测试我的操作是否能妥善处理错误”
• “为我的数据表页面编写组件测试”
• “测试我的 AEM 扩展面板组件”
• “帮我在测试中模拟 shell 上下文”
• “为我的 React Spectrum 表单添加测试”

需要收集的输入

• 当前仓库路径和操作文件位置
• 需要测试的操作（或测试所有已声明的操作）
• 目标测试类型：单元、集成、契约或全部
• 操作是否已部署（集成测试所需）

交付内容

• test/ 中与操作目录结构对应的测试文件
• UI 组件对应的 test/web-src/components/ 组件测试文件
• 针对检测到的 Adobe SDK 依赖项的模拟辅助工具
• 组件依赖上下文 SDK 时所需的 Shell 或 UIX Guest 模拟辅助工具
• 尚未配置时提供 Jest 配置（包括用于组件测试的 jsdom 环境）
• 测试执行生成的覆盖率报告

质量标准

• 每个操作测试至少涵盖：成功（200）、输入错误（400）和 SDK 故障（500）路径
• 通过 beforeEach(() => jest.clearAllMocks()) 隔离每项测试中的模拟
• 单元测试不得调用真实 SDK — 所有外部依赖项都必须模拟
• 测试具有确定性，可离线运行（单元测试不依赖网络）
• 启用覆盖率报告（--coverage 标志）
• 所有组件测试都必须用 <Provider theme={defaultTheme}> 包裹 — 没有它，Spectrum 不会渲染任何内容

参考资料

• 使用 references/testing-patterns.md 查看包含注释示例的单元、集成和契约测试模式。
• 使用 references/component-testing-patterns.md 查看 React Spectrum 组件测试模式，涵盖 Provider 包装、ARIA 选择器和异步模式。
• 使用 references/mock-catalog.md 查看覆盖所有 Adobe SDK（State、Files、Events、Logger、Database、Shell、UIX Guest）的模拟辅助工具。
• 使用 references/checklist.md 进行部署前测试验证。
• 使用 assets/unit-test-template.js 获取 Jest 单元测试样板代码（CommonJS）。
• 使用 assets/integration-test-template.js 获取针对已部署操作的集成测试样板代码。
• 使用 assets/component-test-template.js 获取包含 renderWithSpectrum() 辅助函数的 React Spectrum 组件测试样板代码。
• 使用 assets/shell-mock-helper.js 获取 ExC Shell 上下文模拟（@adobe/exc-app）。
• 使用 assets/uix-guest-mock-helper.js 获取 AEM UIX Guest 模拟（@adobe/uix-guest）。
• 使用 assets/mock-state-sdk.js、assets/mock-files-sdk.js、assets/mock-events-sdk.js 和 assets/mock-database-sdk.js 获取开箱即用的 SDK 模拟配置。

常见问题

• 测试失败并显示“Cannot find module”： 确保 require() 中的操作路径与实际文件位置一致。App Builder 操作通常位于 src/dx-excshell-1/actions/<name>/index.js。
• 模拟不起作用： jest.mock() 调用必须位于被测模块的 require() 之前。Jest 会提升模拟声明，但对于手动模拟，顺序仍然很重要。
• State/Files SDK 测试失败： 这些 SDK 需要 Runtime 环境才能进行真实调用。单元测试中务必模拟它们。需要访问真实 SDK 的集成测试请使用 aio app run（而非 aio app dev）。
• 覆盖率过低： 为错误分支添加测试——缺少参数、无效的身份验证标头、SDK init() 失败和超时场景。
• aio app test 与 npx jest： aio app test 是 Jest 的轻量封装。若要更灵活地控制标志和报告器，请直接使用 npx jest --coverage。
• 测试中的 Spectrum 组件渲染为空白： 缺少 <Provider theme={defaultTheme}> 包装。请使用 assets/component-test-template.js 中的 renderWithSpectrum() 辅助函数。
• ARIA 角色查询返回 null： Spectrum 组件使用 ARIA 角色，而非 CSS 类。角色参考表请参阅 references/component-testing-patterns.md 的 g 节。

链接关系

• 链接自 appbuilder-action-scaffolder（实现后测试操作）
• 链接自 appbuilder-ui-scaffolder（搭建后测试 UI 组件）
• 链接至 appbuilder-cicd-pipeline（在 CI 中自动执行测试）