Back to Details

umbraco-mocked-backoffice

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Mocked Backoffice

Umbraco 模拟后台

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.
状态： 该技能目前正在等待Umbraco的更新，以允许外部扩展使用模拟后台。此处记录的模式在Umbraco-CMS源代码仓库内运行时有效。
运行完整的Umbraco后台UI，所有API调用均已模拟 - 无需.NET后端。

When to Use

使用场景

  • Visually test extensions during development
  • Rapid iteration without backend deployment
  • Test extensions in realistic UI environment
  • Demonstrate extensions without infrastructure
  • CI/CD testing without backend setup
  • 开发期间对扩展进行可视化测试
  • 无需后端部署即可快速迭代
  • 在真实UI环境中测试扩展
  • 无需基础设施即可演示扩展
  • 无需搭建后端即可进行CI/CD测试

Related Skills

相关技能

  • umbraco-example-generator - Set up extensions for mocked backoffice (start here)
  • umbraco-testing - Master skill for testing overview
  • umbraco-unit-testing - Test extension logic in isolation
  • umbraco-e2e-testing - Test against a real Umbraco instance
  • umbraco-example-generator - 为模拟后台设置扩展（从这里开始）
  • umbraco-testing - 测试概述的核心技能
  • umbraco-unit-testing - 独立测试扩展逻辑
  • umbraco-e2e-testing - 在真实Umbraco实例上进行测试

Two Mocking Approaches

两种模拟方式

Extensions with custom APIs can use two mocking approaches:
ApproachUse CaseBest For
MSW HandlersNetwork-level API mockingTesting error handling, loading states, retries
Mock RepositoryApplication-level mockingTesting UI with predictable data (recommended)
Both approaches require MSW to be enabled (
VITE_UMBRACO_USE_MSW=on
) for core Umbraco APIs.
带有自定义API的扩展可以使用两种模拟方式：
方式使用场景最佳适用场景
MSW Handlers网络层面的API模拟测试错误处理、加载状态、重试机制
Mock Repository应用层面的模拟使用可预测数据测试UI（推荐）
两种方式都需要启用MSW（
VITE_UMBRACO_USE_MSW=on
）以处理Umbraco核心API。

Setup

配置步骤

Create Your Extension

创建扩展

Use the umbraco-example-generator skill to set up your extension:
Invoke: 
skill: umbraco-example-generator
This covers:
  • Cloning Umbraco-CMS repository
  • Extension structure and 
    src/index.ts
    requirements
  • Running with 
    VITE_EXAMPLE_PATH
    and 
    npm run dev
使用umbraco-example-generator技能来配置你的扩展：
调用方式：
skill: umbraco-example-generator
该技能包含以下内容：
  • 克隆Umbraco-CMS仓库
  • 扩展结构与
    src/index.ts
    的要求
  • 使用
    VITE_EXAMPLE_PATH
    和
    npm run dev
    运行项目

Add Testing Dependencies

添加测试依赖

json
{
  "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"
  }
}
bash
npm install
npx playwright install chromium
json
{
  "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"
  }
}
bash
npm install
npx playwright install chromium

Directory Structure

目录结构

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

Entry Point (src/index.ts)

入口文件（src/index.ts）

The entry point conditionally loads MSW handlers or mock manifests based on environment:
typescript
// 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;
入口文件会根据环境变量有条件地加载MSW处理器或模拟清单：
typescript
// 外部扩展加载的入口文件
// 在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;

Running Tests

运行测试

Environment Variables

环境变量

VariableValuePurpose
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
/path/to/Umbraco.Web.UI.Client
Path to Umbraco client (for Playwright)
变量值用途
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）

Manual Dev Server

手动启动开发服务器

bash
cd /path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
bash
cd /path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client

MSW mode (uses your handlers for custom APIs)

MSW模式（为自定义API使用你的处理器）

VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_UMBRACO_USE_MSW=on npm run dev
VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_UMBRACO_USE_MSW=on npm run dev

Mock repository mode (uses mock repository for custom APIs)

