@raishin/vanguard-frontier-agentic 2.3.0 → 2.5.0

package/skills/salesforce/salesforce-apex-test-generator-skill/references/async-testing.md

@@ -0,0 +1,217 @@
+# Async Testing Patterns Reference
+
+Adapted from forcedotcom/sf-skills generating-apex-test references (Apache-2.0).
+
+## Test.startTest / Test.stopTest
+
+Every async operation in a test must be wrapped with `Test.startTest` / `Test.stopTest`.
+
+- `Test.startTest` — resets governor limits and marks the async boundary
+- `Test.stopTest` — flushes the async queue (Queueable, future methods, batch jobs)
+  and waits for all enqueued async work to complete before proceeding
+
+```apex
+@isTest
+static void testQueueableJob {
+    List<Account> accounts = TestDataFactory.createAccounts(5, true);
+
+    Test.startTest;
+    System.enqueueJob(new ProcessAccountsQueueable(
+        new Map<Id, Account>(accounts).keySet
+    ));
+    Test.stopTest;
+
+    // Assertions here run AFTER the Queueable has completed
+    List<Account> updated = [SELECT Status__c FROM Account WHERE Id IN :accounts];
+    for (Account acc : updated) {
+        Assert.areEqual('Processed', acc.Status__c, 'Account should be processed');
+    }
+}
+```
+
+**Rule:** All synchronous setup (DML, SOQL for setup) goes before `Test.startTest`.
+The code under test goes between `Test.startTest` and `Test.stopTest`.
+Assertions go after `Test.stopTest`.
+
+---
+
+## Testing Queueable Jobs
+
+```apex
+@isTest
+static void testOrderEventQueueable {
+    List<Order__c> orders = TestDataFactory.createOrders(10, true);
+    Set<Id> orderIds = new Map<Id, Order__c>(orders).keySet;
+
+    Test.startTest;
+    System.enqueueJob(new OrderEventQueueable(orderIds));
+    Test.stopTest;
+
+    // After stopTest, Queueable has executed
+    List<Event_Log__c> logs = [SELECT Order_Id__c FROM Event_Log__c];
+    Assert.areEqual(10, logs.size, 'Expected 10 event log entries');
+}
+```
+
+---
+
+## Testing Batch Jobs
+
+`Test.startTest` / `Test.stopTest` also flushes batch execution:
+
+```apex
+@isTest
+static void testAccountDeduplicationBatch {
+    // Create duplicates
+    List<Account> accs = TestDataFactory.createAccounts(200, true);
+
+    Test.startTest;
+    Database.executeBatch(new AccountDeduplicationBatch, 200);
+    Test.stopTest;
+
+    // Batch has run after stopTest
+    Integer remaining = [SELECT COUNT FROM Account WHERE IsActive__c = true];
+    Assert.isTrue(remaining < 200, 'Deduplication should have reduced count');
+}
+```
+
+**Batch test limitations:**
+- Only one batch execute cycle runs in test context (no multi-execute chunking)
+- Batch size in tests can be set explicitly: `Database.executeBatch(new MyBatch, 1)` for
+  single-record processing to test edge cases
+- `Database.Stateful` instance variables persist across execute calls in test context
+
+---
+
+## Testing Schedulable Jobs
+
+```apex
+@isTest
+static void testNightlyCleanupScheduler {
+    Test.startTest;
+    String jobId = System.schedule(
+        'Test Nightly Cleanup',
+        '0 0 2 * * ?',
+        new NightlyCleanupScheduler
+    );
+    Test.stopTest;
+
+    // Verify the job was scheduled
+    CronTrigger ct = [SELECT Id, CronExpression, State FROM CronTrigger WHERE Id = :jobId];
+    Assert.areEqual('WAITING', ct.State, 'Job should be in WAITING state');
+    Assert.areEqual('0 0 2 * * ?', ct.CronExpression, 'Cron expression should match');
+}
+```
+
+**Note:** `Test.stopTest` triggers a single execution of the Schedulable's `execute`
+method. The Queueable or Batch that the Scheduler enqueues will also flush within
+the `stopTest` boundary.
+
+---
+
+## Testing HTTP Callouts
+
+Classes that make HTTP callouts require a mock implementation during tests.
+The platform blocks real outbound callouts from test context.
+
+**Step 1 — Create a mock class:**
+
+```apex
+@isTest
+public class MockHttpCallout implements HttpCalloutMock {
+    private Integer statusCode;
+    private String responseBody;
+
+    public MockHttpCallout(Integer statusCode, String responseBody) {
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+
+    public HTTPResponse respond(HTTPRequest req) {
+        HTTPResponse res = new HTTPResponse;
+        res.setStatusCode(statusCode);
+        res.setBody(responseBody);
+        return res;
+    }
+}
+```
+
+**Step 2 — Register the mock and test:**
+
+```apex
+@isTest
+static void testExternalApiCallout_Success {
+    // Arrange — register mock before startTest
+    String mockResponse = '{"status":"ok","id":"123"}';
+    Test.setMock(HttpCalloutMock.class, new MockHttpCallout(200, mockResponse));
+
+    Test.startTest;
+    ExternalApiService.syncRecord('001Xx000001ABC');
+    Test.stopTest;
+
+    // Assert on results
+    Sync_Log__c log = [SELECT Status__c FROM Sync_Log__c LIMIT 1];
+    Assert.areEqual('Success', log.Status__c, 'Sync log should show Success');
+}
+
+@isTest
+static void testExternalApiCallout_HandlesError {
+    Test.setMock(HttpCalloutMock.class, new MockHttpCallout(503, '{"error":"Service Unavailable"}'));
+
+    Test.startTest;
+    try {
+        ExternalApiService.syncRecord('001Xx000001ABC');
+        Assert.fail('Expected CalloutException for 503 response');
+    } catch (ExternalApiService.SyncException e) {
+        Assert.isTrue(e.getMessage.contains('503'), 'Exception should mention status code');
+    }
+    Test.stopTest;
+}
+```
+
+---
+
+## Testing with StaticResourceCalloutMock
+
+For complex response bodies, store them as Static Resources and use
+`StaticResourceCalloutMock`:
+
+```apex
+@isTest
+static void testCalloutWithStaticResource {
+    StaticResourceCalloutMock mock = new StaticResourceCalloutMock;
+    mock.setStaticResource('MockApiResponse'); // Static Resource name
+    mock.setStatusCode(200);
+    mock.setHeader('Content-Type', 'application/json');
+    Test.setMock(HttpCalloutMock.class, mock);
+
+    Test.startTest;
+    MyApiService.fetchData;
+    Test.stopTest;
+
+    // assertions
+}
+```
+
+---
+
+## Multiple Async Jobs in One Test
+
+If testing code that enqueues multiple async jobs:
+
+```apex
+@isTest
+static void testMultipleQueueableJobs {
+    // All jobs enqueued within Test.startTest/stopTest will execute
+    Test.startTest;
+    System.enqueueJob(new FirstQueueable);
+    System.enqueueJob(new SecondQueueable);
+    Test.stopTest;
+    // Both jobs have completed here
+}
+```
+
+**Governor limit in tests:** Only one Queueable job can be enqueued per `enqueueJob`
+call from within test context. Chained Queueables (where Job A enqueues Job B)
+may not all execute within a single `stopTest` call — test each job in isolation
+when testing chains.

