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();

---

属性构建器

向文档类型添加属性：

文本框属性

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