SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场umbraco-mocked-backoffice

umbraco-mocked-backoffice

测试与质量

查看项目

更新于 10-15 17:37

技能介绍

Umbraco Mocked Backoffice 用于在不依赖 .NET 后端的情况下，运行完整的 Umbraco 后台 UI，并模拟所有 API 调用。

状态说明 该技能当前正在等待 Umbraco 更新，以允许外部扩展使用被模拟的后台。此处记录的模式在 Umbraco-CMS 源码仓库内运行时有效。

何时使用

  • 在开发过程中对扩展进行可视化测试
  • 无需部署后端即可快速迭代
  • 在逼真的 UI 环境中测试扩展
  • 在没有基础设施的情况下演示扩展
  • 无需后端设置的 CI/CD 测试

相关技能

  • umbraco-example-generator：为 Mocked Backoffice 设置扩展（从此开始）
  • umbraco-testing：测试总览主技能
  • umbraco-unit-testing：隔离测试扩展逻辑
  • umbraco-e2e-testing：针对真实 Umbraco 实例进行测试

两种模拟方式 具有自定义 API 的扩展可以使用两种模拟方式：MSW Handlers（网络层 API 模拟，最适合测试错误处理、加载状态、重试）和 Mock Repository（应用层模拟，最适合使用可预测数据测试 UI，推荐）。两种方式都需要为核心 Umbraco API 启用 MSW（VITE_UMBRACO_USE_MSW=on）。

设置步骤

  1. 创建扩展：使用 umbraco-example-generator 技能（调用：skill: umbraco-example-generator），涵盖克隆 Umbraco-CMS 仓库、扩展结构与 src/index.ts 要求、使用 VITE_EXAMPLE_PATH 和 npm run dev 运行。
  2. 添加测试依赖，在 package.json 中配置 @playwright/test 及 test:mock-repo、test:msw 脚本，并执行 npm install 与 npx playwright install chromium。
  3. 目录结构：Client/src/index.ts（入口，加载 manifests 并注册 MSW handlers）、manifests.ts、feature/、msw/handlers.ts；tests/mock-repo/（mock 仓库测试，含 playwright.config.ts、spec 及 mock/index.ts、mock-repository.ts、mock-data.ts）；tests/msw/（MSW 测试）。
  4. 入口点 src/index.ts 根据环境条件加载 MSW handlers 或 mock manifests：当 VITE_UMBRACO_USE_MSW 为 on 且 VITE_USE_MOCK_REPO 不为 on 时注册 MSW handlers；根据 VITE_USE_MOCK_REPO 选择 mock repository 或正式 manifests。

运行测试 外部示例的自包含支持为自动方式：从 Umbraco 客户端外部路径加载扩展，需要客户端支持绝对 VITE_EXAMPLE_PATH（通过 Vite 的 /@fs/）以及共享包解析器，使 @umbraco-cms/backoffice、lit 和 @umbraco-ui/uui 解析到客户端的单一副本。正式发布版 v18 仅支持相对路径（./examples/...）。为保持自包含，仓库的 mock 配置通过 Playwright 的 globalSetup/globalTeardown（位于 plugins/umbraco-testing-skills/harness/mocked-backoffice/）在开发服务器启动前将该支持注入客户端（基于文件备份，可检测已具备支持的客户端并跳过），因此无需 CMS 分支，只需要一个构建好的 v18 客户端（在 Umbraco.Web.UI.Client 中执行 npm ci）。首次对刚打过补丁的客户端运行时可能会重新优化依赖并短暂重启开发服务器（首次导航可能不稳定），配置已设置重试来吸收该情况；预热后运行稳定。

环境变量

  • VITE_EXAMPLE_PATH：/path/to/extension/Client，指向扩展目录
  • VITE_UMBRACO_USE_MSW：on，为核心 Umbraco API 启用 MSW
  • VITE_USE_MOCK_REPO：on，使用 mock repository 而非 MSW handlers
  • UMBRACO_CLIENT_PATH：/path/to/Umbraco.Web.UI.Client，供 Playwright 使用

手动运行开发服务器 在 Umbraco-CMS/src/Umbraco.Web.UI.Client 下：MSW 模式使用 VITE_EXAMPLE_PATH 与 VITE_UMBRACO_USE_MSW=on；Mock repository 模式额外设置 VITE_USE_MOCK_REPO=on。

运行测试 在扩展 Client 目录下设置 UMBRACO_CLIENT_PATH，执行 npm run test:msw 或 npm run test:mock-repo。

Playwright 配置示例 配置中包含 testDir、testMatch、timeout（60000）、expect.timeout（15000）、fullyParallel: false、workers: 1；webServer 命令在 UMBRACO_CLIENT_PATH 下以 VITE_EXAMPLE_PATH 与 VITE_UMBRACO_USE_MSW=on 运行 dev server 并指定端口 5176；use 设置 baseURL、trace、screenshot；项目为 chromium（Desktop Chrome）。mock-repo 测试将命令改为包含 VITE_USE_MOCK_REPO=on。

测试模式 提供导航辅助函数（navigateToSettings，等待 umb-section-sidebar）、树项测试（等待 umb-tree-item 可见、展开树项显示子项）等示例，并列出 MSW 模拟文档 URL（如 /section/content/workspace/document/edit/the-simplest-document-id、/all-property-editors-document-id）。

故障排查

  • 扩展未出现：检查 src/index.ts 是否导出 manifests 数组、浏览器控制台错误、VITE_EXAMPLE_PATH 是否指向 Client 目录。
  • 测试等待元素超时：确保开发服务器加载了扩展、检查控制台加载错误、对首次出现元素使用更长超时（15000ms+）。
  • MSW handlers 未拦截请求：检查控制台 [MSW] 日志、验证 handler URL 模式与实际 API 调用匹配、使用 DevTools Network 查看实际请求 URL。

工作示例 参见 umbraco-backoffice-skills/examples/tree-example/Client/，其中 src/index.ts 为条件 manifest 加载入口，src/msw/handlers.ts 为自定义 API 的 MSW handlers，tests/mock-repo/ 与 tests/msw/ 分别为测试。设置 UMBRACO_CLIENT_PATH 后可分别运行 npm run test:msw 与 npm run test:mock-repo。

模拟内容 MSW 为所有后台 API 提供模拟数据，包括：文档、媒体、成员；文档类型、媒体类型、成员类型；数据类型、模板、样式表；用户、用户组、权限；语言、文化、字典项。