appbuilder-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

App Builder Testing

App Builder测试

Generate and run Jest tests for Adobe App Builder actions and React Spectrum UI components. Scaffolds unit tests, integration tests, component tests, and mock helpers for Adobe SDKs.

为Adobe App Builder动作和React Spectrum UI组件生成并运行Jest测试。搭建单元测试、集成测试、组件测试以及Adobe SDK的模拟助手。

Pattern Quick-Reference

模式快速参考

Pick the template or reference that matches the user's intent. Default to

assets/unit-test-template.js

for generic test requests.

User wants	Reference	Template / Asset
Unit test for an existing action	references/testing-patterns.md	assets/unit-test-template.js
Integration test against deployed action	references/testing-patterns.md	assets/integration-test-template.js
Component test for React Spectrum UI	references/component-testing-patterns.md	assets/component-test-template.js
Mock ExC Shell context in tests	references/component-testing-patterns.md	assets/shell-mock-helper.js
Mock AEM extension context in tests	references/component-testing-patterns.md	assets/uix-guest-mock-helper.js
Mock State SDK in tests	references/mock-catalog.md	assets/mock-state-sdk.js
Mock Files SDK in tests	references/mock-catalog.md	assets/mock-files-sdk.js
Mock Events SDK in tests	references/mock-catalog.md	assets/mock-events-sdk.js
Mock Database SDK in tests	references/mock-catalog.md	assets/mock-database-sdk.js
Full mock catalog (all SDKs)	references/mock-catalog.md	—
Contract test for API interactions	references/testing-patterns.md	—
Pre-deployment verification	references/checklist.md	—
Debug test failures	references/debugging.md	—

选择与用户意图匹配的模板或参考文档。对于通用测试请求，默认使用

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	—

Fast Path (for clear requests)

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

When the user's request maps unambiguously to a single pattern above — they name a specific test type, reference a template, or describe a use case that clearly matches one entry — skip straight to generation. Use the matched template and proceed directly.

Examples of fast-path triggers:

"Write tests for my action" → Read the action source, use
```
assets/unit-test-template.js
```
, generate immediately
"Help me mock State SDK" → Use
```
assets/mock-state-sdk.js
```
, inject into test file
"Add integration tests" → Use
```
assets/integration-test-template.js
```
, configure for deployed action
"Run tests with coverage" → Execute
```
npx jest --coverage
```
or
```
aio app test
```
"Test my component/page/form/table" → Read the component source, use
```
assets/component-test-template.js
```
, wrap in Provider
"Mock shell context" → Use
```
assets/shell-mock-helper.js
```
, inject into test file

"Test my AEM extension component" → Use

assets/uix-guest-mock-helper.js

assets/component-test-template.js

If there is any ambiguity — multiple test types needed, project structure unclear, or the user hasn't specified enough — fall through to the full workflow below.

当用户的请求明确对应上述单一模式——他们指定了特定测试类型、参考模板，或描述的用例清晰匹配某一项时，直接跳转到生成步骤。使用匹配的模板并立即执行。

快速路径触发示例：

"为我的动作编写测试" → 读取动作源代码，使用
```
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

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

Quick Reference

快速参考

Test directory: Place test files in
```
test/
```
mirroring the action path, e.g.,
```
test/actions/<action-name>/index.test.js
```
.
Jest configuration: App Builder projects use Jest by default. Config lives in
```
package.json
```
or
```
jest.config.js
```
.
Test command:
```
aio app test
```
(wrapper) or
```
npx jest --coverage
```
(direct).
Mock pattern: Use
```
jest.mock()
```
at the top of test files to mock Adobe SDK dependencies before importing the action.
Response shape: All actions return
```
{ statusCode, body }
```
— assert both in every test.
Error paths: Always test 200 (success), 400 (bad input), and 500 (SDK failure) scenarios.
CommonJS: Action test files use
```
require()
```
and
```
module.exports
```
(not ES imports).

Component test directory:

test/web-src/components/<ComponentName>.test.js

(or

test/components/

Provider wrapper: Always wrap in
```
<Provider theme={defaultTheme}>
```
— Spectrum renders nothing without it.
ARIA selectors: Use
```
getByRole()
```
, not CSS classes — see
```
references/component-testing-patterns.md
```
selector table.
Async testing: Use
```
findBy*
```
for data that appears async,
```
queryBy*
```
for absence,
```
waitFor
```
for state changes.

测试目录： 将测试文件放在
```
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导入）。

