umbraco-test-builders

What this skill does

# 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

```bash
npm install @umbraco/json-models-builders
```

---

## Builder Pattern

All builders follow this pattern:

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

| Method Pattern | Purpose | Returns |
|----------------|---------|---------|
| `withXxx(value)` | Set a property | `this` (for chaining) |
| `addXxx()` | Add nested builder | Child builder |
| `done()` | Return to parent | Parent builder |
| `build()` | Generate final object | The model |

---

## Core Builders

### DocumentTypeBuilder

Create document types with properties, groups, and tabs:

```typescript
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:

```typescript
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:

```typescript
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:

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

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

### Rich Text Property

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

### Media Picker Property

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

### Content Picker Property

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

### Custom Data Type Property

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

---

## Block List / Block Grid Builders

### BlockListDataTypeBuilder

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

```typescript
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)

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

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

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

### UserGroupBuilder

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

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

---

## Template and Code Builders

### TemplateBuilder

```typescript
imp