umbraco-test-builders

Umbraco テストビルダー

これは何ですか？

@umbraco/json-models-builders パッケージは、Umbraco バックオフィスモデルを作成するための流暢なビルダークラスを提供します。これらのビルダーは、適切なデフォルト値とチェーン可能な構成メソッドにより、テストデータの作成を簡素化します。

ドキュメント

• パッケージ: @umbraco/json-models-builders
• リポジトリ: https://github.com/umbraco/Umbraco.JsonModels.Builders
• リファレンス: /Users/philw/Projects/Umbraco.JsonModels.Builders

関連スキル

• umbraco-testing - テスト概要のマスタースキル
• umbraco-e2e-testing - E2E テスト（ビルダーの主な利用者）
• umbraco-msw-testing - MSW テスト（モックデータにビルダーを使用可能）

---

インストール

npm install @umbraco/json-models-builders

---

ビルダーパターン

すべてのビルダーはこのパターンに従います：

const model = new SomeBuilder()
  .withProperty(value)        // Configure scalar properties
  .withOtherProperty(value)   // Chain multiple configurations
  .addChild()                 // Create nested builder
    .withChildProperty(value)
    .done()                   // Return to parent builder
  .build();                   // Generate final object

メソッドの種類

メソッドパターン	目的	戻り値
withXxx(value)	プロパティを設定	this（チェーン用）
addXxx()	ネストされたビルダーを追加	子ビルダー
done()	親に戻る	親ビルダー
build()	最終オブジェクトを生成	モデル

---

コアビルダー

DocumentTypeBuilder

プロパティ、グループ、タブを持つドキュメントタイプを作成します：

import { DocumentTypeBuilder } from '@umbraco/json-models-builders';

const documentType = new DocumentTypeBuilder()
  .withName('Article')
  .withAlias('article')
  .withAllowAsRoot(true)
  .withAllowCultureVariation(true)
  .addGroup()
    .withName('Content')
    .addTextBoxProperty()
      .withLabel('Title')
      .withAlias('title')
      .done()
    .addRichTextProperty()
      .withLabel('Body')
      .withAlias('body')
      .done()
    .done()
  .addGroup()
    .withName('SEO')
    .addTextBoxProperty()
      .withLabel('Meta Title')
      .withAlias('metaTitle')
      .done()
    .done()
  .build();

主要メソッド:

• withName(name) - ドキュメントタイプ名
• withAlias(alias) - ドキュメントタイプのエイリアス
• withAllowAsRoot(bool) - コンテンツルートとして許可
• withAllowCultureVariation(bool) - バリアントを有効化
• AsElementType() - 要素タイプとしてマーク（ブロック用）
• addGroup() - プロパティグループを追加
• addTab() - タブを追加
• withDefaultTemplate(template) - デフォルトテンプレートを設定

ContentBuilder

コンテンツアイテムを作成します：

import { ContentBuilder } from '@umbraco/json-models-builders';

const content = new ContentBuilder()
  .withContentTypeAlias('article')
  .withAction('publishNew')
  .withParent('-1') // Root
  .addVariant()
    .withName('My Article')
    .withCulture('en-US')
    .addProperty()
      .withAlias('title')
      .withValue('Hello World')
      .done()
    .addProperty()
      .withAlias('body')
      .withValue('<p>Article content</p>')
      .done()
    .done()
  .build();

主要メソッド:

• withContentTypeAlias(alias) - ドキュメントタイプのエイリアス
• withTemplateAlias(alias) - テンプレートのエイリアス
• withAction(action) - 'publishNew'、'save' など
• withParent(parentId) - 親ノード ID
• addVariant() - コンテンツバリアントを追加

MediaBuilder

メディアアイテムを作成します：

import { MediaBuilder } from '@umbraco/json-models-builders';

const media = new MediaBuilder()
  .withName('My Image')
  .withMediaTypeAlias('Image')
  .addProperty()
    .withAlias('umbracoFile')
    .withValue({ src: '/media/image.jpg' })
    .done()
  .build();

DataTypeBuilder

データタイプを作成します：

import { DataTypeBuilder } from '@umbraco/json-models-builders';

const dataType = new DataTypeBuilder()
  .withName('My Text Box')
  .withSaveNewAction()
  .build();

---

プロパティビルダー

ドキュメントタイプにプロパティを追加します：

TextBox プロパティ

documentTypeBuilder
  .addGroup()
    .withName('Content')
    .addTextBoxProperty()
      .withLabel('Title')
      .withAlias('title')
      .withDescription('Enter the page title')
      .withMandatory(true)
      .done()
    .done()

リッチテキストプロパティ