package/skills/salesforce/salesforce-apex-test-generator-skill/references/test-data-factory.md

@@ -0,0 +1,174 @@
+# TestDataFactory Patterns Reference
+
+Adapted from forcedotcom/sf-skills generating-apex-test references (Apache-2.0).
+
+## Core Design Rules
+
+1. **Always accept a `doInsert` flag** — lets callers modify records before insert
+2. **Append loop index to fields in Duplicate Rules** — prevents `DUPLICATES_DETECTED`
+3. **Single-record methods delegate to bulk** — `createAccount(doInsert)` calls `createAccounts(1, doInsert)[0]`
+4. **Return created records** — enables chaining and further manipulation
+5. **Set all required fields** — include validation-rule-required fields, not just schema-required
+
+## Base Class Structure
+
+```apex
+@isTest
+public class TestDataFactory {
+
+    // Account
+    public static Account createAccount(Boolean doInsert) {
+        return createAccounts(1, doInsert)[0];
+    }
+
+    public static List<Account> createAccounts(Integer count, Boolean doInsert) {
+        List<Account> accounts = new List<Account>;
+        for (Integer i = 0; i < count; i++) {
+            accounts.add(new Account(
+                Name = 'Test Account ' + i,
+                Industry = 'Technology',
+                BillingCity = 'San Francisco'
+            ));
+        }
+        if (doInsert) insert accounts;
+        return accounts;
+    }
+
+    // Contact
+    public static Contact createContact(Id accountId, Boolean doInsert) {
+        return createContacts(accountId, 1, doInsert)[0];
+    }
+
+    public static List<Contact> createContacts(Id accountId, Integer count, Boolean doInsert) {
+        List<Contact> contacts = new List<Contact>;
+        for (Integer i = 0; i < count; i++) {
+            contacts.add(new Contact(
+                FirstName = 'Test',
+                LastName = 'Contact ' + i,
+                Email = 'testcontact' + i + '@example.com',
+                AccountId = accountId
+            ));
+        }
+        if (doInsert) insert contacts;
+        return contacts;
+    }
+}
+```
+
+## Field Override Pattern
+
+Allows callers to customize records without creating new factory methods:
+
+```apex
+public static Account createAccount(Map<String, Object> fieldOverrides, Boolean doInsert) {
+    Account acc = new Account(
+        Name = 'Test Account',
+        Industry = 'Technology'
+    );
+    for (String fieldName : fieldOverrides.keySet) {
+        acc.put(fieldName, fieldOverrides.get(fieldName));
+    }
+    if (doInsert) insert acc;
+    return acc;
+}
+
+// Usage:
+Account acc = TestDataFactory.createAccount(
+    new Map<String, Object>{'Name' => 'Acme Corp', 'Industry' => 'Healthcare'},
+    true
+);
+```
+
+## @TestSetup vs Inline Factory
+
+**Use @TestSetup when:**
+- Multiple test methods need the same base data
+- Setup is expensive (many records, related objects)
+
+```apex
+@isTest
+private class AccountServiceTest {
+
+    @TestSetup
+    static void setup {
+        List<Account> accounts = TestDataFactory.createAccounts(10, true);
+        TestDataFactory.createContacts(accounts[0].Id, 5, true);
+    }
+
+    @isTest
+    static void testGetActiveAccounts {
+        // data from @TestSetup is available; each test gets a fresh copy
+        List<Account> accounts = [SELECT Id FROM Account];
+        Assert.areEqual(10, accounts.size, 'Expected 10 accounts from setup');
+    }
+}
+```
+
+**Important @TestSetup notes:**
+- DML in @TestSetup is rolled back between test methods — each test gets its own
+  isolated copy of the setup data
+- @TestSetup cannot be used in test classes that use `SeeAllData=true`
+- @TestSetup runs once per class, not once per method
+
+## Bulk Factory Pattern (200+ Records)
+
+For bulkification tests, always create at least 201 records to cross the trigger batch
+boundary:
+
+```apex
+@isTest
+static void testBulkAccountUpdate {
+    List<Account> accounts = TestDataFactory.createAccounts(201, true);
+    // test bulk update path
+    for (Account acc : accounts) {
+        acc.Industry = 'Finance';
+    }
+    Test.startTest;
+    update accounts;
+    Test.stopTest;
+
+    List<Account> updated = [SELECT Industry FROM Account WHERE Id IN :accounts];
+    Assert.areEqual(201, updated.size, 'All 201 accounts should be updated');
+    for (Account acc : updated) {
+        Assert.areEqual('Finance', acc.Industry, 'Industry should be Finance for all records');
+    }
+}
+```
+
+## Record Type Support
+
+```apex
+public static Account createAccountByRecordType(String recordTypeDeveloperName, Boolean doInsert) {
+    Id recordTypeId = Schema.SObjectType.Account
+        .getRecordTypeInfosByDeveloperName
+        .get(recordTypeDeveloperName)
+        .getRecordTypeId;
+
+    Account acc = new Account(
+        Name = 'Test ' + recordTypeDeveloperName + ' Account',
+        RecordTypeId = recordTypeId
+    );
+    if (doInsert) insert acc;
+    return acc;
+}
+```
+
+## Handling Duplicate Rules
+
+When Duplicate Rules are active in the org, use `Database.insert` with `AllOrNone=false`
+or `DuplicateRuleHeader` in test setup:
+
+```apex
+public static List<Account> createAccountsAllowDuplicates(Integer count, Boolean doInsert) {
+    List<Account> accounts = new List<Account>;
+    for (Integer i = 0; i < count; i++) {
+        accounts.add(new Account(Name = 'Duplicate Test ' + i));
+    }
+    if (doInsert) {
+        Database.DMLOptions opts = new Database.DMLOptions;
+        opts.DuplicateRuleHeader.AllowSave = true;
+        Database.insert(accounts, opts);
+    }
+    return accounts;
+}
+```