Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

SqlTester Class

Test utility for mocking Data 360 SQL query API responses in Apex tests. The framework automatically detects the test context via Test.isRunningTest() and returns mocked responses when configured. Call clearMocks() before each test to ensure a clean state.

Namespace

sfsqlquery

Usage

You provide mock column metadata and mock row data. The framework auto-generates the query submission and status responses from your mock data. Use setMockRows() to set a single page of results, or call enqueueMockRows() multiple times to simulate multi-page results. If you call cancel() in a test, any subsequent fetch against that query ID raises an exception in the mock layer, simulating production cancellation behavior.

Example

Set up a single-page mock and test an iterator:

1@IsTest
2static void testBasicQuery() {
3    sfsqlquery.SqlTester.clearMocks();
4
5    ConnectApi.QuerySqlMetadataItem col = new ConnectApi.QuerySqlMetadataItem();
6    col.name = 'Name__c';
7    col.type = ConnectApi.TypeEnum.VARCHAR;
8    sfsqlquery.SqlTester.setMockMetadata(new List<ConnectApi.QuerySqlMetadataItem>{ col });
9
10    ConnectApi.QuerySqlRow mockRow = new ConnectApi.QuerySqlRow();
11    mockRow.rowData = new List<Object>{ 'Acme' };
12    sfsqlquery.SqlTester.setMockRows(new List<ConnectApi.QuerySqlRow>{ mockRow });
13
14    sfsqlquery.SqlRowIterator iterator = sfsqlquery.SqlStatement.create('SELECT Name__c FROM accounts__dlm', 'default')
15        .execute();
16
17    Assert.isTrue(iterator.hasNext());
18    sfsqlquery.Row row = iterator.next();
19    Assert.areEqual('Acme', row.getString('Name__c'));
20}

SqlTester Methods

The following are methods for SqlTester.

clearMocks()

Resets all mock state, including metadata, rows, and page queues. Call this at the start of each test method to ensure a clean state.

Signature

public static void clearMocks()

Return Value

Type: void

Example

Clear mocks at the start of each test:

1@IsTest
2static void testMyQuery() {
3    sfsqlquery.SqlTester.clearMocks();
4    // Set up fresh mocks for this test
5    // ... test code ...
6}

enqueueMockRows(rows)

Adds a page of mock rows to the result queue. Call this multiple times to simulate multi-page results. Each call adds one page; pages are returned in the order they were enqueued.

Signature

public static void enqueueMockRows(List<ConnectApi.QuerySqlRow> rows)

Parameters

rows:
Type: List<ConnectApi.QuerySqlRow>

List of ConnectApi.QuerySqlRow objects representing one page of results.

Return Value

Type: void

Example

Simulate multi-page results for SqlQueueable:

1@IsTest
2static void testMultiPageQuery() {
3    sfsqlquery.SqlTester.clearMocks();
4
5    // Set up metadata
6    ConnectApi.QuerySqlMetadataItem col = new ConnectApi.QuerySqlMetadataItem();
7    col.name = 'Name__c';
8    col.type = ConnectApi.TypeEnum.VARCHAR;
9    sfsqlquery.SqlTester.setMockMetadata(new List<ConnectApi.QuerySqlMetadataItem>{ col });
10
11    // Page 1
12    ConnectApi.QuerySqlRow page1Row = new ConnectApi.QuerySqlRow();
13    page1Row.rowData = new List<Object>{ 'Page 1 Data' };
14    sfsqlquery.SqlTester.enqueueMockRows(new List<ConnectApi.QuerySqlRow>{ page1Row });
15
16    // Page 2
17    ConnectApi.QuerySqlRow page2Row = new ConnectApi.QuerySqlRow();
18    page2Row.rowData = new List<Object>{ 'Page 2 Data' };
19    sfsqlquery.SqlTester.enqueueMockRows(new List<ConnectApi.QuerySqlRow>{ page2Row });
20
21    // Execute queueable - will process both pages
22    Test.startTest();
23    System.enqueueJob(new MyQueryJob(
24        sfsqlquery.SqlStatement.create('SELECT Name__c FROM accounts__dlm', 'default')
25    ));
26    Test.stopTest();
27}

isRunningTest()

Returns true if the framework is currently executing within a test context. The framework calls this internally to decide whether to return mocked responses.

Signature

public static Boolean isRunningTest()

Return Value

Type: Boolean

true if executing in a test context; false otherwise.

setMockMetadata(metadata)

Sets the mock column metadata that the framework returns for all queries in the current test. Call this before executing any query.

Signature

public static void setMockMetadata(List<ConnectApi.QuerySqlMetadataItem> metadata)

Parameters

metadata:
Type: List<ConnectApi.QuerySqlMetadataItem>

List of ConnectApi.QuerySqlMetadataItem objects that define the column names and types for the mocked query results.

Return Value

Type: void

Example

Define column metadata for mocked results:

1ConnectApi.QuerySqlMetadataItem idCol = new ConnectApi.QuerySqlMetadataItem();
2idCol.name = 'Id__c';
3idCol.type = ConnectApi.TypeEnum.VARCHAR;
4
5ConnectApi.QuerySqlMetadataItem amountCol = new ConnectApi.QuerySqlMetadataItem();
6amountCol.name = 'Amount__c';
7amountCol.type = ConnectApi.TypeEnum.DECIMAL;
8
9sfsqlquery.SqlTester.setMockMetadata(new List<ConnectApi.QuerySqlMetadataItem>{ idCol, amountCol });

setMockRows(rows)

Sets a single page of mock rows to return for the query. Use enqueueMockRows() instead when simulating multi-page results.

Signature

public static void setMockRows(List<ConnectApi.QuerySqlRow> rows)

Parameters

rows:
Type: List<ConnectApi.QuerySqlRow>

List of ConnectApi.QuerySqlRow objects representing the single page of results to return.

Return Value

Type: void

Example

Set a single page of mock results:

1ConnectApi.QuerySqlRow row1 = new ConnectApi.QuerySqlRow();
2row1.rowData = new List<Object>{ 'acc-001', 1000.00 };
3
4ConnectApi.QuerySqlRow row2 = new ConnectApi.QuerySqlRow();
5row2.rowData = new List<Object>{ 'acc-002', 2500.50 };
6
7sfsqlquery.SqlTester.setMockRows(new List<ConnectApi.QuerySqlRow>{ row1, row2 });

Apex Reference Guide

SqlTester Class

Namespace

Usage

Example

SqlTester Methods

clearMocks()

Signature

Return Value

Example

enqueueMockRows(rows)

Signature

Parameters

Return Value

Example

isRunningTest()

Signature

Return Value

setMockMetadata(metadata)

Signature

Parameters

Return Value

Example

setMockRows(rows)

Signature

Parameters

Return Value

Example