.addRichTextProperty()
  .withLabel('Body Text')
  .withAlias('bodyText')
  .done()

メディアピッカープロパティ

.addMediaPickerProperty()
  .withLabel('Featured Image')
  .withAlias('featuredImage')
  .done()

コンテンツピッカープロパティ

.addContentPickerProperty()
  .withLabel('Related Page')
  .withAlias('relatedPage')
  .done()

カスタムデータタイププロパティ

.addCustomProperty()
  .withLabel('Custom Field')
  .withAlias('customField')
  .withDataTypeId('your-datatype-id')
  .done()

---

ブロックリスト / ブロックグリッドビルダー

BlockListDataTypeBuilder

import { BlockListDataTypeBuilder } from '@umbraco/json-models-builders';

const blockList = new BlockListDataTypeBuilder()
  .withName('Content Blocks')
  .addBlock()
    .withContentElementTypeKey('hero-block-key')
    .withLabel('Hero Block')
    .done()
  .addBlock()
    .withContentElementTypeKey('text-block-key')
    .withLabel('Text Block')
    .done()
  .withMin(1)
  .withMax(10)
  .withUseLiveEditing(true)
  .build();

BlockGridDataTypeBuilder

import { BlockGridDataTypeBuilder } from '@umbraco/json-models-builders';

const blockGrid = new BlockGridDataTypeBuilder()
  .withName('Page Grid')
  .withGridColumns(12)
  .addBlock()
    .withContentElementTypeKey('row-block-key')
    .withLabel('Row')
    .withColumnSpanOptions([6, 12])
    .done()
  .addBlock()
    .withContentElementTypeKey('image-block-key')
    .withLabel('Image')
    .done()
  .build();

BlockListValueBuilder（コンテンツ用）

import { ContentBuilder, BlockListValueBuilder } from '@umbraco/json-models-builders';

const content = new ContentBuilder()
  .withContentTypeAlias('page')
  .addVariant()
    .withName('Home')
    .addProperty()
      .withAlias('blocks')
      .addBlockListValue()
        .addBlockListEntry()
          .withContentTypeKey('hero-block-key')
          .appendContentProperties('heading', 'Welcome')
          .appendContentProperties('subheading', 'To our site')
          .done()
        .addBlockListEntry()
          .withContentTypeKey('text-block-key')
          .appendContentProperties('text', 'Some content here')
          .done()
        .done()
      .done()
    .done()
  .build();

---

ユーザーと権限のビルダー

UserBuilder

import { UserBuilder } from '@umbraco/json-models-builders';

const user = new UserBuilder()
  .withName('Test User')
  .withEmail('[email protected]')
  .withUserGroups(['admin'])
  .build();

UserGroupBuilder

import { UserGroupBuilder } from '@umbraco/json-models-builders';

const userGroup = new UserGroupBuilder()
  .withName('Editors')
  .withAlias('editors')
  .withIcon('icon-users')
  .appendSection('content')
  .appendSection('media')
  .addDefaultPermissions()
    .withBrowseNode()
    .withCreate()
    .withUpdate()
    .withPublish()
    .done()
  .withSaveNew()
  .build();

PermissionsBuilder

userGroupBuilder
  .addNodePermissions()
    .forNode('content-node-id')
    .withBrowseNode()
    .withCreate()
    .withUpdate()
    .withDelete()
    .withPublish()
    .withUnpublish()
    .done()

---

テンプレートとコードのビルダー

TemplateBuilder

import { TemplateBuilder } from '@umbraco/json-models-builders';

const template = new TemplateBuilder()
  .withName('Article Template')
  .withAlias('articleTemplate')
  .withContent(`@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
<h1>@Model.Name</h1>`)
  .build();

StylesheetBuilder

import { StylesheetBuilder } from '@umbraco/json-models-builders';

const stylesheet = new StylesheetBuilder()
  .withName('main.css')
  .withContent('body { font-family: sans-serif; }')
  .build();

ScriptBuilder

import { ScriptBuilder } from '@umbraco/json-models-builders';

const script = new ScriptBuilder()
  .withName('main.js')
  .withContent('console.log("Hello");')
  .build();

---

AliasHelper ユーティリティ

名前から安全なエイリアスを生成します：

import { AliasHelper } from '@umbraco/json-models-builders';

// Convert to camelCase alias
AliasHelper.toAlias('My Page Type');
// Returns: "myPageType"

// Create safe alias with prefix/suffix
AliasHelper.toSafeAlias('My Page Type');
// Returns: "aMyPageTypea"

// Capitalize first character
AliasHelper.capitalize('hello');
// Returns: "Hello"

// Convert sentence to camelCase
AliasHelper.toCamelCase('My Awesome Example');
// Returns: "myAwesomeExample"

