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

Two Mocking Approaches

两种模拟方式

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.

带有自定义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

环境变量

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

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

Run MSW tests

运行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 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`

文档名称	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/

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

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提供模拟数据：

文档、媒体、成员
文档类型、媒体类型、成员类型
数据类型、模板、样式表
用户、用户组、权限
语言、区域文化、字典项

umbraco-mocked-backoffice

Original

Translation

Umbraco Mocked Backoffice

Umbraco 模拟后台

When to Use

使用场景

Related Skills

相关技能

Two Mocking Approaches

两种模拟方式

Setup

配置步骤

Create Your Extension

创建扩展

Add Testing Dependencies

添加测试依赖

Directory Structure

目录结构

Entry Point (src/index.ts)

入口文件（src/index.ts）

Running Tests

运行测试

Environment Variables

环境变量

Manual Dev Server

手动启动开发服务器

MSW mode (uses your handlers for custom APIs)

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

Mock repository mode (uses mock repository for custom APIs)

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

Run Tests

运行测试

Set path to Umbraco client

设置Umbraco客户端路径

Run MSW tests

运行MSW测试

Run mock repository tests

运行模拟仓库测试

Playwright Config Example

Playwright配置示例

Test Patterns

测试模式

Navigation Helper

导航助手

Testing Tree Items

测试树状项

MSW Mock Document URLs

MSW模拟文档URL

Troubleshooting

故障排除

Extension not appearing

扩展未显示

Tests timeout waiting for elements

测试因等待元素超时

MSW handlers not intercepting requests

MSW处理器未拦截请求

Working Example

示例项目

What's Mocked?

已模拟的内容