组件测试目录：

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
```
。

Full Workflow (for ambiguous or complex requests)

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

Scan project structure — Check for existing
```
test/
```
directory,
```
jest.config.js
```
, and test scripts in
```
package.json
```
. Scan both
```
src/
```
for actions AND
```
web-src/
```
for UI components.
Identify targets to test — Parse
```
ext.config.yaml
```
(or
```
app.config.yaml
```
) for declared actions and their source paths. Check
```
web-src/src/components/
```
for React components.
Determine test types needed — Unit tests for logic, integration tests for deployed actions, contract tests for API interactions.
**For each action:**a. Read the action source to identify SDK dependencies (State, Files, Events, Logger, etc.).b. Generate unit test using
```
assets/unit-test-template.js
```
as the base.c. Inject appropriate mocks from
```
references/mock-catalog.md
```
based on detected dependencies.d. Add error scenario tests (missing params, auth failures, SDK errors).
**For each UI component:**a. Read the component source to identify dependencies (shell context, UIX guest, action calls).b. Generate component test using
```
assets/component-test-template.js
```
as the base.c. Wrap all renders in
```
<Provider theme={defaultTheme}>
```
— Spectrum renders nothing without it.d. Inject shell mock (
```
assets/shell-mock-helper.js
```
) or UIX guest mock (
```
assets/uix-guest-mock-helper.js
```
) as needed.e. Add loading, success, and error state tests for async data using
```
findBy*
```
and
```
waitFor
```
.
Run tests — Execute
```
aio app test
```
or
```
npx jest --coverage
```
and report results.
Validate — Check against
```
references/checklist.md
```
before marking done.

扫描项目结构 —— 检查是否存在现有
```
test/
```
目录、
```
jest.config.js
```
以及
```
package.json
```
中的测试脚本。同时扫描
```
src/
```
中的动作和
```
web-src/
```
中的UI组件。
确定测试目标 —— 解析
```
ext.config.yaml
```
（或
```
app.config.yaml
```
）中声明的动作及其源路径。检查
```
web-src/src/components/
```
中的React组件。
确定所需测试类型 —— 针对逻辑的单元测试、针对已部署动作的集成测试、针对API交互的契约测试。
**针对每个动作：**a. 读取动作源代码，识别SDK依赖（State、Files、Events、Logger等）。b. 以
```
assets/unit-test-template.js
```
为基础生成单元测试。c. 根据检测到的依赖，从
```
references/mock-catalog.md
```
中注入相应的模拟。d. 添加错误场景测试（缺少参数、认证失败、SDK错误）。
**针对每个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
```
为异步数据添加加载、成功和错误状态测试。
运行测试 —— 执行
```
aio app test
```
或
```
npx jest --coverage
```
并报告结果。
验证 —— 在标记完成前对照
```
references/checklist.md
```
检查。

Example User Prompts

用户示例提示

"Write unit tests for my generic action"
"Add integration tests for my deployed action"
"My action uses State SDK — help me mock it in tests"
"Run tests and show me coverage"
"Set up Jest for my App Builder project"
"Test my action handles errors properly"
"Write component tests for my data table page"
"Test my AEM extension panel component"
"Help me mock shell context in my tests"
"Add tests for my React Spectrum form"

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

Inputs To Request

需要请求的输入信息

Current repository path and action file locations
Which actions need tests (or test all declared actions)
Target test types: unit, integration, contract, or all
Whether action is deployed (needed for integration tests)

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

Deliverables

交付物

Test files in
```
test/
```
matching the action directory structure
Component test files in
```
test/web-src/components/
```
for UI components
Mock helpers for detected Adobe SDK dependencies
Shell or UIX Guest mock helpers when components depend on context SDKs
Jest configuration if not already present (including jsdom environment for component tests)
Coverage report from test execution