// Convert UUID to alias (removes dashes)
AliasHelper.uuidToAlias('123e4567-e89b-12d3-a456-426614174000');
// Returns: "123e4567e89b12d3a456426614174000"

---

完全な例

プロパティを持つドキュメントタイプを作成

import { DocumentTypeBuilder, AliasHelper } from '@umbraco/json-models-builders';

const name = 'Blog Post';
const alias = AliasHelper.toAlias(name);

const blogPost = new DocumentTypeBuilder()
  .withName(name)
  .withAlias(alias)
  .withAllowAsRoot(true)
  .withAllowCultureVariation(true)
  .addGroup()
    .withName('Content')
    .addTextBoxProperty()
      .withLabel('Title')
      .withAlias('title')
      .withMandatory(true)
      .done()
    .addTextBoxProperty()
      .withLabel('Author')
      .withAlias('author')
      .done()
    .addRichTextProperty()
      .withLabel('Body')
      .withAlias('body')
      .done()
    .done()
  .addGroup()
    .withName('Media')
    .addMediaPickerProperty()
      .withLabel('Featured Image')
      .withAlias('featuredImage')
      .done()
    .done()
  .build();

// Use in test
await umbracoApi.documentType.save(blogPost);

ブロック用の要素タイプを作成

const heroBlock = new DocumentTypeBuilder()
  .withName('Hero Block')
  .withAlias('heroBlock')
  .AsElementType() // Important for blocks!
  .addGroup()
    .withName('Content')
    .addTextBoxProperty()
      .withLabel('Heading')
      .withAlias('heading')
      .done()
    .addTextBoxProperty()
      .withLabel('Subheading')
      .withAlias('subheading')
      .done()
    .addMediaPickerProperty()
      .withLabel('Background Image')
      .withAlias('backgroundImage')
      .done()
    .done()
  .build();

ブロックリストを持つコンテンツを作成

const pageContent = new ContentBuilder()
  .withContentTypeAlias('landingPage')
  .withAction('publishNew')
  .addVariant()
    .withName('Landing Page')
    .addProperty()
      .withAlias('pageTitle')
      .withValue('Welcome')
      .done()
    .addProperty()
      .withAlias('contentBlocks')
      .addBlockListValue()
        .addBlockListEntry()
          .withContentTypeKey(heroBlockKey)
          .appendContentProperties('heading', 'Welcome to Our Site')
          .appendContentProperties('subheading', 'Discover what we offer')
          .done()
        .addBlockListEntry()
          .withContentTypeKey(textBlockKey)
          .appendContentProperties('text', '<p>More content here...</p>')
          .done()
        .done()
      .done()
    .done()
  .build();

---

利用可能なすべてのビルダー（合計 67 個）

メインビルダー

• DocumentTypeBuilder、ContentBuilder、MediaBuilder
• TemplateBuilder、StylesheetBuilder、ScriptBuilder
• DataTypeBuilder、MacroBuilder、PackageBuilder
• UserBuilder、UserGroupBuilder
• PartialViewBuilder、PartialViewMacroBuilder
• DomainBuilder、WebhookBuilder

データタイプビルダー

• TextBoxDataTypeBuilder、DropDownDataTypeBuilder
• LabelDataTypeBuilder、SliderDataTypeBuilder
• BlockListDataTypeBuilder、BlockGridDataTypeBuilder
• GridDataTypeBuilder、CheckBoxListDataTypeBuilder
• ApprovedColorPickerDataTypeBuilder、FormPickerDataTypeBuilder

プロパティビルダー

• TextBoxDocumentTypePropertyBuilder
• RichTextDocumentTypePropertyEditor
• MediaPickerDocumentTypePropertyBuilder
• ContentPickerPropertyBuilder
• UrlPickerPropertyBuilder
• DropDownDocumentTypePropertyBuilder
• CustomDocumentTypePropertyBuilder

Block Builders

• BlockListValueBuilder, BlockListEntryBuilder
• BlockGridValueBuilder, BlockGridEntryBuilder
• BlockGridLayoutBuilder, BlockGridAreaBuilder
• BlockGridItemsBuilder, BlockGridBlocksBuilder

Permission Builders

• PermissionsBuilder, NodePermissionBuilder
• NodePermissionCollectionBuilder

Other Builders

• DocumentTypeGroupBuilder, DocumentTypeTabBuilder
• ContentVariantBuilder, ContentVariantPropertyBuilder
• MediaFileBuilder, MediaPropertyBuilder
• WebhookEventBuilder, WebhookHeaderBuilder
• GridLayoutBuilder, GridRowConfigBuilder, GridAreaBuilder