Test Data - Guide
Who this page is for: developers who build the records their Apex unit tests run against (single records, relationships, mock Ids and bulk data), and the architects who give a whole team one short, consistent way to set up tests.
New to it? Try the Test Data Fast Start first: a full build-and-test cycle, plus TST_Mock for query testing with no saved records. Deciding whether to use KernDX? See Why KernDX.
Copy this first
// Build and insert a single Account; required fields are auto-populated
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Industry, 'Technology')
.build();What this does: saves one account in your test with Industry set to Technology. You name only the fields your test checks, and the builder fills every other required field (such as Name) with a valid value. To keep the record in memory without saving it, add .withoutInsertion() before .build().
Read next: Many records at once, Records that are not saved, A parent with its children, Shared setup for your team.
Quick Navigation
| I need to... | Go to... |
|---|---|
| Set several fields at once, or a field whose name is only known at run time | Token Maps vs String Maps |
| Fill in a field that is not required | Defaulting Optional Fields |
| Leave a required field empty | Marking Fields Optional |
| Set a record type | Record Types |
| Build many records with one save | Bulk Creation |
| Build records without saving them, with or without an Id | Insertion Modes |
| Build a parent with its children | Relationships |
| Create a test user, or give users a permission set | Users and Permission Sets |
| Turn a feature flag on for a test | Feature Flags |
| Test a trigger action or a validation rule | Framework Metadata: Triggers and Validations |
| Test a masking rule, or other behaviour set up by custom metadata records | Custom Metadata Records |
| Check what a test logged | Logger Configuration |
| Fill a sandbox or scratch org with records to click through | How do I seed a sandbox or scratch org? |
| Change the values the builder fills in | Extending the Defaults |
| Test an aggregate query, or step outside the builder | How to opt out |
| Look up every builder method | Layer 1: TST_Builder |
| Look up every factory method | Layer 2: TST_Factory |
| Avoid the common mistakes | Anti-Patterns |
| See why KernDX is worth using | Why KernDX: the test data example |
Quick Start
Pick the class that fits the records your test needs. No custom class is required for any of them.
- Records of any type, saved or kept in memory:
TST_Builderdirectly, as in the sample below. - A user, a permission set assignment or a feature flag, set up the same way in every test:
TST_Factory, see The Factory Pattern. - Records that a
kern.QRY_Builderquery returns, with nothing saved:kern.TST_Mock, see the Test Data Fast Start.
// Build and insert a single Account; required fields are auto-populated
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Industry, 'Technology')
.build();
System.debug('Id: ' + account.Id + ', Industry: ' + account.Industry);build() returns one record (saved to the database by default). buildList() returns a List<SObject> and respects withCount(n). Cast the result to your concrete type.
Namespaces in code samples:
kern.on a class andkern__on an object, field, or metadata type mark the managed package's namespace. On the managed package, framework references need those prefixes even where a sample omits them; repackaged under your own namespace, replacekern/kern__with your prefix; on an unmanaged deploy, drop them. See How to read the code samples.
What problem does this solve?
Every Apex unit test needs example records to run against, and setting them up by hand is slow and fragile. You fill in fields the test does not care about, that setup breaks every time a field is renamed, and saving many records inside a loop quickly hits Salesforce's safety limits.
This layer builds those records for you. You name only the fields your test actually checks, and it fills in the rest, then either saves the records or keeps them in memory.
Use it whenever a test needs records. A plain new Account(...) is fine only for a record the test never saves, such as an argument it hands straight to a method.
Mental model
Think of it as ordering a coffee. You say what you actually care about (a flat white, oat milk), and the barista fills in everything else (cup, lid, water, machine settings) to defaults so the order is complete.
The builder works the same way: you name the few fields your test asserts on, and it supplies valid values for the rest so the record saves.
Use this when
- a test needs records and you only care about a handful of fields on them
- you need many records at once, saved in a single statement, to stay within Salesforce's limits
- you want records in memory (with or without an Id) so the test never touches the database
- you need a parent and its children built and saved together as one all-or-nothing unit
- the whole team should set up the same kind of record (a user on a profile, an active flag) the same way
- you want a sandbox or scratch org filled with realistic records to click through, built the same way as your test data
Don't use this when
- you need an
AggregateResultobject itself: it has no public constructor and cannot be built. For an aggregate query you run throughkern.QRY_Builder, register the rows it returns instead (see Mocking an aggregate query)
What is it?
The layer has two classes that work together. You configure each with short chained calls, then one call builds the record and returns it.
TST_Builderis the primary tool. It works for any SObject and handles overrides, bulk creation, cycling values across records, parent-child relationships, and three ways of saving (or not saving) the record.TST_Factoryis a convenience layer on top. It offers ready-made builders for records nearly every test needs (users, permission set assignments, feature flags), plus builders for API call records, API settings and content versions. Trigger settings and validation rules are not built by the factory: you deploy them as XML.
From your org's Apex, call them with the kern. namespace prefix, for example kern.TST_Builder and kern.TST_Factory: they are global classes in a managed package. The framework source is also available if you build and manage the package yourself.
What this layer does, and what it does not:
- It only builds records (and optionally saves them) for tests. It does not run production business logic, and most of it is meant to be called from test code (
@IsTest).TST_Builderand theTST_Factorymethods run from anonymous Apex and from an@IsTestclass in your org. That is also how you fill a sandbox with records to click through (see How do I seed a sandbox or scratch org?).- Framework configuration records for your tests (trigger settings, validation rules, masking) are deployed as
CustomMetadatarecords via XML (see Framework Metadata).
Building Records
These examples use Account and Contact, but every method works for any SObject, standard or custom.
A Single Record
// Inserted by default; required fields auto-populated
Account account = (Account)kern.TST_Builder.of(Account.SObjectType).build();
System.debug('Name: ' + account.Name); // randomly generated
System.debug('Id: ' + account.Id); // populated because the record was insertedOverriding Fields
Override only the fields the test cares about, with withOverride. Everything else the test doesn't name is either auto-populated (if required) or left null.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Name, 'Acme Corp')
.withOverride(Account.Industry, 'Technology')
.build();
Assert.areEqual('Acme Corp', account.Name, 'Name override should apply');Token Maps vs String Maps
When you want to set several fields at once, pass a map to withOverrides. Prefer the field-token form (SObjectField) so the compiler catches a misspelled or renamed field before the test runs. Use the String form only when the field name is not known until the test actually runs.
// Type-safe: field-name typos are caught at compile time
Account tokenForm = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverrides(new Map<SObjectField, Object>
{
Account.Name => 'Acme Corp',
Account.Industry => 'Technology',
Account.AnnualRevenue => 5000000
})
.build();
// String form: useful when the field name is dynamic
Account stringForm = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverrides(new Map<String, Object>
{
'Name' => 'Beta Corp',
'Industry' => 'Finance'
})
.build();Building by API Name
When the SObject type itself is dynamic, start from the API name. An invalid name throws an IllegalArgumentException with a descriptive message.
List<SObject> records = kern.TST_Builder.of('Foobar__c')
.withCount(5)
.buildList();Defaulting Optional Fields
By default the builder fills in only the fields Salesforce requires. Sometimes your test reads a field that is not required, and you want it populated too (for example, to exercise code that reads it). List those fields with withDefaultedField or withDefaultedFields.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withDefaultedField(Account.Description)
.withDefaultedField(Account.Industry)
.withoutInsertion()
.build();
Assert.isNotNull(account.Description, 'Description should be auto-populated');Marking Fields Optional
Sometimes you want a normally-required field left empty, perhaps to test how your code handles a missing value. Tell the builder to leave that field alone, and it comes back null.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOptionalField(Account.Name)
.withoutInsertion()
.build();
Assert.isNull(account.Name, 'Name should be left unpopulated');
withOptionalFieldonly stops the builder from filling the field in. If the field is genuinely required to save the record, inserting it will still fail. So use this together withwithoutInsertion(), or supply the value some other way.
Record Types
When a record needs a specific record type, set it by its developer name with withRecordType(developerName). An unknown developer name throws an IllegalArgumentException. A blank name is ignored.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withRecordType('Enterprise_Account')
.withOverride(Account.Name, 'Enterprise Corp')
.build();In your org a packaged record type may not be assigned to the running profile. If a build fails with
INVALID_CROSS_REFERENCE_KEYonRecordTypeId, confirm the record type is available to the running user, or pass a blank developer name to fall back to the master record type.
Bulk Creation
withCount and buildList
Tests often need many records, and saving them one at a time quickly hits Salesforce's per-transaction limits. withCount(n) followed by buildList() creates n records with a single DML statement, which keeps you safely within those limits. (build() always returns exactly one record, no matter what withCount says.)
List<Account> accounts = (List<Account>)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Industry, 'Technology')
.withCount(200)
.buildList();
Assert.areEqual(200, accounts.size(), 'Should build 200 accounts in one DML statement');Cycling Values Across Records
withCycle(field, values) rotates your list of values across the records that buildList() produces, so one batch covers several variations of one field (say a few different industries) without a separate test method for each.
- If there are more records than values, the values repeat from the start.
- The value list must not be null or empty.
List<SObject> records = kern.TST_Builder.of(Account.SObjectType)
.withCycle(Account.Industry, new List<Object> {'Technology', 'Finance', 'Healthcare'})
.withCount(6)
.buildList();
// Industries: Technology, Finance, Healthcare, Technology, Finance, HealthcareInsertion Modes
Pick one of three modes, depending on whether the record needs to reach the database and whether your code needs an Id on it (Choosing a Mode compares them). Not every test needs to save its records: some only read fields, so saving them is wasted time and governor-limit cost.
Insert (Default)
Without withoutInsertion(), records are inserted and come back with real Ids.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType).build();
Assert.isNotNull(account.Id, 'Inserted record has a real Id');In-Memory, No Id
withoutInsertion() builds the record in memory with no DML and no Id. Use it when the code under test only works with the record's fields and never needs an Id or a database round-trip. This is the fastest option and the easiest on governor limits.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Name, 'In-Memory Co')
.withoutInsertion()
.build();
Assert.isNull(account.Id, 'No insertion means no Id');In-Memory with Mock Ids
Some code needs an Id to work (it checks record.Id != null, uses the Id as a map key, or registers the record for query mocking) but you still do not want to touch the database. withoutInsertion(true) builds in memory but stamps a valid 18-character mock Id so that code is satisfied.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Name, 'Mock Corp')
.withoutInsertion(true)
.build();
Assert.isNotNull(account.Id, 'Mock Id is generated without DML');Choosing a Mode
| Mode | DML | Id | Use when |
|---|---|---|---|
| (default) | ✅ | Real | The test exercises real persistence, queries, triggers, or sharing. |
withoutInsertion() | ❌ | null | The code under test only reads fields (no Id, no database needed). |
withoutInsertion(true) | ❌ | Mock | The code checks Id != null, keys by Id, or registers a query mock. |
Custom metadata and read-only fields: custom metadata types (
*__mdt) cannot be inserted via DML, so the framework builds them in memory. Read-only and system fields are applied through a serialize/deserialize step so they appear populated on an in-memory record even though Apex would normally reject setting them directly.
Relationships
The builder constructs a whole parent-child graph for you, so you never wire the foreign keys by hand.
| You build it | What you get |
|---|---|
| Saved (default) | Parent and children commit together as one all-or-nothing unit (a Unit of Work): they all save, or none do |
| In memory | The child relationship is filled in, so it reads back just like a subquery result |
Adding Child Records
The simplest form takes a child type and a count. The framework works out the relationship name for you from the schema.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Name, 'ACME Corp')
.withChildren(Contact.SObjectType, 3)
.build();
Assert.areEqual(3, account.Contacts.size(), 'Three child contacts should be attached');Add child field overrides with the map overloads (token or string form):
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Name, 'ACME Corp')
.withChildren(Contact.SObjectType, 3, new Map<SObjectField, Object>
{
Contact.LastName => 'Mock Contact'
})
.build();Child Builders
For richer child configuration, pass a fully-configured child Builder. The relationship name is auto-detected from the child's SObject type.
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withChildren(
kern.TST_Builder.of(Opportunity.SObjectType)
.withCount(2)
.withOverride(Opportunity.Name, 'Big Deal')
.withOverride(Opportunity.StageName, 'Prospecting')
)
.build();Explicit Relationship Names
When parent and child share more than one relationship (for example, two lookup fields from the same child to the same parent), auto-detection cannot choose for you and throws an IllegalArgumentException listing the candidates. Pass the relationship name explicitly:
Foobar__c foobar = (Foobar__c)kern.TST_Builder.of(Foobar__c.SObjectType)
.withChildren('PrimaryContacts__r',
kern.TST_Builder.of(Contact.SObjectType).withCount(2))
.withChildren('SecondaryContacts__r',
kern.TST_Builder.of(Contact.SObjectType).withCount(1))
.build();Mock Ids Across a Graph
When you call withoutInsertion(true) on the parent, the builder generates mock Ids for the entire graph (parents and children) and connects each child's foreign key to its parent's mock Id. The result is a fully-linked in-memory graph with no DML, ready to register for query mocking.
Account account = (Account)kern.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(account.Id, 'Parent has a mock Id');
Assert.isNotNull(account.Contacts[0].Id, 'Children have mock Ids');
Assert.areEqual(account.Id, account.Contacts[0].AccountId, 'Child foreign key references the parent');The Factory Pattern
Why use a factory?
Some records need the same multi-field setup in test after test: a User on a specific profile, a permission set assignment, an active feature flag, or the framework's own configuration metadata. TST_Factory wraps TST_Builder with pre-configured builders for these cases so the setup lives in one place instead of being copied across every test class.
Users and Permission Sets
Most tests need a second user to run as. insertUser gives you a saved one on the profile you name, ready for System.runAs.
To run as another user in a test, put the test code inside a System.runAs(user) block, as the sample below shows. The code inside the block runs as that user, so record sharing follows that user. A KernDX read or save in user mode (the mode that checks the running user's access) also checks that user's object and field permissions.
@IsTest
private static void shouldRunAsStandardUser()
{
User testUser = kern.TST_Factory.insertUser('Standard User');
System.runAs(testUser)
{
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Industry, 'Technology')
.withoutInsertion()
.build();
Assert.areEqual('Technology', account.Industry, 'Industry should be set');
}
}Two platform rules sit behind this:
- Setup records and ordinary records are saved apart (the factory handles this). Salesforce will not save "setup" records (users, permission set assignments) and ordinary records (accounts, your own objects) in the same stretch of a transaction.
- If you try, the save fails with the platform's mixed DML error, which reads like this:
MIXED_DML_OPERATION, DML operation on setup object is not permitted after you have updated a non-setup object (or vice versa). - In a test, a save inside a
System.runAsblock counts as a separate stretch, so the error does not happen there. That is how the factory avoids it. - The factory saves its own setup records apart from everything else, so your test can create ordinary records before or after any factory call without a wrapper of its own.
- If you try, the save fails with the platform's mixed DML error, which reads like this:
- No user saves in parallel tests (yours to keep). Salesforce forbids saving
Userrecords in parallel tests, so removeIsParallel=truefrom the test class header whenever the test saves a user.
A saved user needs a free seat for its profile's licence. If your org is at its limit for a licence, choose a profile whose licence has seats to spare; otherwise the platform reports the licence limit when the factory saves the user.
insertUser(profileName, companyName) also sets the company name, a simple way to find the user again from another test method with new kern.SEL_User().findByCompanyName(companyName). insertUsers(profileName, count) saves a batch. When your org's User rules need more than the factory sets, or the user needs a role, build the user with newUser, set the fields yourself, and let the factory save it:
UserRole managerRole = (UserRole)kern.QRY_Builder.selectFrom(UserRole.SObjectType)
.condition(UserRole.DeveloperName).equals('Manager')
.toList()
.iterator()
.next();
User manager = kern.TST_Factory.newUser('Standard User');
manager.UserRoleId = managerRole.Id;
kern.TST_Factory.insertUsers(new List<User> {manager});newUser and newUsers return unsaved users for the cases where you want to save them yourself.
Assign a permission set (or permission set group) to saved users with createPermissionSetAssignments. It throws an AssertException if the named permission set cannot be resolved, and it keeps its writes apart from your ordinary records in the same way. It saves all of one call's assignments together, so if one assignment fails, none of them is saved.
List<User> users = kern.TST_Factory.insertUsers('Standard User', 2);
kern.TST_Factory.createPermissionSetAssignments(users, 'My_Permission_Set');When you need a saved admin user that test methods reach through System.runAs, newUserWithPermissionSet builds the user, saves it, and assigns the permission set in one call. That makes it a good fit inside @TestSetup, where you can seed ordinary records right after it.
@TestSetup
private static void setupAdmin()
{
kern.TST_Factory.newUserWithPermissionSet(
'System Administrator',
'MyClass_TEST-admin',
'My_Admin_Permission_Set'
);
}Setup records the factory does not create, such as groups and group members, still need the platform's own guard. Wrap those inserts in a System.runAs block for the running user:
System.runAs(new User(Id = UserInfo.getUserId()))
{
insert new Group(Name = 'Reviewers');
}Feature Flags
When a test needs to run code that is gated behind a feature flag, turn the flag on for that test. newFeatureFlag(flagName) registers an active feature flag for the current transaction, so kern.UTIL_FeatureFlag.isEnabled(flagName) returns true afterward. No DML is involved: the flag is placed straight into the framework's in-memory cache.
@IsTest
private static void shouldRunFlagGatedPath()
{
kern.TST_Factory.newFeatureFlag('MyFeatureFlag');
Assert.isTrue(
kern.UTIL_FeatureFlag.isEnabled('MyFeatureFlag'),
'Flag should report enabled after registration'
);
}Framework Metadata: Triggers and Validations
Deploy the framework configuration your tests rely on (trigger settings, trigger actions, validation rules, and validation rule groups: the TriggerSetting__mdt, TriggerAction__mdt, ValidationRule__mdt and related records) as CustomMetadata records via XML. The Trigger Actions Fast Start and Custom Validations Fast Start show that pattern.
Those records are in place for every test that runs against the org, so a test simply builds a record and asserts on the resulting trigger or validation behaviour. This example uses the TRG_AccountSetDefaults action from the Trigger Actions Fast Start, which fills in a blank Description when an Account is created.
A before-insert change is not copied back to the record in your test, so the test reads the saved record again:
@IsTest
private static void shouldFireTriggerAction()
{
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Description, null)
.build();
Account saved = (Account)kern.QRY_Builder.selectFrom(Account.SObjectType)
.fields(new List<SObjectField>{ Account.Description })
.condition(Account.Id).equals(account.Id)
.getFirst();
Assert.isNotNull(saved.Description, 'The trigger action should fill in a blank Description');
}Custom Metadata Records
Some framework configuration depends on custom metadata records (masking targets, for example). You set those up by deploying the relevant CustomMetadata records as XML alongside your test classes. Custom metadata types can't be inserted via DML, so the records ship with your source and are active for every test run.
Place the records under force-app/main/default/customMetadata/, one file per record:
<?xml version="1.0" encoding="UTF-8"?>
<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<label>Mask Contact Email</label>
<protected>false</protected>
<values>
<field>kern__CallerClass__c</field>
<value xsi:nil="true"/>
</values>
<values>
<field>kern__Field__c</field>
<value xsi:nil="true"/>
</values>
<values>
<field>kern__IsActive__c</field>
<value xsi:type="xsd:boolean">true</value>
</values>
<values>
<field>kern__Rule__c</field>
<value xsi:type="xsd:string">kern__MaskEmail</value>
</values>
<values>
<field>kern__SObjectType__c</field>
<value xsi:type="xsd:string">Contact</value>
</values>
</CustomMetadata>A blank kern__Field__c applies the rule to every text field on Contact. Masking runs inside the framework's trigger, so Contact also needs the one-line trigger that hands control to the framework, and a kern__TriggerSetting__mdt record with kern__ApplyMasking__c checked. The Data Masking - Guide explains both steps.
Once the records are deployed, a test builds a record normally and asserts on the masked behaviour:
@IsTest
private static void shouldMaskContactEmail()
{
Contact contact = (Contact)kern.TST_Builder.of(Contact.SObjectType)
.withOverride(Contact.Email, 'real.person@example.com')
.build();
Assert.areNotEqual(
'real.person@example.com',
contact.Email,
'Email should be masked according to the deployed masking target');
}Logger Configuration
When a test needs to check what was logged, set the global kern.LOG_Builder.ignoreTestMode flag to true. By default the logging framework discards log records during tests, to avoid cluttering them. It still runs inside tests using your org's configuration, so the logs you generate in a test go through the same code path as in production.
kern.LOG_Builder.ignoreTestMode = true;The flag is reset between test methods along with all other static state, so enabling it in one test never leaks into another.
How do I seed a sandbox or scratch org?
Run the builder and the factory from a script: they fill a fresh sandbox or scratch org with records to click through, demo, or test by hand. There is nothing to install or switch on. Both are ordinary production classes, so a script run from your command line saves records exactly as a test would, except that they stay.
// Three accounts, each with two contacts, saved together as one all-or-nothing unit
List<Account> accounts = (List<Account>)kern.TST_Builder.of(Account.SObjectType)
.withCount(3)
.withCycle(Account.Name, new List<Object> {'Northwind Traders', 'Contoso', 'Fabrikam'})
.withOverride(Account.Industry, 'Technology')
.withChildren(Contact.SObjectType, 2, new Map<SObjectField, Object> {Contact.LastName => 'Seeded'})
.buildList();
// A Standard User to try the org as (Setup, Users, Login); the company name is how you find the user again later
User reviewer = kern.TST_Factory.insertUser('Standard User', 'seed-reviewer');Save it as seed.apex and run it against the org:
sf apex run --file seed.apex -o YourOrgAliasAfterwards the org holds:
- three accounts named Northwind Traders, Contoso and Fabrikam;
- two contacts under each, with the last name Seeded;
- an active Standard User whose company name is
seed-reviewer.
Every field Salesforce requires carries a valid generated value; fields it does not require are left empty. The seeded user needs a free seat for its profile's licence, and a profile with that exact name; see Users and Permission Sets.
Before you run it, know how a seeding run differs from a test:
- The data stays. A test rolls back everything it saved; a script does not. Whatever the script builds is in the org until you remove it.
- Each build is all or nothing. One
build()orbuildList()call saves its whole graph as one unit. If the platform refuses a row (a validation rule, a required field your org adds), the call throws with the platform's message and nothing from that call is saved. - The builder saves with full access. It saves in system mode, which skips the object and field permission checks that apply to the user running the script, so it can fill fields that user could not edit on screen. Record sharing is unchanged. Check the result as the people who will use the org, not as yourself.
- Defaults are random, and only required fields are filled. Every required field you do not override gets a valid random value: names, emails, dates, picklist entries.
- Fields Salesforce does not require stay empty. List the ones people will see on screen with
withDefaultedField(see Defaulting Optional Fields), and override the ones whose value matters, as the script does with the account names, the industry and the contacts' last names. - Running it twice creates a second set. A second run inserts three more accounts and another user, and a duplicate rule on your objects may refuse the second copy. Usernames never collide, though: each run draws a fresh random base for the user's email and username.
- Users cannot be deleted. Salesforce never deletes a user, so when you are done, deactivate the seeded user instead. Find it by the company name you gave it:
User reviewer = new kern.SEL_User().findByCompanyName('seed-reviewer');
kern.DML_Builder.newTransaction().doUpdate(new User(Id = reviewer.Id, IsActive = false)).execute();Send only the field you change, as above: the update runs with your own field permissions, and a user record read back from the database carries fields nobody may edit, which the save would refuse. If no user has that company name the lookup returns nothing, so check the record is not null before you use its Id.
The seeded accounts and contacts delete like any other records, but do the deleting in its own script. A run that updates a user and then deletes ordinary records is refused with a MIXED_DML_OPERATION error, and nothing the run did is kept.
Extending the Defaults
Custom Default Value Provider
The values the builder fills in come from a default value provider. If you need to change how those defaults are generated (say, to satisfy an unusual required-field setup), extend kern.UTIL_SObjectBuilderDefaultProvider and assign an instance to kern.TST_Builder.defaultValueProvider. UTIL_SObjectBuilderDefaultProvider is a global virtual class rather than an interface, so the framework can add methods in future releases without breaking your subclass.
Extend that class, not the bare kern.TST_Builder.DefaultValueProvider it is built on. kern.UTIL_SObjectBuilderDefaultProvider is the one carrying every default the builder normally supplies, so your subclass changes only what you override and inherits the rest. A subclass of the bare base starts from nothing.
Override whichever of these hooks you need:
| Hook | What it changes |
|---|---|
defineSObjectRequiredFields(SObjectType) | Which fields the builder treats as required and fills in for you |
defineSObjectOptionalFields(SObjectType) | Which fields the builder leaves alone |
get<Type>DefaultValue(DescribeFieldResult, Integer) | The value generated for one field type, for example getEmailDefaultValue or getTextDefaultValue |
public inherited sharing class MyDefaultProvider extends kern.UTIL_SObjectBuilderDefaultProvider
{
public override Set<SObjectField> defineSObjectRequiredFields(SObjectType sObjectType)
{
if(sObjectType == Account.SObjectType)
{
return new Set<SObjectField>{ Account.Industry };
}
return super.defineSObjectRequiredFields(sObjectType);
}
public override String getEmailDefaultValue(DescribeFieldResult fieldDescribe, Integer recordIndex)
{
return 'qa+' + recordIndex + '@example.com';
}
}
// Apply it for the transaction
kern.TST_Builder.defaultValueProvider = new MyDefaultProvider();If you override
defineSObjectOptionalFields, end it with thesupercall. Returnsuper.defineSObjectOptionalFields(sObjectType)for every type you are not handling yourself.The inherited behaviour marks each
UserPermissionsfield onUseras optional, and that is what keeps the builder from tripping over the permission fields your org's licences control when it creates aUser. Replace the method outright and building aUserstarts to fail.
public override Set<SObjectField> defineSObjectOptionalFields(SObjectType sObjectType)
{
if(sObjectType == Account.SObjectType)
{
return new Set<SObjectField>{ Account.Website };
}
return super.defineSObjectOptionalFields(sObjectType);
}A custom provider is set per transaction, so the assignment does not leak into other tests (see Let Salesforce Reset Static State).
Auto-Default Marker
In an override map, the kern.TST_Builder.autoDefaultFieldValueProvider marker asks the builder to generate a default for a field even when you're supplying other fields explicitly:
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverrides(new Map<String, Object>
{
'Name' => 'Test Account',
'Description' => kern.TST_Builder.autoDefaultFieldValueProvider
})
.withoutInsertion()
.build();How to opt out
The test-data layer is opt-in: when part of it does not fit, step outside that part and keep the rest.
| You need | Use | See |
|---|---|---|
| A plain record with no auto-population | new Account(Name = 'X'), saved with kern.DML_Builder.newTransaction().doInsert(record).execute(), so the save still goes through KernDX. | — |
| One field that the builder shouldn't default | withOptionalField(field) to skip a required field, or build the record by hand. | Marking Fields Optional |
DML-free query interception (records flow through kern.QRY_Builder) | kern.TST_Mock (same chained build calls as TST_Builder, auto-registers for query mocking). | Test Data Fast Start |
| Aggregate-query test data | kern.TST_Mock.registerAggregateRows hands the query the rows it returns, so nothing is inserted. | Mocking an aggregate query |
| Custom default values for a field type | Extend kern.UTIL_SObjectBuilderDefaultProvider and assign kern.TST_Builder.defaultValueProvider. | Extending the Defaults |
How does it work?
Your test code calls either the convenience layer (TST_Factory) or the builder directly (TST_Builder). The builder fills in field defaults through a part you can replace if you need to (DefaultValueProvider).
┌─────────────────────────────────────────────────────────────────────────────┐
│ TEST DATA LAYER ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ @IsTest CODE (and anonymous Apex for TST_Builder) │
│ ================================================== │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ TST_Factory (Convenience — pre-configured builders for common records)│ │
│ │ - newUser, createPermissionSetAssignments, newFeatureFlag │ │
│ │ - newContentVersion, newApiCall, newOutboundApiSetting │ │
│ └───────────────────────────────┬───────────────────────────────────────┘ │
│ │ delegates to │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ TST_Builder (Primary — fluent builder for any SObject) │ │
│ │ - of(type).withOverride(...).withCount(n).build()/buildList() │ │
│ │ - auto-populated required fields, cycling, relationships, mock Ids │ │
│ └───────────────────────────────┬───────────────────────────────────────┘ │
│ │ pluggable │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ DefaultValueProvider (extension point for custom field defaults) │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Layer 1: TST_Builder
TST_Builder builds a valid record without you listing every required field: it fills in the fields Salesforce requires, and it saves the record unless you ask it not to. Use it for building records in any test. One caveat in your org: if you have added custom validation rules, a record may need extra withOverride() calls to satisfy them.
You start a build, chain any configure calls (each returns the Builder), then finish it with the call that builds the records and returns them:
| Step | Method | What it does |
|---|---|---|
| Start | kern.TST_Builder.of(SObjectType) | Start a build for a typed SObject |
| Start | kern.TST_Builder.of(String) | Start a build by SObject API name (resolved via describe) |
| Configure | withOverride(field, value) / withOverride(fieldName, value) | Set one field |
| Configure | withOverrides(Map<SObjectField, Object>) / withOverrides(Map<String, Object>) | Set many |
| Configure | withCycle(field, values) / withCycle(fieldName, values) | Rotate values across buildList() |
| Configure | withDefaultedField(...) / withDefaultedFields(List<Object>) | Also default a non-required field |
| Configure | withOptionalField(...) / withOptionalFields(List<Object>) | Skip auto-populating a field |
| Configure | withCount(Integer) | Number of records for buildList() |
| Configure | withRecordType(String developerName) | Set the record type by developer name |
| Configure | withChildren(...) | Attach child records (several overloads) |
| Configure | withoutInsertion() / withoutInsertion(Boolean) | Control DML and mock Ids |
| Finish | build() | Returns a single SObject |
| Finish | buildList() | Returns a List<SObject> of withCount(n) records |
Layer 2: TST_Factory
TST_Factory skips the setup a record needs in test after test (a User on a given profile, a permission set assignment, an active feature flag). It offers ready-made builders for users, permission set assignments, feature flags, API call records, API settings and content versions. The methods you call most:
| Method | What you get |
|---|---|
kern.TST_Factory.insertUser(profileName) / insertUser(profileName, companyName) | A saved User, ready for System.runAs |
kern.TST_Factory.insertUsers(profileName, count) / insertUsers(users) | A saved batch, or users you shaped yourself, saved |
kern.TST_Factory.newUser(profileName) / newUser(profileName, companyName) | An unsaved User (you choose when to insert it) |
kern.TST_Factory.newUsers(profileName, count) | A list of unsaved User records |
kern.TST_Factory.newUserWithPermissionSet(profileName, companyName, permissionSetName) | Saves a user and assigns a permission set (or permission set group) |
kern.TST_Factory.createPermissionSetAssignments(users, permissionSetOrGroupName) | Assigns a permission set to saved users |
kern.TST_Factory.newFeatureFlag(flagName) | Registers an active feature flag for the transaction |
Trigger settings, trigger actions and validation rules: see Framework Metadata.
Anti-Patterns
| Anti-Pattern | Why It's Wrong | Instead |
|---|---|---|
Calling build() inside a loop | One DML statement per iteration, which hits governor limits fast | withCount(n).buildList() (a single DML statement) |
| Setting every required field by hand | Verbose and brittle; renamed required fields break silently | Override only what the test asserts on; let the builder fill the rest |
Using withoutInsertion(true) when no Id is needed | Generates a mock Id the test never uses, adding noise | withoutInsertion() (no argument) for pure in-memory logic tests |
Building an AggregateResult by hand | AggregateResult has no public constructor, so it cannot be instantiated | kern.TST_Mock.registerAggregateRows, then read with toAggregateList() |
Forgetting IsParallel=true removal when inserting User | Salesforce forbids User DML in parallel tests | Remove IsParallel=true from the class header for user-inserting tests |
| Hardcoding field names as strings in hand-written tests | Breaks silently when fields are renamed or deleted | Use SObjectField token overloads (withOverride(Account.Name, …)) |
Best Practices
Override Only What Matters
Let the builder handle required fields. A test that names only the fields it asserts on stays focused and survives unrelated schema changes.
// Good — the test cares about Industry; everything else is filled in
Account account = (Account)kern.TST_Builder.of(Account.SObjectType)
.withOverride(Account.Industry, 'Technology')
.build();Prefer In-Memory Builds for Pure Logic
If the code under test only reads fields, use withoutInsertion(): see In-Memory, No Id.
Bulk With One DML
Always create many records with withCount(n).buildList(), never a loop of build() calls (see withCount and buildList).
Use Mock Ids Only When the Code Needs an Id
Choose withoutInsertion(true) only when the code needs an Id, and withoutInsertion() otherwise: see Choosing a Mode.
Build Relationships With withChildren
Let the builder set the foreign keys for you: see Relationships for what a saved graph and an in-memory graph give you.
Prefer Token Overloads in Hand-Written Tests
withOverride(Account.Name, …) is compile-checked: see Token Maps vs String Maps.
Centralise Shared Setup in TST_Factory
If many test classes build the same kind of record (a user on a profile, an active flag), use the existing TST_Factory method. For records specific to your own org, follow the same factory pattern in your own test helper.
Assert on User-Facing Text Through Custom Labels
When a test asserts on text that surfaces to an end user, compare against the Custom Label rather than a hardcoded literal: in Apex via System.Label.X, in LWC via an import from @salesforce/label/c.X. This keeps the test aligned with text that can be translated and overridden.
Let Salesforce Reset Static State
Salesforce resets static state (including any custom default provider you assigned) between test methods. You do not need manual cleanup between methods for the test-data layer.
Related Documentation
- Test Data Fast Start - Build-and-test walkthrough, plus
TST_Mockfor DML-free query interception - Selectors - Guide - Querying records and mocking query results in tests
- DML - Guide - DML operations and Unit of Work transactions
- Triggers - Guide - Trigger actions and how to test them
- Validation - Guide - Validation rules and how to test them