sf-forcekit 1.0.0

package/templates/ai-dir/testing-strategy.md

@@ -0,0 +1,342 @@
+# Testing Strategy
+
+> How we test, what we test, and why. Agents MUST follow these patterns.
+
+---
+
+## Testing Philosophy
+
+1. **Test behavior, not implementation** — Assert what the code *does*, not how it does it.
+2. **Bulk by default** — Every test uses 200+ records unless explicitly testing a single-record path.
+3. **Negative paths are mandatory** — If a method can fail, test the failure.
+4. **Permissions matter** — Test with restricted users, not just System Administrator.
+5. **No org data** — `SeeAllData=true` is permanently banned.
+
+---
+
+## Coverage Requirements
+
+| Target | Minimum | Standard |
+|--------|---------|----------|
+| Per class | 75% | **90%+** |
+| Org-wide | 75% | **85%+** |
+| New code (PRs) | 90% | **95%+** |
+
+---
+
+## Test Categories
+
+### Unit Tests (Required for every class)
+
+Tests a single method in isolation. Mock all dependencies.
+
+```apex
+@IsTest
+private class AccountServiceTest {
+
+    @TestSetup
+    static void setupTestData() {
+        // Use TestDataFactory — never hardcode test data inline
+        List<Account> accounts = TestDataFactory.createAccounts(200);
+        insert accounts;
+    }
+
+    @IsTest
+    static void testProcessAccounts_BulkPositive() {
+        // Arrange
+        List<Account> accounts = [SELECT Id, Name FROM Account];
+        System.assertEquals(200, accounts.size(), 'Setup should create 200 accounts');
+
+        // Act
+        Test.startTest();
+        AccountService.processAccounts(accounts);
+        Test.stopTest();
+
+        // Assert
+        List<Account> updated = [SELECT Id, Status__c FROM Account WHERE Id IN :accounts];
+        for (Account a : updated) {
+            System.assertNotEquals(null, a.Status__c, 'Status should be set after processing');
+        }
+    }
+
+    @IsTest
+    static void testProcessAccounts_EmptyList() {
+        // Negative: empty input should not throw
+        Test.startTest();
+        AccountService.processAccounts(new List<Account>());
+        Test.stopTest();
+        // No exception = pass
+    }
+
+    @IsTest
+    static void testProcessAccounts_NullInput() {
+        // Negative: null input should throw
+        try {
+            AccountService.processAccounts(null);
+            System.assert(false, 'Should have thrown exception for null input');
+        } catch (AccountServiceException e) {
+            System.assert(e.getMessage().contains('cannot be null'),
+                'Exception message should mention null: ' + e.getMessage());
+        }
+    }
+}
+```
+
+### Integration Tests (Required for callouts & triggers)
+
+Tests end-to-end flow including DML and trigger execution.
+
+```apex
+@IsTest
+private class AccountTriggerTest {
+
+    @TestSetup
+    static void setupTestData() {
+        List<Account> accounts = TestDataFactory.createAccounts(200);
+        insert accounts;
+    }
+
+    @IsTest
+    static void testAfterUpdate_StatusChange_FiresRelatedUpdate() {
+        // Arrange
+        List<Account> accounts = [SELECT Id, Status__c FROM Account];
+        for (Account a : accounts) {
+            a.Status__c = 'Active';
+        }
+
+        // Act — trigger fires on update
+        Test.startTest();
+        update accounts;
+        Test.stopTest();
+
+        // Assert — check related records were updated
+        List<Contact> contacts = [SELECT Id, Account_Status__c FROM Contact WHERE AccountId IN :accounts];
+        for (Contact c : contacts) {
+            System.assertEquals('Active', c.Account_Status__c,
+                'Contact should reflect parent Account status');
+        }
+    }
+}
+```
+
+### Callout Mock Tests (Required for all integrations)
+
+```apex
+@IsTest
+private class ExternalApiServiceTest {
+
+    private class MockSuccess implements HttpCalloutMock {
+        public HttpResponse respond(HttpRequest req) {
+            HttpResponse res = new HttpResponse();
+            res.setStatusCode(200);
+            res.setBody('{"status":"success","id":"ext-123"}');
+            res.setHeader('Content-Type', 'application/json');
+            return res;
+        }
+    }
+
+    private class MockFailure implements HttpCalloutMock {
+        public HttpResponse respond(HttpRequest req) {
+            HttpResponse res = new HttpResponse();
+            res.setStatusCode(500);
+            res.setBody('{"error":"Internal Server Error"}');
+            return res;
+        }
+    }
+
+    @IsTest
+    static void testCallExternalApi_Success() {
+        Test.setMock(HttpCalloutMock.class, new MockSuccess());
+
+        Test.startTest();
+        ApiResponseDTO result = ExternalApiService.callExternalApi('/orders', 'GET', null);
+        Test.stopTest();
+
+        System.assertEquals('success', result.status, 'Should parse success response');
+    }
+
+    @IsTest
+    static void testCallExternalApi_ServerError() {
+        Test.setMock(HttpCalloutMock.class, new MockFailure());
+
+        Test.startTest();
+        try {
+            ExternalApiService.callExternalApi('/orders', 'GET', null);
+            System.assert(false, 'Should throw IntegrationException on 500');
+        } catch (IntegrationException e) {
+            System.assert(e.getMessage().contains('500'),
+                'Exception should contain status code');
+        }
+        Test.stopTest();
+    }
+}
+```
+
+### Permission Tests (Required for customer-facing features)
+
+```apex
+@IsTest
+private class AccountService_PermissionTest {
+
+    @IsTest
+    static void testReadAccess_RestrictedUser() {
+        // Create a user with minimal permissions
+        User restrictedUser = TestDataFactory.createUser('Standard User');
+
+        System.runAs(restrictedUser) {
+            Test.startTest();
+            try {
+                List<Account> results = AccountService.getAccounts(new Set<Id>());
+                // Should return empty, not throw
+                System.assertEquals(0, results.size(), 'Restricted user should see no accounts');
+            } catch (Exception e) {
+                System.assert(false,
+                    'Should not throw for restricted user, should return empty: ' + e.getMessage());
+            }
+            Test.stopTest();
+        }
+    }
+}
+```
+
+---
+
+## TestDataFactory Pattern
+
+Every project MUST have a `TestDataFactory` class. Never create test data inline.
+
+```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'
+            ));
+        }
+        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;
+    }
+
+    public static User createUser(String profileName) {
+        Profile p = [SELECT Id FROM Profile WHERE Name = :profileName LIMIT 1];
+        return new User(
+            FirstName = 'Test',
+            LastName = 'User',
+            Email = 'testuser@example.com',
+            Username = 'testuser' + DateTime.now().getTime() + '@example.com',
+            Alias = 'tuser',
+            ProfileId = p.Id,
+            TimeZoneSidKey = 'America/New_York',
+            LocaleSidKey = 'en_US',
+            EmailEncodingKey = 'UTF-8',
+            LanguageLocaleKey = 'en_US'
+        );
+    }
+}
+```
+
+---
+
+## Test Naming Convention
+
+```
+{MethodName}_{Scenario}_{ExpectedResult}
+```
+
+| Example | Meaning |
+|---------|---------|
+| `testGetAccounts_ValidIds_ReturnsAccounts` | Happy path |
+| `testGetAccounts_EmptySet_ReturnsEmpty` | Empty input |
+| `testGetAccounts_NullInput_ThrowsException` | Null input |
+| `testGetAccounts_200Records_NoLimitErrors` | Bulk test |
+| `testGetAccounts_RestrictedUser_ReturnsEmpty` | Permission |
+
+---
+
+## Governor Limit Testing
+
+```apex
+@IsTest
+static void testBulkProcessing_200Records_NoGovernorViolations() {
+    List<Account> accounts = TestDataFactory.createAccounts(200);
+    insert accounts;
+
+    Test.startTest();
+
+    Integer queriesBefore = Limits.getQueries();
+    Integer dmlBefore = Limits.getDmlStatements();
+
+    AccountService.processAccounts(accounts);
+
+    Integer queriesUsed = Limits.getQueries() - queriesBefore;
+    Integer dmlUsed = Limits.getDmlStatements() - dmlBefore;
+
+    Test.stopTest();
+
+    // Assert governor-friendly behavior
+    System.assert(queriesUsed <= 5,
+        'Should use ≤5 SOQL queries for 200 records, used: ' + queriesUsed);
+    System.assert(dmlUsed <= 3,
+        'Should use ≤3 DML statements for 200 records, used: ' + dmlUsed);
+}
+```
+
+---
+
+## Test Execution Commands
+
+```bash
+# Run all local tests
+sf apex run test --target-org <target_org> --code-coverage --result-format human --test-level RunLocalTests
+
+# Run one test class
+sf apex run test --target-org <target_org> --tests AccountServiceTest --code-coverage --result-format human
+
+# Run one test method
+sf apex run test --target-org <target_org> --tests "AccountServiceTest.testBulkInsert" --code-coverage --result-format human
+
+# Run tests with JSON output (for CI/CD parsing)
+sf apex run test --target-org <target_org> --code-coverage --result-format json --output-dir test-results --json
+```
+
+---
+
+## What NOT to Test
+
+| Don't Test | Why |
+|-----------|-----|
+| Standard Salesforce behavior (e.g., required field validation) | Platform handles it |
+| Getter/setter methods with no logic | Trivial, adds no value |
+| Private methods directly | Test through public interface |
+| Platform UI behavior | Not testable via Apex |
+
+---
+
+## Test Review Checklist
+
+- [ ] Uses `@TestSetup` for shared data
+- [ ] `SeeAllData=true` is NOT used
+- [ ] Tests 200+ records (bulk)
+- [ ] Tests negative paths (null, empty, invalid)
+- [ ] Tests permission scenarios (`System.runAs`)
+- [ ] Tests callout mocks (`HttpCalloutMock`)
+- [ ] Every assertion has a meaningful message
+- [ ] `Test.startTest()` / `Test.stopTest()` bracket the action
+- [ ] No hardcoded IDs in test data
+- [ ] Coverage ≥ 90%