位于
```
test/
```
目录中的测试文件，与动作目录结构匹配
针对UI组件的测试文件，位于
```
test/web-src/components/
```
针对检测到的Adobe SDK依赖的模拟助手
当组件依赖上下文SDK时，提供Shell或UIX Guest模拟助手
如果尚未存在，提供Jest配置（包括组件测试所需的jsdom环境）
测试执行的覆盖率报告

Quality Bar

质量标准

Every action test covers at minimum: success (200), bad input (400), and SDK failure (500) paths
Mocks are isolated per test via
```
beforeEach(() => jest.clearAllMocks())
```
No real SDK calls in unit tests — all external dependencies are mocked
Tests are deterministic and can run offline (no network dependencies in unit tests)
Coverage reporting is enabled (
```
--coverage
```
flag)
All component tests wrap in
```
<Provider theme={defaultTheme}>
```
— Spectrum renders nothing without it

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

References

参考文档

Use
```
references/testing-patterns.md
```
for unit, integration, and contract test patterns with annotated examples.
Use
```
references/component-testing-patterns.md
```
for React Spectrum component testing with Provider wrapping, ARIA selectors, and async patterns.
Use
```
references/mock-catalog.md
```
for mock helpers covering all Adobe SDKs (State, Files, Events, Logger, Database, Shell, UIX Guest).
Use
```
references/checklist.md
```
for pre-deployment test verification.
Use
```
assets/unit-test-template.js
```
for Jest unit test boilerplate (CommonJS).
Use
```
assets/integration-test-template.js
```
for integration test against deployed actions.
Use
```
assets/component-test-template.js
```
for React Spectrum component test boilerplate with
```
renderWithSpectrum()
```
helper.

Use

assets/shell-mock-helper.js

for ExC Shell context mock (

@adobe/exc-app

Use

assets/uix-guest-mock-helper.js

for AEM UIX Guest mock (

@adobe/uix-guest

Use

assets/mock-state-sdk.js

assets/mock-files-sdk.js

assets/mock-events-sdk.js

, and

assets/mock-database-sdk.js

for ready-to-use SDK mock setups.

使用
```
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模拟设置。

Common Issues

常见问题

Tests fail with "Cannot find module": Ensure the action path in
```
require()
```
matches the actual file location. App Builder actions are typically at
```
src/dx-excshell-1/actions/<name>/index.js
```
.
Mocks not working:
```
jest.mock()
```
calls must appear before
```
require()
```
of the module under test. Jest hoists mock declarations but order still matters for manual mocks.
State/Files SDK tests fail: These SDKs require Runtime environment for real calls. Always mock them in unit tests. Use
```
aio app run
```
(not
```
aio app dev
```
) for integration tests that need real SDK access.
Coverage too low: Add tests for error branches — missing params, invalid auth headers, SDK
```
init()
```
failures, and timeout scenarios.
```
aio app test
```
** vs
```
npx jest
```
:**
```
aio app test
```
is a thin wrapper around Jest. Use
```
npx jest --coverage
```
directly for more control over flags and reporters.

Spectrum components render blank in tests: Missing

<Provider theme={defaultTheme}>

wrapper. Use

renderWithSpectrum()

helper from

assets/component-test-template.js

ARIA role queries return null: Spectrum components use ARIA roles, not CSS classes. See
```
references/component-testing-patterns.md
```
section g for the role reference table.

测试失败，提示"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
vs
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节的角色参考表格。

Chaining

链式关联

Chains FROM
```
appbuilder-action-scaffolder
```
(test actions after implementation)
Chains FROM
```
appbuilder-ui-scaffolder
```
(test UI components after scaffolding)
Chains TO
```
appbuilder-cicd-pipeline
```
(automated test execution in CI)

从
```
appbuilder-action-scaffolder
```
关联而来（实现动作后进行测试）
从
```
appbuilder-ui-scaffolder
```
关联而来（搭建UI组件后进行测试）
关联到
```
appbuilder-cicd-pipeline
```
（在CI中自动执行测试）