TST_Builder.Builder

Class

global inherited sharing class TST_Builder.Builder

A fluid builder for configuring and creating SObject records. Obtain an instance via TST_Builder.of(SObjectType).

Since: 1.0

---

Methods

Method	Description
global SObject build()	Executes the build operation and creates a single SObject record.
global List buildList()	Executes the build operation and creates a list of SObject records.
global TST_Builder.Builder withChildren(SObjectType childType, Integer count)	Adds child records to the parent being built without field overrides.
global TST_Builder.Builder withChildren(SObjectType childType, Integer count, Map<SObjectField, Object> overrides)	Adds child records to the parent being built using SObjectField tokens.
global TST_Builder.Builder withChildren(SObjectType childType, Integer count, Map<String, Object> overrides)	Adds child records to the parent being built using String field names.
global TST_Builder.Builder withChildren(String relationshipName, TST_Builder.Builder childBuilder)	Adds child records using a pre-configured Builder instance with explicit relationship name.
global TST_Builder.Builder withChildren(TST_Builder.Builder childBuilder)	Adds child records using a pre-configured Builder instance with auto-detected relationship name.
global TST_Builder.Builder withCount(Integer count)	Sets the number of SObject records to create when calling buildList().
global TST_Builder.Builder withCycle(SObjectField field, List<Object> values)	Assigns a list of values that cycle across records built by buildList().
global TST_Builder.Builder withCycle(String fieldName, List<Object> values)	Assigns a list of values that cycle across records built by buildList().
global TST_Builder.Builder withDefaultedField(SObjectField field)	Specifies an optional field to populate with a default value using an SObjectField token.
global TST_Builder.Builder withDefaultedField(String fieldName)	Specifies an optional field to populate with a default value, even though it is not marked as required.
global TST_Builder.Builder withDefaultedFields(List<Object> fields)	Specifies a list of optional fields to populate with default values, even though they are not marked as required.
global TST_Builder.Builder withOptionalField(SObjectField field)	Specifies a field to treat as optional using an SObjectField token, preventing the factory from auto-populating it as a required field.
global TST_Builder.Builder withOptionalField(String fieldName)	Specifies a field to treat as optional, preventing the factory from auto-populating it as a required field.
global TST_Builder.Builder withOptionalFields(List<Object> fields)	Specifies a list of fields to treat as optional, preventing the factory from auto-populating them as required fields.
global TST_Builder.Builder withoutInsertion()	Configures the build to not insert the records into the database.
global TST_Builder.Builder withoutInsertion(Boolean withMockIds)	Configures the build to not insert the records into the database, with an option to generate mock IDs for the entire object graph.
global TST_Builder.Builder withOverride(SObjectField field, Object value)	Applies a specific field value override using an SObjectField token.
global TST_Builder.Builder withOverride(String fieldName, Object value)	Applies a specific field value override.
global TST_Builder.Builder withOverrides(Map<SObjectField, Object> overrides)	Applies a map of specific field values using SObjectField tokens, overriding defaults.
global TST_Builder.Builder withOverrides(Map<String, Object> overrides)	Applies a map of specific field values, overriding defaults.
global TST_Builder.Builder withRecordType(String recordTypeDeveloperName)	Sets the Record Type for the SObject(s) to be built, using the Record Type's DeveloperName.

---

Method Details

build

global SObject build()

Executes the build operation and creates a single SObject record. If withCount() was called, this method still only returns one record.

Returns: SObject - The created SObject record (inserted by default unless withoutInsertion() was called).

Since: 1.0

Example:

// Build and insert a single Account
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withOverride('Name', 'Test Account')
	.build();
Assert.isNotNull(account.Id);

buildList

global List<SObject> buildList()

Executes the build operation and creates a list of SObject records. The number of records is determined by the value passed to withCount() (defaults to 1).

Returns: SObject - A list of the created SObject records (inserted by default unless withoutInsertion() was called).

Since: 1.0

Example:

// Build and insert 5 Contact records
List<Contact> contacts = (List<Contact>)TST_Builder.of(Contact.SObjectType)
	.withCount(5)
	.withOverride('LastName', 'Smith')
	.buildList();
