@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/running-apex-tests/references/performance-optimization.md

@@ -0,0 +1,283 @@
+<!-- Parent: running-apex-tests/SKILL.md -->
+# Performance Optimization for Apex Tests
+
+Fast tests enable faster development. When test suites run quickly, developers refactor confidently. This guide covers techniques to dramatically reduce test execution time.
+
+---
+
+## Why Test Speed Matters
+
+| Test Suite Duration | Impact |
+|---------------------|--------|
+| **< 5 minutes** | Developers run frequently, catch issues early |
+| **5-30 minutes** | Developers run occasionally, issues slip through |
+| **30+ minutes** | Developers avoid running, tests become stale |
+| **Hours** | CI/CD bottleneck, blocked deployments |
+
+The goal: **Sub-second unit tests**, with integration tests taking seconds, not minutes.
+
+---
+
+## Technique 1: Mock DML Operations
+
+Database operations are the #1 cause of slow tests.
+
+### The Numbers
+
+| Operation | 10,000 Records | Notes |
+|-----------|----------------|-------|
+| Actual insert | ~50 seconds | Database round-trips |
+| DML mocking | <1 second | In-memory only |
+| **Improvement** | **~35x faster** | |
+
+### Implementation
+
+See `assets/dml-mock.cls` and `references/mocking-patterns.md` for complete implementation.
+
+```apex
+// ❌ SLOW: Actual database insert
+List<Account> accounts = TestDataFactory.createAccounts(1000);
+insert accounts;  // ~5 seconds
+
+// ✅ FAST: Mock DML
+DMLMock.reset();
+AccountService service = new AccountService(new DMLMock());
+service.createAccounts(accounts);  // <0.1 seconds
+Assert.areEqual(1000, DMLMock.InsertedRecords.size());
+```
+
+---
+
+## Technique 2: Mock SOQL Queries
+
+Query execution adds overhead, especially with large result sets.
+
+```apex
+// ❌ SLOW: Actual query requiring test data setup
+@TestSetup
+static void setup() {
+    List<Account> accounts = new List<Account>();
+    for (Integer i = 0; i < 1000; i++) {
+        accounts.add(new Account(Name = 'Test ' + i));
+    }
+    insert accounts;  // Slow
+}
+
+// ✅ FAST: Mock query results
+AccountSelector.setMockResults(new List<Account>{
+    new Account(Name = 'Mock 1'),
+    new Account(Name = 'Mock 2')
+});
+List<Account> results = AccountSelector.getActiveAccounts();  // Instant
+```
+
+---
+
+## Technique 3: Minimize @TestSetup
+
+`@TestSetup` runs before every test method. Large setups compound execution time.
+
+```apex
+// ❌ SLOW: Heavy @TestSetup
+@TestSetup
+static void setup() {
+    List<Account> accounts = TestDataFactory.createAccounts(100);
+    insert accounts;
+    List<Contact> contacts = TestDataFactory.createContacts(500, accounts);
+    insert contacts;
+    List<Opportunity> opps = TestDataFactory.createOpportunities(200, accounts);
+    insert opps;
+    // Total: 800 DML operations, runs before EACH test method
+}
+
+// ✅ FAST: Minimal @TestSetup, mock what you can
+@TestSetup
+static void setup() {
+    // Only create what MUST exist in database
+    Account parentAccount = new Account(Name = 'Required Parent');
+    insert parentAccount;
+}
+```
+
+---
+
+## Technique 4: Choose Efficient Loop Constructs
+
+Loop performance varies significantly with large iterations.
+
+### Benchmark Results (10,000 iterations)
+
+| Loop Type | Duration | Notes |
+|-----------|----------|-------|
+| While loop | ~0.4s | Fastest |
+| Cached iterator | ~0.8s | Good alternative |
+| For loop (index) | ~1.4s | Acceptable |
+| Enhanced for loop | ~2.4s | Convenient but slower |
+| Uncached iterator | CPU limit | Avoid |
+
+### Recommendation
+
+```apex
+// ✅ PREFERRED: While loop for large iterations
+Iterator<Account> iter = accounts.iterator();
+while (iter.hasNext()) {
+    Account acc = iter.next();
+    // process
+}
+
+// ✅ ACCEPTABLE: Standard for loop
+for (Integer i = 0; i < accounts.size(); i++) {
+    Account acc = accounts[i];
+    // process
+}
+
+// ⚠️ CONVENIENT BUT SLOWER: Enhanced for
+for (Account acc : accounts) {
+    // process
+}
+```
+
+---
+
+## Technique 5: Batch Test Data Creation
+
+Creating records one-by-one is slow. Batch operations are faster.
+
+```apex
+// ❌ SLOW: One-by-one creation
+for (Integer i = 0; i < 200; i++) {
+    Account acc = new Account(Name = 'Test ' + i);
+    insert acc;  // 200 DML statements!
+}
+
+// ✅ FAST: Batch creation
+List<Account> accounts = new List<Account>();
+for (Integer i = 0; i < 200; i++) {
+    accounts.add(new Account(Name = 'Test ' + i));
+}
+insert accounts;  // 1 DML statement
+```
+
+---
+
+## Technique 6: Use Assert Instead of System.assert
+
+The modern `Assert` class is cleaner and provides better error messages.
+
+```apex
+// ❌ OLD: System.assert (still works but verbose)
+System.assert(result != null, 'Result should not be null');
+System.assertEquals(expected, actual, 'Values should match');
+
+// ✅ MODERN: Assert class (Apex 56.0+)
+Assert.isNotNull(result, 'Result should not be null');
+Assert.areEqual(expected, actual, 'Values should match');
+Assert.isTrue(condition, 'Condition should be true');
+Assert.fail('Should not reach here');
+```
+
+---
+
+## Technique 7: Avoid SOSL in Tests
+
+SOSL searches return empty results in tests unless configured.
+
+```apex
+// ❌ PROBLEM: SOSL returns nothing in tests by default
+List<List<SObject>> results = [FIND 'test' IN ALL FIELDS RETURNING Account];
+// results[0] is EMPTY even with matching records!
+
+// ✅ SOLUTION: Use Test.setFixedSearchResults()
+@IsTest
+static void testSearch() {
+    Account acc = new Account(Name = 'Searchable');
+    insert acc;
+
+    // Configure what SOSL will return
+    Test.setFixedSearchResults(new List<Id>{ acc.Id });
+
+    Test.startTest();
+    List<List<SObject>> results = [FIND 'test' IN ALL FIELDS RETURNING Account];
+    Test.stopTest();
+
+    Assert.areEqual(1, results[0].size(), 'Should find configured record');
+}
+```
+
+---
+
+## Technique 8: Strategic Test Method Scoping
+
+Run only the tests you need during development.
+
+```bash
+# ❌ SLOW: Run all tests (minutes to hours)
+sf apex run test --test-level RunLocalTests --target-org sandbox
+
+# ✅ FAST: Run single test class
+sf apex run test --class-names MyClassTest --target-org sandbox
+
+# ✅ FASTER: Run single test method
+sf apex run test --tests MyClassTest.testSpecificMethod --target-org sandbox
+```
+
+---
+
+## Technique 9: Async Test Execution
+
+Use async mode for large test suites to avoid blocking.
+
+```bash
+# Start tests asynchronously
+sf apex run test --class-names MyClassTest --wait 0 --target-org sandbox
+# Returns test run ID: 707xx0000000000
+
+# Check status later
+sf apex get test --test-run-id 707xx0000000000 --target-org sandbox
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| DML in loops | N operations instead of 1 | Bulk DML outside loops |
+| Large @TestSetup | Runs before every test | Minimize or mock |
+| No mocking | Full database round-trips | Mock DML, queries, callouts |
+| SeeAllData=true | Depends on org data | Create test data |
+| Deep nested loops | O(n²) or worse | Flatten with Maps |
+| String concatenation in loops | New string objects each iteration | Use List and join |
+
+---
+
+## Optimization Checklist
+
+Before committing tests, verify:
+
+- [ ] DML operations are mocked where possible
+- [ ] @TestSetup is minimal
+- [ ] No SOQL/DML inside loops
+- [ ] Uses bulk patterns (200+ records)
+- [ ] Individual test methods run in <1 second
+- [ ] Full test class runs in <10 seconds
+- [ ] Uses Assert class (not System.assert)
+
+---
+
+## Performance Testing Your Tests
+
+```apex
+@IsTest
+static void testPerformance() {
+    Long startTime = System.currentTimeMillis();
+
+    // Your test code here
+
+    Long duration = System.currentTimeMillis() - startTime;
+    System.debug('Test duration: ' + duration + 'ms');
+
+    // Assert performance constraint
+    Assert.isTrue(duration < 1000, 'Test should complete in <1 second, took: ' + duration + 'ms');
+}
+```

package/skills/running-apex-tests/references/test-fix-loop.md

@@ -0,0 +1,49 @@
+<!-- Parent: running-apex-tests/SKILL.md -->
+
+# Agentic Test-Fix Loop Implementation
+
+## How It Works
+
+When the agentic loop is enabled, running-apex-tests will:
+
+1. **Run tests** and capture results
+2. **Parse failures** to identify error type and location
+3. **Read source files** (test class + class under test)
+4. **Analyze root cause** using the failure analysis decision tree
+5. **Generate fix** by invoking sf-apex skill
+6. **Re-run failing test** to verify fix
+7. **Iterate** until passing or max attempts (3)
+
+## Example Agentic Flow
+
+```
+User: "Run tests for AccountService with auto-fix enabled"
+
+Claude:
+1. sf apex run test --class-names AccountServiceTest --code-coverage --result-format json
+2. Parse results: 1 failure - testBulkInsert line 45 NullPointerException
+3. Read AccountServiceTest.cls (line 45 context)
+4. Read AccountService.cls (trace the null reference)
+5. Identify: Missing null check in AccountService.processAccounts()
+6. Skill(sf-apex): Add null safety to AccountService.processAccounts()
+7. Deploy fix
+8. Re-run: sf apex run test --tests AccountServiceTest.testBulkInsert
+9. ✅ Passing! Report success.
+```
+
+## Failure Analysis Decision Tree
+
+| Error Type | Root Cause | Auto-Fix Strategy |
+|------------|------------|-------------------|
+| `System.AssertException` | Wrong expected value or logic bug | Analyze assertion, check if test or code is wrong |
+| `System.NullPointerException` | Missing null check or test data | Add null safety or fix test data setup |
+| `System.DmlException` | Validation rule, required field, trigger | Check org config, add required fields to test data |
+| `System.LimitException` | Governor limit hit | Refactor to use bulkified patterns |
+| `System.QueryException` | No rows returned | Add test data or adjust query |
+| `System.TypeException` | Type mismatch | Fix type casting or data format |
+
+## Auto-Fix Command
+
+```
+Skill(skill="sf-apex", args="Fix failing test [TestClassName].[methodName] - Error: [error message]")
+```

package/skills/running-apex-tests/references/test-patterns.md

@@ -0,0 +1,154 @@
+<!-- Parent: running-apex-tests/SKILL.md -->
+
+# Test Patterns & Templates
+
+## Pattern 1: Basic Test Class
+
+Use template: `assets/basic-test.cls`
+
+```apex
+@IsTest
+private class AccountServiceTest {
+
+    @TestSetup
+    static void setupTestData() {
+        // Use Test Data Factory for consistent data creation
+        List<Account> accounts = TestDataFactory.createAccounts(5);
+        insert accounts;
+    }
+
+    @IsTest
+    static void testCreateAccount_Success() {
+        // Given
+        Account testAccount = new Account(Name = 'Test Account');
+
+        // When
+        Test.startTest();
+        Id accountId = AccountService.createAccount(testAccount);
+        Test.stopTest();
+
+        // Then
+        Assert.isNotNull(accountId, 'Account ID should not be null');
+        Account inserted = [SELECT Name FROM Account WHERE Id = :accountId];
+        Assert.areEqual('Test Account', inserted.Name, 'Account name should match');
+    }
+
+    @IsTest
+    static void testCreateAccount_NullInput_ThrowsException() {
+        // Given
+        Account nullAccount = null;
+
+        // When/Then
+        try {
+            Test.startTest();
+            AccountService.createAccount(nullAccount);
+            Test.stopTest();
+            Assert.fail('Expected IllegalArgumentException was not thrown');
+        } catch (IllegalArgumentException e) {
+            Assert.isTrue(e.getMessage().contains('cannot be null'),
+                'Error message should mention null: ' + e.getMessage());
+        }
+    }
+}
+```
+
+## Pattern 2: Bulk Test (251+ Records)
+
+Use template: `assets/bulk-test.cls`
+
+```apex
+@IsTest
+static void testBulkInsert_251Records() {
+    // Given - 251 records crosses the 200-record batch boundary
+    List<Account> accounts = TestDataFactory.createAccounts(251);
+
+    // When
+    Test.startTest();
+    insert accounts;  // Triggers fire in batches of 200, then 51
+    Test.stopTest();
+
+    // Then
+    Integer count = [SELECT COUNT() FROM Account];
+    Assert.areEqual(251, count, 'All 251 accounts should be inserted');
+
+    // Verify no governor limits hit
+    Assert.isTrue(Limits.getQueries() < 100,
+        'Should not approach SOQL limit: ' + Limits.getQueries());
+}
+```
+
+## Pattern 3: Mock Callout Test
+
+Use template: `assets/mock-callout-test.cls`
+
+```apex
+@IsTest
+private class ExternalAPIServiceTest {
+
+    // Mock class for HTTP callouts
+    private class MockHttpResponse implements HttpCalloutMock {
+        public HttpResponse respond(HttpRequest req) {
+            HttpResponse res = new HttpResponse();
+            res.setStatusCode(200);
+            res.setBody('{"success": true, "data": {"id": "12345"}}');
+            return res;
+        }
+    }
+
+    @IsTest
+    static void testCallExternalAPI_Success() {
+        // Given
+        Test.setMock(HttpCalloutMock.class, new MockHttpResponse());
+
+        // When
+        Test.startTest();
+        String result = ExternalAPIService.callAPI('test-endpoint');
+        Test.stopTest();
+
+        // Then
+        Assert.isTrue(result.contains('success'), 'Response should indicate success');
+    }
+}
+```
+
+## Pattern 4: Test Data Factory
+
+Use template: `assets/test-data-factory.cls`
+
+```apex
+@IsTest
+public class TestDataFactory {
+
+    public static List<Account> createAccounts(Integer count) {
+        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'
+            ));
+        }
+        return accounts;
+    }
+
+    public static List<Contact> createContacts(Integer count, Id accountId) {
+        List<Contact> contacts = new List<Contact>();
+        for (Integer i = 0; i < count; i++) {
+            contacts.add(new Contact(
+                FirstName = 'Test',
+                LastName = 'Contact ' + i,
+                AccountId = accountId,
+                Email = 'test' + i + '@example.com'
+            ));
+        }
+        return contacts;
+    }
+
+    // Convenience method with insert
+    public static List<Account> createAndInsertAccounts(Integer count) {
+        List<Account> accounts = createAccounts(count);
+        insert accounts;
+        return accounts;
+    }
+}
+```