模拟仓库模式（为自定义API使用模拟仓库）

VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev
undefined
VITE_EXAMPLE_PATH=/path/to/extension/Client VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev
undefined

Run Tests

运行测试

bash
cd /path/to/extension/Client
bash
cd /path/to/extension/Client

Set path to Umbraco client

设置Umbraco客户端路径

export UMBRACO_CLIENT_PATH=/path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
export UMBRACO_CLIENT_PATH=/path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client

Run MSW tests

运行MSW测试

npm run test:msw
npm run test:msw

Run mock repository tests

运行模拟仓库测试

npm run test:mock-repo

---
npm run test:mock-repo

---

Playwright Config Example

Playwright配置示例

Create 
tests/msw/playwright.config.ts
:
typescript
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
:
typescript
command: `VITE_EXAMPLE_PATH=${EXTENSION_PATH} VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev -- --port ${DEV_SERVER_PORT}`,
创建
tests/msw/playwright.config.ts
：
typescript
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
：
typescript
command: `VITE_EXAMPLE_PATH=${EXTENSION_PATH} VITE_USE_MOCK_REPO=on VITE_UMBRACO_USE_MSW=on npm run dev -- --port ${DEV_SERVER_PORT}`,

Test Patterns

测试模式

Navigation Helper

导航助手

typescript
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 });
}
typescript
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 });
}

Testing Tree Items

测试树状项

typescript
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 });
});
typescript
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 });
});

MSW Mock Document URLs

MSW模拟文档URL

Document NameURL 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
文档名称URL路径
最简文档
/section/content/workspace/document/edit/the-simplest-document-id
包含所有属性
/section/content/workspace/document/edit/all-property-editors-document-id

Troubleshooting

故障排除

Extension not appearing

扩展未显示

  • Check that your extension exports a 
    manifests
    array from 
    src/index.ts
  • Check browser console for errors
  • Verify 
    VITE_EXAMPLE_PATH
    points to the 
    Client
    directory
  • 检查你的扩展是否从
    src/index.ts
    导出了
    manifests
    数组
  • 检查浏览器控制台是否有错误
  • 验证
    VITE_EXAMPLE_PATH
    指向的是
    Client
    目录

Tests timeout waiting for elements

测试因等待元素超时

  • Ensure the dev server is running with your extension loaded
  • Check the browser console for extension loading errors
  • Use longer timeouts (15000ms+) for initial element appearance
  • 确保开发服务器已运行且加载了你的扩展
  • 检查浏览器控制台是否有扩展加载错误
  • 为初始元素显示设置更长的超时时间（15000ms以上）

MSW handlers not intercepting requests

MSW处理器未拦截请求

  • Check console for 
    [MSW]
    logs showing handler registration
  • Verify handler URL patterns match the actual API calls
  • Use browser DevTools Network tab to see actual request URLs
  • 检查控制台中的
    [MSW]
    日志，确认处理器已注册
  • 验证处理器的URL模式与实际API调用匹配
  • 使用浏览器开发者工具的网络标签查看实际请求URL

Working Example

示例项目

See tree-example in 
umbraco-backoffice-skills/examples/tree-example/Client/
:
PathDescription
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
bash
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
查看
umbraco-backoffice-skills/examples/tree-example/Client/
中的tree-example：
路径描述
src/index.ts
带有条件清单加载的入口文件
src/msw/handlers.ts
自定义API的MSW处理器
tests/mock-repo/
模拟仓库测试
tests/msw/
MSW测试
bash
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  # 运行模拟仓库测试

What's Mocked?

已模拟的内容

MSW provides mock data for all backoffice APIs:
  • Documents, media, members
  • Document types, media types, member types
  • Data types, templates, stylesheets
  • Users, user groups, permissions
  • Languages, cultures, dictionary items
MSW为所有后台API提供模拟数据：
  • 文档、媒体、成员
  • 文档类型、媒体类型、成员类型
  • 数据类型、模板、样式表
  • 用户、用户组、权限
  • 语言、区域文化、字典项