Assert.areEqual(5, contacts.size());
Assert.isNotNull(contacts[0].Id);

withChildren

global TST_Builder.Builder withChildren(SObjectType childType, Integer count)

Adds child records to the parent being built without field overrides. The simplest way to add child records - relationship name is auto-detected. All child fields will use framework defaults.

Parameters:

• childType (SObjectType) - The SObjectType of the child records
• count (Integer) - Number of child records to create

Returns: TST_Builder.Builder - Builder for method chaining

Since: 1.0

Example:

Account account = (Account)TST_Builder.of(Account.SObjectType)
    .withOverride(Account.Name, 'ACME Corp')
    .withChildren(Contact.SObjectType, 3)
    .build();
Assert.areEqual(3, account.Contacts.size());

withChildren

global TST_Builder.Builder withChildren(SObjectType childType, Integer count, Map<SObjectField, Object> overrides)

Adds child records to the parent being built using SObjectField tokens. The child records will be assigned to the appropriate relationship field.

Parameters:

• childType (SObjectType) - The SObjectType of the child records
• count (Integer) - Number of child records to create
• overrides (Map) - Field overrides for child records using SObjectField tokens

Returns: TST_Builder.Builder - Builder for method chaining

Since: 1.0

Example:

Account account = (Account)TST_Builder.of(Account.SObjectType)
    .withOverride(Account.Name, 'ACME Corp')
    .withChildren(Contact.SObjectType, 3, new Map<SObjectField, Object>{
        Contact.FirstName => 'John',
        Contact.LastName => 'Doe'
    })
    .build();
Assert.areEqual(3, account.Contacts.size());

withChildren

global TST_Builder.Builder withChildren(SObjectType childType, Integer count, Map<String, Object> overrides)

Adds child records to the parent being built using String field names. The child records will be assigned to the appropriate relationship field.

Parameters:

• childType (SObjectType) - The SObjectType of the child records
• count (Integer) - Number of child records to create
• overrides (Map) - Field overrides for child records using String field names

Returns: TST_Builder.Builder - Builder for method chaining

Since: 1.0

Example:

Account account = (Account)TST_Builder.of(Account.SObjectType)
    .withOverride('Name', 'ACME Corp')
    .withChildren(Contact.SObjectType, 2, new Map<String, Object>{
        'LastName' => 'Smith'
    })
    .build();

withChildren

global TST_Builder.Builder withChildren(String relationshipName, TST_Builder.Builder childBuilder)

Adds child records using a pre-configured Builder instance with explicit relationship name. EDGE CASE ONLY: Use this variant when there are multiple relationships between the same parent and child types (e.g., self-referential with multiple lookup fields, or objects with multiple lookups to the same parent). For most cases, use withChildren(Builder) which auto-detects the relationship name.

Parameters:

• relationshipName (String) - The child relationship name (e.g., 'Contacts', 'Opportunities', 'PrimaryContacts__r')
• childBuilder (TST_Builder.Builder) - A pre-configured Builder instance for the child records

Returns: TST_Builder.Builder - Builder for method chaining

Since: 1.0

Example:

// Edge case: Foobar__c has TWO lookup fields to Contact (PrimaryContact__c, SecondaryContact__c)
Foobar__c foobar = (Foobar__c)TST_Builder.of(Foobar__c.SObjectType)
    .withChildren('PrimaryContacts__r',
        TST_Builder.of(Contact.SObjectType).withCount(2)
    )
    .withChildren('SecondaryContacts__r',
        TST_Builder.of(Contact.SObjectType).withCount(1)
    )
    .build();

withChildren

global TST_Builder.Builder withChildren(TST_Builder.Builder childBuilder)

Adds child records using a pre-configured Builder instance with auto-detected relationship name. The relationship name is automatically determined from the child Builder's SObjectType. Allows for complex child record configuration using fluent Builder API.

Parameters:

• childBuilder (TST_Builder.Builder) - A pre-configured Builder instance for the child records

Returns: TST_Builder.Builder - Builder for method chaining

Since: 1.0

Example:

Account account = (Account)TST_Builder.of(Account.SObjectType)
    .withChildren(
        TST_Builder.of(Opportunity.SObjectType)
            .withCount(2)
            .withOverride(Opportunity.Name, 'Big Deal')
            .withOverride(Opportunity.StageName, 'Prospecting')
    )
    .build();

