umbraco-mocked-backoffice by umbraco/umbraco-cms-backoffice-skills
npx skills add https://github.com/umbraco/umbraco-cms-backoffice-skills --skill umbraco-mocked-backoffice状态: 此技能目前正在等待 Umbraco 的更新,以允许外部扩展使用模拟后台。本文档记录的模式在从 Umbraco-CMS 源代码仓库内运行时有效。
运行完整的 Umbraco 后台 UI,所有 API 调用均被模拟 - 无需 .NET 后端。
具有自定义 API 的扩展可以使用两种模拟方法:
| 方法 | 使用场景 | 最适合 |
|---|---|---|
| MSW 处理程序 | 网络级 API 模拟 | 测试错误处理、加载状态、重试 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 模拟仓库 | 应用级模拟 | 使用可预测数据测试 UI(推荐) |
两种方法都需要启用 MSW (VITE_UMBRACO_USE_MSW=on) 以支持核心 Umbraco API。
使用 umbraco-example-generator 技能来设置你的扩展:
调用 : skill: umbraco-example-generator
这包括:
src/index.ts 要求VITE_EXAMPLE_PATH 和 npm run dev 运行{
"devDependencies": {
"@playwright/test": "^1.56"
},
"scripts": {
"test:mock-repo": "playwright test --config=tests/mock-repo/playwright.config.ts",
"test:msw": "playwright test --config=tests/msw/playwright.config.ts"
}
}
npm install
npx playwright install chromium
my-extension/Client/
├── src/
│ ├── index.ts # 入口点(加载清单,注册 MSW 处理程序)
│ ├── manifests.ts # 生产清单
│ ├── feature/
│ │ ├── my-element.ts
│ │ └── types.ts
│ └── msw/ # MSW 处理程序(从 index.ts 加载)
│ └── handlers.ts
├── tests/
│ ├── mock-repo/ # 模拟仓库测试
│ │ ├── playwright.config.ts
│ │ ├── my-extension.spec.ts
│ │ └── mock/
│ │ ├── index.ts # 模拟清单(替换仓库)
│ │ ├── mock-repository.ts
│ │ └── mock-data.ts
│ └── msw/ # MSW 测试
│ ├── playwright.config.ts
│ └── my-extension.spec.ts
├── package.json
└── tsconfig.json
入口点根据环境条件加载 MSW 处理程序或模拟清单:
// 外部扩展加载的入口点
// 在 Umbraco.Web.UI.Client 中运行:
// VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_UMBRACO_USE_MSW=on npm run dev
// VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev
// 在 MSW 模式下运行时注册 MSW 处理程序(但非模拟仓库模式)
if (import.meta.env.VITE_UMBRACO_USE_MSW === 'on' && import.meta.env.VITE_USE_MOCK_REPO !== 'on') {
import('./msw/handlers.js').then(({ createHandlers }) => {
const { addMockHandlers } = (window as any).MockServiceWorker;
addMockHandlers(...createHandlers());
});
}
// 导出清单 - 如果设置了 VITE_USE_MOCK_REPO,则使用模拟仓库
export const manifests = import.meta.env.VITE_USE_MOCK_REPO === 'on'
? (await import('../tests/mock-repo/mock/index.js')).manifests
: (await import('./manifests.js')).manifests;
| 变量 | 值 | 用途 |
|---|---|---|
VITE_EXAMPLE_PATH | /path/to/extension/Client | 扩展目录路径 |
VITE_UMBRACO_USE_MSW | on | 为核心 Umbraco API 启用 MSW |
VITE_USE_MOCK_REPO | on | 使用模拟仓库而非 MSW 处理程序 |
UMBRACO_CLIENT_PATH | /path/to/Umbraco.Web.UI.Client | Umbraco 客户端路径(用于 Playwright) |
cd /path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
# MSW 模式(使用你的处理程序处理自定义 API)
VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_UMBRACO_USE_MSW=on npm run dev
# 模拟仓库模式(使用模拟仓库处理自定义 API)
VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev
cd /path/to/extension/Client
# 设置 Umbraco 客户端路径
export UMBRACO_CLIENT_PATH=/path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
# 运行 MSW 测试
npm run test:msw
# 运行模拟仓库测试
npm run test:mock-repo
创建 tests/msw/playwright.config.ts:
import { defineConfig, devices } from '@playwright/test';
import { fileURLToPath } from 'url';
import { dirname, resolve } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const EXTENSION_PATH = resolve(__dirname, '../..');
const UMBRACO_CLIENT_PATH = process.env.UMBRACO_CLIENT_PATH;
if (!UMBRACO_CLIENT_PATH) {
throw new Error('UMBRACO_CLIENT_PATH environment variable is required');
}
const DEV_SERVER_PORT = 5176;
export default defineConfig({
testDir: '.',
testMatch: ['*.spec.ts'],
timeout: 60000,
expect: { timeout: 15000 },
fullyParallel: false,
workers: 1,
// 启动带有扩展和 MSW 启用的开发服务器
webServer: {
command: `VITE_EXAMPLE_PATH=${EXTENSION_PATH} VITE_UMBRACO_USE_MSW=on npm run dev -- --port ${DEV_SERVER_PORT}`,
cwd: UMBRACO_CLIENT_PATH,
port: DEV_SERVER_PORT,
reuseExistingServer: !process.env.CI,
timeout: 120000,
},
use: {
baseURL: `http://localhost:${DEV_SERVER_PORT}`,
trace: 'on-first-retry',
screenshot: 'only-on-failure',
},
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
],
});
对于模拟仓库测试,将命令更改为包含 VITE_USE_MOCK_REPO=on:
command: `VITE_EXAMPLE_PATH=${EXTENSION_PATH} VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev -- --port ${DEV_SERVER_PORT}`,
import { type Page } from '@playwright/test';
async function navigateToSettings(page: Page) {
await page.goto('/section/settings');
await page.waitForLoadState('domcontentloaded');
await page.waitForSelector('umb-section-sidebar', { timeout: 30000 });
}
test('should display root tree items', async ({ page }) => {
await navigateToSettings(page);
await page.waitForSelector('umb-tree-item', { timeout: 15000 });
const treeItems = page.locator('umb-tree-item');
await expect(treeItems.first()).toBeVisible();
});
test('should expand tree item to show children', async ({ page }) => {
await navigateToSettings(page);
const expandableItem = page.locator('umb-tree-item').filter({ hasText: 'Group A' });
const expandButton = expandableItem.locator('button[aria-label="toggle child items"]');
await expandButton.click();
const childItem = page.locator('umb-tree-item').filter({ hasText: 'Child 1' });
await expect(childItem).toBeVisible({ timeout: 15000 });
});
| 文档名称 | URL 路径 |
|---|---|
| 最简单的文档 | /section/content/workspace/document/edit/the-simplest-document-id |
| 所有属性 | /section/content/workspace/document/edit/all-property-editors-document-id |
src/index.ts 导出了一个 manifests 数组VITE_EXAMPLE_PATH 是否指向 Client 目录[MSW] 日志查看 umbraco-backoffice-skills/examples/tree-example/Client/ 中的 tree-example:
| 路径 | 描述 |
|---|---|
src/index.ts | 带有条件清单加载的入口点 |
src/msw/handlers.ts | 自定义 API 的 MSW 处理程序 |
tests/mock-repo/ | 模拟仓库测试 |
tests/msw/ | MSW 测试 |
cd tree-example/Client
export UMBRACO_CLIENT_PATH=/path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
npm run test:msw # 运行 MSW 测试
npm run test:mock-repo # 运行模拟仓库测试
MSW 为所有后台 API 提供模拟数据:
每周安装次数
75
仓库
GitHub 星标
17
首次出现
2026年2月4日
安全审计
安装于
github-copilot54
codex22
opencode21
cursor21
gemini-cli19
amp19
Status: This skill is currently awaiting an update from Umbraco to allow external extensions to use the mocked backoffice. The patterns documented here work when running from within the Umbraco-CMS source repository.
Run the full Umbraco backoffice UI with all API calls mocked - no .NET backend required.
Extensions with custom APIs can use two mocking approaches:
| Approach | Use Case | Best For |
|---|---|---|
| MSW Handlers | Network-level API mocking | Testing error handling, loading states, retries |
| Mock Repository | Application-level mocking | Testing UI with predictable data (recommended) |
Both approaches require MSW to be enabled (VITE_UMBRACO_USE_MSW=on) for core Umbraco APIs.
Use the umbraco-example-generator skill to set up your extension:
Invoke : skill: umbraco-example-generator
This covers:
src/index.ts requirementsVITE_EXAMPLE_PATH and npm run dev{
"devDependencies": {
"@playwright/test": "^1.56"
},
"scripts": {
"test:mock-repo": "playwright test --config=tests/mock-repo/playwright.config.ts",
"test:msw": "playwright test --config=tests/msw/playwright.config.ts"
}
}
npm install
npx playwright install chromium
my-extension/Client/
├── src/
│ ├── index.ts # Entry point (loads manifests, registers MSW handlers)
│ ├── manifests.ts # Production manifests
│ ├── feature/
│ │ ├── my-element.ts
│ │ └── types.ts
│ └── msw/ # MSW handlers (loaded from index.ts)
│ └── handlers.ts
├── tests/
│ ├── mock-repo/ # Mock repository tests
│ │ ├── playwright.config.ts
│ │ ├── my-extension.spec.ts
│ │ └── mock/
│ │ ├── index.ts # Mock manifests (replaces repository)
│ │ ├── mock-repository.ts
│ │ └── mock-data.ts
│ └── msw/ # MSW tests
│ ├── playwright.config.ts
│ └── my-extension.spec.ts
├── package.json
└── tsconfig.json
The entry point conditionally loads MSW handlers or mock manifests based on environment:
// Entry point for external extension loading
// Run from Umbraco.Web.UI.Client with:
// VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_UMBRACO_USE_MSW=on npm run dev
// VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev
// Register MSW handlers when running in MSW mode (but not mock-repo mode)
if (import.meta.env.VITE_UMBRACO_USE_MSW === 'on' && import.meta.env.VITE_USE_MOCK_REPO !== 'on') {
import('./msw/handlers.js').then(({ createHandlers }) => {
const { addMockHandlers } = (window as any).MockServiceWorker;
addMockHandlers(...createHandlers());
});
}
// Export manifests - use mock repository if VITE_USE_MOCK_REPO is set
export const manifests = import.meta.env.VITE_USE_MOCK_REPO === 'on'
? (await import('../tests/mock-repo/mock/index.js')).manifests
: (await import('./manifests.js')).manifests;
| Variable | Value | Purpose |
|---|---|---|
VITE_EXAMPLE_PATH | /path/to/extension/Client | Path to extension directory |
VITE_UMBRACO_USE_MSW | on | Enable MSW for core Umbraco APIs |
VITE_USE_MOCK_REPO | on | Use mock repository instead of MSW handlers |
UMBRACO_CLIENT_PATH |
cd /path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
# MSW mode (uses your handlers for custom APIs)
VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_UMBRACO_USE_MSW=on npm run dev
# Mock repository mode (uses mock repository for custom APIs)
VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev
cd /path/to/extension/Client
# Set path to Umbraco client
export UMBRACO_CLIENT_PATH=/path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
# Run MSW tests
npm run test:msw
# Run mock repository tests
npm run test:mock-repo
Create tests/msw/playwright.config.ts:
import { defineConfig, devices } from '@playwright/test';
import { fileURLToPath } from 'url';
import { dirname, resolve } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const EXTENSION_PATH = resolve(__dirname, '../..');
const UMBRACO_CLIENT_PATH = process.env.UMBRACO_CLIENT_PATH;
if (!UMBRACO_CLIENT_PATH) {
throw new Error('UMBRACO_CLIENT_PATH environment variable is required');
}
const DEV_SERVER_PORT = 5176;
export default defineConfig({
testDir: '.',
testMatch: ['*.spec.ts'],
timeout: 60000,
expect: { timeout: 15000 },
fullyParallel: false,
workers: 1,
// Start dev server with extension and MSW enabled
webServer: {
command: `VITE_EXAMPLE_PATH=${EXTENSION_PATH} VITE_UMBRACO_USE_MSW=on npm run dev -- --port ${DEV_SERVER_PORT}`,
cwd: UMBRACO_CLIENT_PATH,
port: DEV_SERVER_PORT,
reuseExistingServer: !process.env.CI,
timeout: 120000,
},
use: {
baseURL: `http://localhost:${DEV_SERVER_PORT}`,
trace: 'on-first-retry',
screenshot: 'only-on-failure',
},
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
],
});
For mock-repo tests, change the command to include VITE_USE_MOCK_REPO=on:
command: `VITE_EXAMPLE_PATH=${EXTENSION_PATH} VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev -- --port ${DEV_SERVER_PORT}`,
import { type Page } from '@playwright/test';
async function navigateToSettings(page: Page) {
await page.goto('/section/settings');
await page.waitForLoadState('domcontentloaded');
await page.waitForSelector('umb-section-sidebar', { timeout: 30000 });
}
test('should display root tree items', async ({ page }) => {
await navigateToSettings(page);
await page.waitForSelector('umb-tree-item', { timeout: 15000 });
const treeItems = page.locator('umb-tree-item');
await expect(treeItems.first()).toBeVisible();
});
test('should expand tree item to show children', async ({ page }) => {
await navigateToSettings(page);
const expandableItem = page.locator('umb-tree-item').filter({ hasText: 'Group A' });
const expandButton = expandableItem.locator('button[aria-label="toggle child items"]');
await expandButton.click();
const childItem = page.locator('umb-tree-item').filter({ hasText: 'Child 1' });
await expect(childItem).toBeVisible({ timeout: 15000 });
});
| Document Name | URL Path |
|---|---|
| The Simplest Document | /section/content/workspace/document/edit/the-simplest-document-id |
| All properties | /section/content/workspace/document/edit/all-property-editors-document-id |
manifests array from src/index.tsVITE_EXAMPLE_PATH points to the Client directory[MSW] logs showing handler registrationSee tree-example in umbraco-backoffice-skills/examples/tree-example/Client/:
| Path | Description |
|---|---|
src/index.ts | Entry point with conditional manifest loading |
src/msw/handlers.ts | MSW handlers for custom API |
tests/mock-repo/ | Mock repository tests |
tests/msw/ | MSW tests |
cd tree-example/Client
export UMBRACO_CLIENT_PATH=/path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
npm run test:msw # Run MSW tests
npm run test:mock-repo # Run mock repository tests
MSW provides mock data for all backoffice APIs:
Weekly Installs
75
Repository
GitHub Stars
17
First Seen
Feb 4, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
github-copilot54
codex22
opencode21
cursor21
gemini-cli19
amp19
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
120,000 周安装
/path/to/Umbraco.Web.UI.Client |
| Path to Umbraco client (for Playwright) |