Skip to content

TST_Mock ​

Class · Group: Testing

Learn it: Fast Start - Test Data and Test Data guide

apex
global inherited sharing class TST_Mock

Central registry and fluent builder for mock SObjects. Wraps QRY_Builder.setMock() with lifecycle management, providing a single point of control for registering, retrieving, and clearing mock records used in DML-free unit tests, and for setting a different answer for each query with registerNext. registerAggregateRows and registerNextAggregateRows answer aggregate queries. The nested MockBuilder creates records with mock IDs and registers them on its own, so that a query in the test returns them.

Example

apex
Foobar__c mock = (Foobar__c)TST_Mock.of(Foobar__c.SObjectType)
    .withOverride(Foobar__c.Name, 'Test').build();
Foobar__c result = (Foobar__c)new SEL_Foobar().findById(mock.Id);

See Also: TST_Builder, QRY_Builder


Methods ​

MethodDescription
global static void clear()Removes every mock record, queued answer, exception and aggregate rows registered for every SObject type, and takes every type out of the QRY_Builder mock layer, so queries read the database again.
global static void clear(SObjectType objectType)Removes the mock records, queued answers, exception and aggregate rows registered for one SObject type, and takes that type out of the QRY_Builder mock layer, so its queries read the database again.
global static List<SObject> get(SObjectType objectType)Retrieves all mock records registered for the specified SObject type.
global static TST_Mock.MockBuilder of(SObjectType objectType)Creates a new MockBuilder for the specified SObject type.
global static void register(SObjectType objectType, List<SObject> records)Registers a list of mock records for the specified SObject type.
global static void register(SObjectType objectType, SObject record)Registers a single mock record for the specified SObject type.
global static void registerAggregateRows(SObjectType objectType, List<Map<String, Object>> rows)Registers rows that every aggregate query on this object type returns until cleared.
global static void registerAggregateRows(SObjectType objectType, Map<String, Object> row)Registers one row that every aggregate query on this object type returns until cleared.
global static void registerNext(SObjectType objectType, List<SObject> records)Sets the answer to the NEXT query the framework runs against the given SObject type: that one query, or count, is answered from these records, and the answer is then used up.
global static void registerNext(SObjectType objectType, SObject record)Sets one record as the answer to the NEXT query the framework runs against the given SObject type.
global static void registerNextAggregateRows(SObjectType objectType, List<Map<String, Object>> rows)Registers rows that answer the next aggregate query on this object type once; answers are used in the order you added them, before any registered rows.
global static void registerNextAggregateRows(SObjectType objectType, Map<String, Object> row)Registers one row that answers the next aggregate query on this object type once.
global static void throwsException(SObjectType objectType)Convenience overload that throws a generic QueryException for the given SObjectType.
global static void throwsException(SObjectType objectType, Exception exceptionToThrow)Registers an Exception to be thrown on every query the framework runs against the specified SObjectType, until it is cleared.
global static void throwsException(SObjectType objectType, String errorMessage)Convenience overload that throws a QueryException with the given message.

clear ​

apex
global static void clear()

Removes every mock record, queued answer, exception and aggregate rows registered for every SObject type, and takes every type out of the QRY_Builder mock layer, so queries read the database again.

Example

apex
TST_Mock.clear();
apex
global static void clear(SObjectType objectType)

Removes the mock records, queued answers, exception and aggregate rows registered for one SObject type, and takes that type out of the QRY_Builder mock layer, so its queries read the database again.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObject type to clear mocks for.

Example

apex
TST_Mock.clear(Foobar__c.SObjectType);

get ​

apex
global static List<SObject> get(SObjectType objectType)

Retrieves all mock records registered for the specified SObject type.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObject type to retrieve mocks for.

Returns SObject — The list of registered mock records, or an empty list if none registered.

Example

apex
List<SObject> mocks = TST_Mock.get(Foobar__c.SObjectType);

of ​

apex
global static TST_Mock.MockBuilder of(SObjectType objectType)

Creates a new MockBuilder for the specified SObject type. Records built via the returned builder are automatically created with mock IDs (no DML) and registered with TST_Mock, so that a query in the test returns them.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObject type to build mock records for.

Returns TST_Mock.MockBuilder — A new MockBuilder instance configured for the specified type.

Example

apex
Foobar__c mock = (Foobar__c)TST_Mock.of(Foobar__c.SObjectType)
    .withOverride(Foobar__c.Name, 'Test')
    .build();

register ​

apex
global static void register(SObjectType objectType, List<SObject> records)

Registers a list of mock records for the specified SObject type. Appends to any previously registered records for the same type and updates the QRY_Builder mock layer.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObject type to register mocks for.
recordsListThe mock records to register.