withCount

global TST_Builder.Builder withCount(Integer count)

Sets the number of SObject records to create when calling buildList().

Parameters:

• count (Integer) - The number of records to create.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build 10 Account records and insert them
List<Account> accounts = (List<Account>)TST_Builder.of(Account.SObjectType)
	.withCount(10)
	.buildList();
Assert.areEqual(10, accounts.size());

withCycle

global TST_Builder.Builder withCycle(SObjectField field, List<Object> values)

Assigns a list of values that cycle across records built by buildList(). When more records are built than values provided, the values repeat from the beginning.

Parameters:

• field (SObjectField) - The SObjectField token of the field to cycle.
• values (List) - The list of values to cycle through. Must not be null or empty.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

List<SObject> foobars = TST_Builder.of(Foobar__c.SObjectType)
    .withCycle(Foobar__c.Picklist__c, new List<Object>{'Alpha', 'Beta', 'Gamma'})
    .withCount(6)
    .withoutInsertion()
    .buildList();
// Alpha, Beta, Gamma, Alpha, Beta, Gamma

withCycle

global TST_Builder.Builder withCycle(String fieldName, List<Object> values)

Assigns a list of values that cycle across records built by buildList(). When more records are built than values provided, the values repeat from the beginning.

Parameters:

• fieldName (String) - The API name of the field to cycle.
• values (List) - The list of values to cycle through. Must not be null or empty.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

List<SObject> foobars = TST_Builder.of(Foobar__c.SObjectType)
    .withCycle('Picklist__c', new List<Object>{'Alpha', 'Beta', 'Gamma'})
    .withCount(6)
    .withoutInsertion()
    .buildList();
// Alpha, Beta, Gamma, Alpha, Beta, Gamma

withDefaultedField

global TST_Builder.Builder withDefaultedField(SObjectField field)

Specifies an optional field to populate with a default value using an SObjectField token. This provides compile-time checking for field names.

Parameters:

• field (SObjectField) - The SObjectField token of the field.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account with type-safe defaulted fields
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withDefaultedField(Account.Description)
	.withDefaultedField(Account.Industry)
	.withoutInsertion()
	.build();

withDefaultedField

global TST_Builder.Builder withDefaultedField(String fieldName)

Specifies an optional field to populate with a default value, even though it is not marked as required.

Parameters:

• fieldName (String) - The API name of the field.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account with Description field automatically populated
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withDefaultedField('Description')
	.withDefaultedField('Industry')
	.withoutInsertion()
	.build();

withDefaultedFields

global TST_Builder.Builder withDefaultedFields(List<Object> fields)

Specifies a list of optional fields to populate with default values, even though they are not marked as required.

Parameters:

• fields (List) - A list of fields (SObjectField tokens or String API names).

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account with optional fields automatically populated
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withDefaultedFields(new List<Object>{ 'Description', 'Industry', 'Website' })
	.withoutInsertion()
	.build();

withOptionalField

global TST_Builder.Builder withOptionalField(SObjectField field)

Specifies a field to treat as optional using an SObjectField token, preventing the factory from auto-populating it as a required field. This provides compile-time checking for field names.

Parameters:

• field (SObjectField) - The SObjectField token of the field to mark as optional.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account without populating the Name field using type-safe field reference
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withOptionalField(Account.Name)
	.withoutInsertion()
	.build();
Assert.isNull(account.Name);

withOptionalField

global TST_Builder.Builder withOptionalField(String fieldName)

Specifies a field to treat as optional, preventing the factory from auto-populating it as a required field.

Parameters:

• fieldName (String) - The API name of the field to mark as optional.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account without populating the Name field (normally required)
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withOptionalField('Name')
	.withoutInsertion()
	.build();
Assert.isNull(account.Name);

withOptionalFields

global TST_Builder.Builder withOptionalFields(List<Object> fields)

Specifies a list of fields to treat as optional, preventing the factory from auto-populating them as required fields.

Parameters:

• fields (List) - A list of fields (SObjectField tokens or String API names).

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account without populating multiple normally-required fields
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withOptionalFields(new List<Object>{ 'Name', Account.Type })
	.withoutInsertion()
	.build();

