Umbraco Test Builders

What is it?

The @umbraco/json-models-builders package provides fluent builder classes for creating Umbraco backoffice models. These builders simplify test data creation with sensible defaults and chainable configuration methods.

Documentation

• Package: @umbraco/json-models-builders
• Repository: https://github.com/umbraco/Umbraco.JsonModels.Builders
• Reference: /Users/philw/Projects/Umbraco.JsonModels.Builders

Related Skills

• umbraco-testing - Master skill for testing overview
• umbraco-e2e-testing - E2E testing (primary user of builders)
• umbraco-msw-testing - MSW testing (can use builders for mock data)

Installation

npm install @umbraco/json-models-builders

Builder Pattern

All builders follow this pattern:

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

Method Types

Core Builders

DocumentTypeBuilder

Create document types with properties, groups, and tabs:

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

Key Methods:

• withName(name) - Document type name
• withAlias(alias) - Document type alias
• withAllowAsRoot(bool) - Allow at content root
• withAllowCultureVariation(bool) - Enable variants
• AsElementType() - Mark as element type (for blocks)
• addGroup() - Add property group
• addTab() - Add tab
• withDefaultTemplate(template) - Set default template

ContentBuilder

Create content items:

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

Key Methods:

• withContentTypeAlias(alias) - Document type alias
• withTemplateAlias(alias) - Template alias
• withAction(action) - 'publishNew', 'save', etc.
• withParent(parentId) - Parent node ID
• addVariant() - Add content variant

MediaBuilder

Create media items:

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

Create data types:

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

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

Property Builders

Add properties to document types:

TextBox Property

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

Rich Text Property

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

Media Picker Property

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

Content Picker Property

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

Custom Data Type Property

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

Block List / Block Grid Builders

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 (for content)

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

User and Permission Builders

UserBuilder

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

const user = new UserBuilder()
  .withName('Test User')
  .withEmail('test@example.com')
  .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()

Template and Code Builders

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 Utility

Generate safe aliases from names:

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"

Complete Examples

Create Document Type with Properties

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

Create Element Type for Blocks

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

Create Content with Block List

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

All Available Builders (67 Total)

Main Builders

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

Data Type Builders

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

Property Builders

• 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