umbraco-unit-testing

用途

本技能用于对 Umbraco 后台（backoffice）扩展进行单元测试与组件测试，测试框架为 @open-wc/testing —— 一个面向 Web Components 与 Lit 元素的测试框架。官方描述称这是最快、隔离度最高的测试方式。

适用场景包括：

测试上下文逻辑与状态管理
测试 Lit 元素渲染与 shadow DOM
测试 observable 订阅与状态变化
测试控制器与工具函数
开发过程中的快速反馈

依赖与安装

在 package.json 中添加 devDependencies：@open-wc/testing ^4.0.0、@web/dev-server-esbuild ^1.0.0、@web/dev-server-import-maps ^0.2.0、@web/test-runner ^0.18.0、@web/test-runner-playwright ^0.11.0；并添加脚本 test: web-test-runner 与 test:watch: web-test-runner --watch。

安装命令：

npm install
npx playwright install chromium

两种配置方案

1. 完整 Umbraco 导入方案

在项目根目录创建 web-test-runner.config.mjs，使用 esbuildPlugin、playwrightLauncher、importMapsPlugin。配置要点：rootDir 为 '.'，files 为 ['./src//*.test.ts', '!/node_modules/**']，nodeResolve 的 exportConditions 为 ['development']、preferBuiltins false、browser false，浏览器使用 playwrightLauncher({ product: 'chromium' })，esbuildPlugin 开启 ts、指定 tsconfig、target 'auto'、json true，并通过 importMapsPlugin 注入 Umbraco 导入映射。

导入路径对照：

Libs（底层 API）位于 dist-cms/libs/，例如 element-api、observable-api
Packages（功能）位于 dist-cms/packages/，例如 core/lit-element、core/class-api

常见错误：使用 dist/packages 而非 dist-cms 会导致 404 错误。

2. Mock 方案（更简单）

对于不需要完整 Umbraco 上下文系统的简单单元测试，可将 Umbraco 导入整体替换为 mock。该方案避免复杂的 import map 配置，运行更快（不加载 Umbraco 包），在完全隔离下测试逻辑，适合测试类型、常量与 observable 模式。

简化配置将 Umbraco 导入映射到本地 mock 文件（如 /src/mocks/lit.js、observable-api.js、class-api.js）。

技能给出了 UmbStringState 的 mock 实现（含 getValue、setValue、asObservable、destroy）以及 lit.js 的 mock 实现（html、css、nothing、customElement、state）。

选择建议：测试类型、常量、纯函数、observable 状态模式用 Mock 方案；测试 Lit 元素 shadow DOM、元素间上下文消费、UUI 组件用完整 Umbraco 导入方案。

主要能力与测试范式

技能提供以下模式与示例代码：

基础测试结构：describe/it/beforeEach/afterEach，import { expect, fixture, defineCE } from '@open-wc/testing'。
关键工具：fixture() 创建并等待元素（可传 parentNode 用于上下文消费）；defineCE() 定义带唯一标签的自定义元素；expect() 使用 Chai 断言。
测试上下文：通过 UmbLitElement 宿主元素实例化 context，用 subscribe 与 done() 回调断言值变化与增量操作。
测试 Lit 元素：fixture 渲染元素，检查 shadowRoot.textContent，属性变更后 await element.updateComplete。
测试带上下文的元素：先创建宿主元素，再在宿主上创建 context，最后以宿主为 parentNode 创建待测元素。
测试 UI 交互：UUI 组件使用 shadow DOM，事件需带 composed: true（如 uui-button 的 click、uui-toggle 的 change）。
Observable 状态行为：状态对象仅在值发生变化时发出通知，相同值重复设置只发出一次；测试 no-op 操作时通过 callCount 与 setTimeout 断言没有第二次发出。

技能还给出了 CounterContext 与 CounterView 的完整测试示例代码。

使用方式

# 运行全部单元测试
npm test

# watch 模式
npm run test:watch

# 运行指定文件
npx web-test-runner src/my-element.test.ts

# 带覆盖率运行
npx web-test-runner --coverage

目录结构示例：src 下的源文件与 .test.ts 测试文件并列，根目录放置 web-test-runner.config.mjs、package.json、tsconfig.json。

限制与排查

技能列出的常见问题及处理：

导入 404：检查 import map 路径，API 用 dist-cms/libs/，功能用 dist-cms/packages/。
元素未定义：测试前需先 import 该元素文件（副作用导入注册元素）。
上下文不可用：元素必须是带有上下文的宿主的子元素。
observable 测试挂起：异步订阅使用 done() 回调。
updateComplete 未等待：必须 await element.updateComplete。

关于该技能的具体授权方式、收费模式、支持版本范围等，资料中暂未提供。

技能介绍

用途