umbraco-mocked-backoffice

Umbraco モックバックオフィス

ステータス: このスキルは現在、外部拡張機能がモックバックオフィスを使用できるようにするための Umbraco からの更新を待っています。ここに記載されているパターンは、Umbraco-CMS ソースリポジトリ内から実行する場合に機能します。

すべての API 呼び出しをモックした状態で Umbraco バックオフィス UI 全体を実行します - .NET バックエンドは不要です。

使用する場面

• 開発中に拡張機能を視覚的にテストする
• バックエンドをデプロイせずに迅速にイテレーションする
• リアルな UI 環境で拡張機能をテストする
• インフラストラクチャなしで拡張機能をデモする
• バックエンドのセットアップなしで CI/CD テストを行う

関連スキル

• umbraco-example-generator - モックバックオフィス用の拡張機能をセットアップします（ここから始めてください）
• umbraco-testing - テストの概要に関するマスタースキル
• umbraco-unit-testing - 拡張機能のロジックを分離してテストします
• umbraco-e2e-testing - 実際の Umbraco インスタンスに対してテストします

---

2 つのモックアプローチ

カスタム API を持つ拡張機能では、2 つのモックアプローチを使用できます:

アプローチ	ユースケース	最適な用途
MSW ハンドラー	ネットワークレベルの API モック	エラー処理、ローディング状態、リトライのテスト
モックリポジトリ	アプリケーションレベルのモック	予測可能なデータで UI をテストする（推奨）

どちらのアプローチでも、コア Umbraco API のために MSW を有効にする必要があります（VITE_UMBRACO_USE_MSW=on）。

---

セットアップ

拡張機能を作成する

umbraco-example-generator スキルを使用して拡張機能をセットアップします:

呼び出し: skill: umbraco-example-generator

これがカバーする内容:

• Umbraco-CMS リポジトリのクローン
• 拡張機能の構造と 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                # 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

---

エントリポイント (src/index.ts)

エントリポイントは、環境に基づいて MSW ハンドラーまたはモックマニフェストを条件付きで読み込みます:

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

---

テストの実行

自己完結型の外部サンプルサポート（自動）

Umbraco クライアントの外部のパスから拡張機能を読み込むには、クライアントが絶対パス VITE_EXAMPLE_PATH（Vite の /@fs/ 経由）をサポートすることに加えて、共有パッケージリゾルバーが必要です。これにより、@umbraco-cms/backoffice、lit、@umbraco-ui/uui がクライアントの単一のコピーに解決されます。リリース済みの標準 v18 は相対パス（./examples/...）のみをサポートします。

自己完結型を維持するため、このリポジトリのモック構成は Playwright の globalSetup/globalTeardown（plugins/umbraco-testing-skills/harness/mocked-backoffice/）を組み込みます。これは、開発サーバーが起動する前にそのサポートを UMBRACO_CLIENT_PATH のクライアントに注入し、その後で元に戻します（ファイルバックアップベース。すでにサポートがあるクライアントを検出した場合は何もしません）。したがって、CMS ブランチは不要で、ビルド済みの v18 クライアント（Umbraco.Web.UI.Client での npm ci）だけが必要です。

新しくパッチを適用したクライアントに対して初めて実行すると、依存関係が再最適化され、開発サーバーが一時的に再起動する場合があります（最初のナビゲーションが不安定になります）。構成では retries を設定してこれを吸収します。ウォーム状態での実行は安定しています。

環境変数

変数	値	目的
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 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

---

Playwright 構成の例

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'] },
    },
  ],
});

モックリポジトリのテストでは、コマンドに 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 });
});

MSW モックドキュメント URL

ドキュメント名	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 ディレクトリを指していることを確認してください

要素を待機してテストがタイムアウトする

• 拡張機能を読み込んだ状態で開発サーバーが実行されていることを確認してください
• ブラウザのコンソールで拡張機能の読み込みエラーを確認してください
• 初回の要素表示にはより長いタイムアウト（15000ms 以上）を使用してください

MSW ハンドラーがリクエストをインターセプトしない

• ハンドラーの登録を示す [MSW] ログがコンソールに出力されているか確認してください
• ハンドラーの URL パターンが実際の API 呼び出しと一致していることを確認してください
• ブラウザの DevTools の Network タブで実際のリクエスト URL を確認してください

---

動作する例

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        # Run MSW tests
npm run test:mock-repo  # Run mock repository tests

---

何がモックされるのか？

MSW はすべてのバックオフィス API にモックデータを提供します:

• ドキュメント、メディア、メンバー
• ドキュメントタイプ、メディアタイプ、メンバータイプ
• データタイプ、テンプレート、スタイルシート
• ユーザー、ユーザーグループ、権限
• 言語、カルチャ、ディクショナリ項目