withoutInsertion

global TST_Builder.Builder withoutInsertion()

Configures the build to not insert the records into the database. By default, records are inserted. Use this when you need in-memory records for testing without DML operations.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account in memory without inserting it
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withOverride('Name', 'Test Account')
	.withoutInsertion()
	.build();
Assert.isNull(account.Id);

withoutInsertion

global TST_Builder.Builder withoutInsertion(Boolean withMockIds)

Configures the build to not insert the records into the database, with an option to generate mock IDs for the entire object graph. Use this when you need in-memory records with IDs for query mocking.

Parameters:

• withMockIds (Boolean) - If true, generates unique mock IDs for all records in the graph (parents and children). Foreign key fields on children are automatically set to reference their parent's mock ID.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build mock Account with Contacts - all with generated IDs
Account mockAccount = (Account)TST_Builder.of(Account.SObjectType)
	.withOverride(Account.Name, 'Mock Account')
	.withChildren(Contact.SObjectType, 3, new Map<SObjectField, Object>{
		Contact.LastName => 'Mock Contact'
	})
	.withoutInsertion(true)
	.build();
Assert.isNotNull(mockAccount.Id, 'Parent should have mock ID');
Assert.areEqual(3, mockAccount.Contacts.size());
Assert.isNotNull(mockAccount.Contacts[0].Id, 'Children should have mock IDs');
Assert.areEqual(mockAccount.Id, mockAccount.Contacts[0].AccountId, 'FK should reference parent');
// Register for query mocking
QRY_Builder.setMock(Account.SObjectType, new List<Account>{mockAccount});

withOverride

global TST_Builder.Builder withOverride(SObjectField field, Object value)

Applies a specific field value override using an SObjectField token. This provides compile-time checking for field names.

Parameters:

• field (SObjectField) - The SObjectField token of the field.
• value (Object) - The override value.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account with type-safe field overrides
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withOverride(Account.Name, 'Test Account')
	.withOverride(Account.AnnualRevenue, 1000000)
	.withoutInsertion()
	.build();

withOverride

global TST_Builder.Builder withOverride(String fieldName, Object value)

Applies a specific field value override.

Parameters:

• fieldName (String) - The API name of the field.
• value (Object) - The override value.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account with a single field override
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withOverride('Name', 'Test Account')
	.withOverride('Phone', '555-9999')
	.withoutInsertion()
	.build();

withOverrides

global TST_Builder.Builder withOverrides(Map<SObjectField, Object> overrides)

Applies a map of specific field values using SObjectField tokens, overriding defaults. This provides compile-time checking for field names.

Parameters:

• overrides (Map) - A map of SObjectField tokens to their override values.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

Account account = (Account)TST_Builder.of(Account.SObjectType)
.withOverrides(new Map<SObjectField, Object>
   {
		Account.Name => 'Token Account',
		Account.Phone => '111-222-3333'
	})
.withoutInsertion()
.build();

withOverrides

global TST_Builder.Builder withOverrides(Map<String, Object> overrides)

Applies a map of specific field values, overriding defaults.

Parameters:

• overrides (Map) - A map of field names to their override values.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Since: 1.0

Example:

// Build an Account with multiple field overrides
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withOverrides(new Map<String, Object>
	{
		'Name' => 'Acme Corp',
		'Phone' => '555-1234',
		'Industry' => 'Technology'
	})
	.withoutInsertion()
	.build();

withRecordType

global TST_Builder.Builder withRecordType(String recordTypeDeveloperName)

Sets the Record Type for the SObject(s) to be built, using the Record Type's DeveloperName.

Parameters:

• recordTypeDeveloperName (String) - The DeveloperName of the Record Type.

Returns: TST_Builder.Builder - This Builder instance for further chaining.

Throws:

• IllegalArgumentException - if the Record Type DeveloperName is not found; ignores blank DeveloperName's

Since: 1.0

Example:

// Build an Account with a specific record type
Account account = (Account)TST_Builder.of(Account.SObjectType)
	.withRecordType('Enterprise_Account')
	.withOverride('Name', 'Enterprise Corp')
	.withoutInsertion()
	.build();