Example

apex
List<Foobar__c> mocks = new List<Foobar__c>
{
    (Foobar__c)TST_Builder.of(Foobar__c.SObjectType).withoutInsertion(true).build(),
    (Foobar__c)TST_Builder.of(Foobar__c.SObjectType).withoutInsertion(true).build()
};
TST_Mock.register(Foobar__c.SObjectType, mocks);
apex
global static void register(SObjectType objectType, SObject record)

Registers a single mock record for the specified SObject type.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObject type to register the mock for.
recordSObjectThe mock record to register.

Example

apex
Foobar__c mock = (Foobar__c)TST_Builder.of(Foobar__c.SObjectType).withoutInsertion(true).build();
TST_Mock.register(Foobar__c.SObjectType, mock);

registerAggregateRows ​

apex
global static void registerAggregateRows(SObjectType objectType, List<Map<String, Object>> rows)

Registers rows that every aggregate query on this object type returns until cleared. Each map is one row; its keys are the aliases your code reads.

An aggregate query is one with count(field, alias), count(fieldName), countDistinct(), sum(), avg(), min(), max() or groupBy(). The count() that ends a query and returns a number is not one: like toList(), it reads the records registered with register. Read the rows with QRY_Builder.Builder.toAggregateList() or getFirstAggregate(). The rows come back in the order you gave them; only the query's limit is applied to them, never its conditions or its order. Aliases are matched without regard to case, and reading an alias the row does not hold throws, so a spelling mistake shows at once. A number can be written as an Integer, a Long or a Decimal and read with any of the number getters.

Rows registered here are added after the rows registered earlier for the type, the way register adds records, so one aggregate query returns them all, the first registered first. QRY_Builder.setAggregateMock replaces the rows instead. Record mocks registered with register never answer an aggregate query: such a query throws until aggregate rows are registered too. Reading a mocked aggregate query with toList() or any other record read throws. clear() and clear(SObjectType) remove the rows.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe object type whose aggregate queries the rows answer.
rowsListThe rows to add, in this order. May be empty; may not be null. An empty list adds no row, but when no rows are registered yet for the type, it makes every aggregate query on the type find nothing. To remove the rows, call clear(SObjectType).

Throws

ExceptionDescription
IllegalArgumentExceptionWhen objectType or rows is null.

Example

apex
TST_Mock.registerAggregateRows(Foobar__c.SObjectType, new List<Map<String, Object>>
{
    new Map<String, Object> {'total' => 3, 'Name' => 'A'},
    new Map<String, Object> {'total' => 2, 'Name' => 'B'}
});
List<QRY_Builder.AggregateRow> rows = QRY_Builder.selectFrom(Foobar__c.SObjectType)
    .count(Foobar__c.Id, 'total')
    .groupBy(Foobar__c.Name)
    .toAggregateList();
Assert.areEqual(3, rows[0].getInteger('total'), 'The first registered row comes first');
apex
global static void registerAggregateRows(SObjectType objectType, Map<String, Object> row)

Registers one row that every aggregate query on this object type returns until cleared. Its keys are the aliases your code reads. The row is added after the rows registered earlier for the type. Use it for a query read with getFirstAggregate(). See the list overload for how the rows are used.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe object type whose aggregate queries the row answers.
rowMapThe row to return. May not be null.

Throws

ExceptionDescription
IllegalArgumentExceptionWhen objectType or row is null.

Example

apex
TST_Mock.registerAggregateRows(Foobar__c.SObjectType, new Map<String, Object> {'sum' => 10});
QRY_Builder.AggregateRow row = QRY_Builder.selectFrom(Foobar__c.SObjectType)
    .sum(Foobar__c.NumberInteger__c, 'sum')
    .getFirstAggregate();
Assert.areEqual(10, row.getDecimal('sum'), 'The registered row answers');

registerNext ​

apex
global static void registerNext(SObjectType objectType, List<SObject> records)

Sets the answer to the NEXT query the framework runs against the given SObject type: that one query, or count, is answered from these records, and the answer is then used up. Call it once for each query you want to answer; the answers are used in the order you added them. When all of them are used up, the type goes back to the records registered with register, or to the database when none are registered. A test can therefore make the first read find nothing and the second read find the row. That is what a caller sees when another transaction saved the row in between. Nothing needs cleaning up afterwards.

An empty list means the next query finds nothing. A queued answer is filtered, sorted, limited and paged in memory in the same way as a registered record. A count gives the number of queued records that match the query's conditions. A limit or offset on the query does not change a count. An exception registered with throwsException is thrown first, on every query until it is cleared, and the queued answers stay waiting. get returns registered records only, never queued answers. clear() and clear(SObjectType) remove queued answers.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObject type to set the next answer for.
recordsListThe records the next query is answered from. May be empty; may not be null.

Throws

ExceptionDescription
IllegalArgumentExceptionWhen objectType or records is null, or a record is of another type.

Example

apex
Foobar__c stored = (Foobar__c)TST_Builder.of(Foobar__c.SObjectType).build();
TST_Mock.registerNext(Foobar__c.SObjectType, new List<SObject>());
Assert.isNull(new SEL_Foobar().findById(stored.Id), 'The first read misses');
Assert.isNotNull(new SEL_Foobar().findById(stored.Id), 'The second read finds the stored row');
apex
global static void registerNext(SObjectType objectType, SObject record)

Sets one record as the answer to the NEXT query the framework runs against the given SObject type. See the list overload for how queued answers are used.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObject type to set the next answer for.
recordSObjectThe record the next query is answered from. May not be null.

Throws

ExceptionDescription
IllegalArgumentExceptionWhen objectType or record is null, or the record is of another type.

Example

apex
Foobar__c mock = (Foobar__c)TST_Builder.of(Foobar__c.SObjectType).withoutInsertion(true).build();
TST_Mock.registerNext(Foobar__c.SObjectType, mock);

registerNextAggregateRows ​

apex
global static void registerNextAggregateRows(SObjectType objectType, List<Map<String, Object>> rows)

Registers rows that answer the next aggregate query on this object type once; answers are used in the order you added them, before any registered rows.

Call it once for each aggregate query you want to answer. When all of these answers are used up, the type goes back to the rows registered with registerAggregateRows, or to the database when none are registered. An empty list means the next aggregate query finds nothing. clear() and clear(SObjectType) remove the answers that are left.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe object type to set the next aggregate answer for.
rowsListThe rows the next aggregate query returns. May be empty; may not be null.

Throws

ExceptionDescription
IllegalArgumentExceptionWhen objectType or rows is null.

Example

apex
TST_Mock.registerNextAggregateRows(Foobar__c.SObjectType, new List<Map<String, Object>>());
List<QRY_Builder.AggregateRow> rows = QRY_Builder.selectFrom(Foobar__c.SObjectType)
    .count(Foobar__c.Id, 'total')
    .toAggregateList();
Assert.isTrue(rows.isEmpty(), 'The empty answer makes the first aggregate query find nothing');
apex
global static void registerNextAggregateRows(SObjectType objectType, Map<String, Object> row)

Registers one row that answers the next aggregate query on this object type once. See the list overload for how these answers are used.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe object type to set the next aggregate answer for.
rowMapThe row the next aggregate query returns. May not be null.

Throws

ExceptionDescription
IllegalArgumentExceptionWhen objectType or row is null.

Example

apex
TST_Mock.registerNextAggregateRows(Foobar__c.SObjectType, new Map<String, Object> {'total' => 1});

throwsException ​

apex
global static void throwsException(SObjectType objectType)

Convenience overload that throws a generic QueryException for the given SObjectType. The synthesized message names the type so failures point to which mock fired without manual message threading.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObjectType for which queries should throw.

Example

apex
TST_Mock.throwsException(Account.SObjectType);
apex
global static void throwsException(SObjectType objectType, Exception exceptionToThrow)

Registers an Exception to be thrown on every query the framework runs against the specified SObjectType, until it is cleared. Use for negative-path test coverage when a caller needs to exercise a catch block around a SOQL call.

Coexists with record mocks: if both an exception and records are registered for the same SObjectType, the exception is thrown first (records are unreachable).

Cleared by TST_Mock.clear() and TST_Mock.clear(SObjectType).

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObjectType for which queries should throw.
exceptionToThrowExceptionThe exception instance to throw.

Example

apex
TST_Mock.throwsException(Account.SObjectType, new QueryException('Simulated SOQL failure'));
try
{
    new SEL_Accounts().findById(someAccountId);
    Assert.fail('Expected QueryException');
}
catch(QueryException error)
{
    Assert.areEqual('Simulated SOQL failure', error.getMessage(), 'Caught the simulated failure');
}
apex
global static void throwsException(SObjectType objectType, String errorMessage)

Convenience overload that throws a QueryException with the given message.

Parameters

ParameterTypeDescription
objectTypeSObjectTypeThe SObjectType for which queries should throw.
errorMessageStringThe message attached to the synthesized QueryException.

Example

apex
TST_Mock.throwsException(Account.SObjectType, 'Simulated SOQL failure');

Inner Classes ​

ClassDescription
MockBuilderFluent builder wrapper that delegates to TST_Builder.Builder for record construction and auto-registers built records with TST_Mock.