@salesforce/afv-skills 1.5.0 → 1.5.2

package/skills/generating-apex-test/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: generating-apex-test
+description: Generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking strategies, assertion best practices, and disciplined test-fix loops. Use this skill when creating new Apex test classes, improving test coverage, debugging and fixing failing Apex tests, running test execution and coverage analysis, or implementing testing patterns for triggers, services, controllers, batch jobs, queueables, and integrations. Triggers on *Test.cls, *_Test.cls files, sf apex run test workflows, coverage reports, test-fix loops. Do NOT trigger for production Apex code (use generating-apex) or Jest/LWC tests.
+---
+
+# Generating Apex Tests
+
+Generate production-ready Apex test classes and run disciplined test-fix loops with coverage analysis.
+
+## Core Principles
+
+1. **One behavior per method** — each test method validates a single scenario. Separate positive, negative, and bulk tests. NEVER combine related-but-distinct inputs (e.g., null and empty) in one method — create `_NullInput_` and `_EmptyInput_` as separate test methods
+2. **Bulkify tests** — test with 251+ records to cross the 200-record trigger batch boundary. **Batch Apex exception:** in test context only one `execute()` invocation runs, so set `batchSize >= testRecordCount`. See [references/async-testing.md](references/async-testing.md)
+3. **Isolate test data** — every `@TestSetup` must delegate record creation to a `TestDataFactory` class. If none exists, create one first. Never build record lists inline in `@TestSetup`. Never rely on org data (`SeeAllData=false`) or hardcoded IDs. For duplicate rule handling, see [references/test-data-factory.md](references/test-data-factory.md)
+4. **Assert meaningfully** — use exact expected values computed from test data setup. NEVER use range assertions or approximate counts when the value is deterministic. Always include failure messages. See [references/assertion-patterns.md](references/assertion-patterns.md)
+5. **Use `Assert` class only** — `Assert.areEqual`, `Assert.isTrue`, `Assert.fail`, etc. Never use legacy `System.assert`, `System.assertEquals`, or `System.assertNotEquals`
+6. **Mock external boundaries** — use `HttpCalloutMock` for callouts, `Test.setFixedSearchResults` for SOSL, DML mock classes for database isolation. Design for testability via constructor injection. See [references/mocking-patterns.md](references/mocking-patterns.md)
+7. **Test negative paths** — validate error handling and exception scenarios, not just happy paths
+8. **Wrap with start/stop** — pair `Test.startTest()` with `Test.stopTest()` to reset governor limits and force async execution
+
+## Test.startTest() / Test.stopTest()
+
+Always wrap the code under test in `Test.startTest()` / `Test.stopTest()`:
+
+- Resets governor limits so the test measures only the code under test
+- Executes async operations synchronously (queueables, batch, future methods)
+- Fires scheduled jobs immediately
+
+## Test Code Anti-Patterns
+
+| Anti-Pattern | Fix |
+|---|---|
+| SOQL/DML inside loops | Query once before the loop; use `Map<Id, SObject>` for lookups |
+| Magic numbers in assertions | Derive expected values from setup constants |
+| God test class (>500 lines) | Split into multiple test classes by behavior area |
+| Long test methods (>30 lines) | Extract Given/When/Then into helper methods |
+| Generic `Exception` catch | Catch the specific expected type (e.g., `DmlException`) |
+
+## Workflow
+
+### Step 1 — Gather Context
+
+Before generating or fixing tests, identify:
+
+- the target production class(es) under test
+- existing test classes, test data factories, and setup helpers
+- desired test scope (single class, specific methods, suite, or local tests)
+- coverage threshold (75% minimum for deploy, 90%+ recommended)
+- org alias when running tests against an org
+
+### Step 2 — Generate the Test Class
+
+Apply the structure, naming conventions, and patterns from the asset templates and reference docs.
+
+**MANDATORY — File Deliverables:** For every test class, create BOTH files:
+1. `{ClassName}Test.cls` — the test class (use [assets/test-class-template.cls](assets/test-class-template.cls) as starting point)
+2. `{ClassName}Test.cls-meta.xml` — the metadata file:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <status>Active</status>
+</ApexClass>
+```
+
+If no `TestDataFactory` exists in the project, create `TestDataFactory.cls` + `TestDataFactory.cls-meta.xml` using [assets/test-data-factory-template.cls](assets/test-data-factory-template.cls).
+
+#### @TestSetup Example
+
+```apex
+@TestSetup
+static void setupTestData() {
+    List<Account> accounts = TestDataFactory.createAccounts(251, true);
+}
+```
+
+#### Test Method Structure
+
+Use Given/When/Then:
+
+```apex
+@isTest
+static void shouldUpdateStatus_WhenValidInput() {
+    // Given
+    List<Account> accounts = [SELECT Id FROM Account];
+
+    // When
+    Test.startTest();
+    MyService.processAccounts(accounts);
+    Test.stopTest();
+
+    // Then
+    List<Account> updated = [SELECT Id, Status__c FROM Account];
+    Assert.areEqual(251, updated.size(), 'All accounts should be processed');
+}
+```
+
+#### Negative Test — Exception Pattern
+
+Use try/catch with `Assert.fail` to verify expected exceptions:
+
+```apex
+@isTest
+static void shouldThrowException_WhenInvalidInput() {
+    // Given
+    List<Account> emptyList = new List<Account>();
+
+    // When/Then
+    Test.startTest();
+    try {
+        MyService.processAccounts(emptyList);
+        Assert.fail('Expected MyCustomException to be thrown');
+    } catch (MyCustomException e) {
+        Assert.isTrue(e.getMessage().contains('cannot be empty'),
+            'Exception message should indicate empty input');
+    }
+    Test.stopTest();
+}
+```
+
+#### Naming Convention
+
+- `should[ExpectedResult]_When[Scenario]`: `shouldSendNotification_WhenOpportunityClosedWon`
+- `[SubjectOrAction]_[Scenario]_[ExpectedResult]`: `AccountUpdate_ChangeName_Success`
+
+### Step 3 — Run Tests
+
+Start narrow when debugging; widen after the fix is stable.
+
+```bash
+# Single test class
+sf apex run test --class-names MyServiceTest --result-format human --code-coverage --target-org <alias>
+
+# Specific test methods
+sf apex run test --tests MyServiceTest.shouldUpdateStatus_WhenValidInput --result-format human --target-org <alias>
+
+# All local tests
+sf apex run test --test-level RunLocalTests --result-format human --code-coverage --target-org <alias>
+```
+
+### Step 4 — Analyze Results
+
+Focus on:
+
+- failing methods — exception types and stack traces
+- uncovered lines and weak coverage areas
+- whether failures indicate bad test data, brittle assertions, or broken production logic
+
+### Step 5 — Fix Loop
+
+When tests fail, run a disciplined fix loop (max 3 iterations — stop and surface root cause if still failing):
+
+1. Read the failing test class and the class under test
+2. Identify root cause from error messages and stack traces
+3. Apply fix — adjust test data or assertions for test-side issues; delegate production code issues to the `generating-apex` skill
+4. Rerun the focused test before broader regression
+5. Repeat until all tests pass, iteration limit reached, or root cause requires design change
+
+### Step 6 — Validate Coverage
+
+| Level | Coverage | Purpose |
+|-------|----------|---------|
+| Production deploy | 75% minimum | Required by Salesforce |
+| Recommended | 90%+ | Best practice target |
+| Critical paths | 100% | Business-critical code |
+
+Cover all paths: positive, negative/exception, bulk (251+ records), callout/async.
+
+## What to Test by Component
+
+| Component | Key Test Scenarios |
+|-----------|-------------------|
+| Trigger | Bulk insert/update/delete, recursion guard, field change detection |
+| Service | Valid/invalid inputs, bulk operations, exception handling |
+| Controller | Page load, action methods, view state |
+| Batch | start/execute/finish, scope matching (batch size >= record count), `Database.Stateful` tracking, error handling, chaining (separate methods — `finish()` calling `Database.executeBatch()` throws `UnexpectedException`) |
+| Queueable | Chaining (only first job runs in tests), bulkification, error handling, callout mocks before `Test.startTest()` |
+| Callout | Success response, error response, timeout |
+| Selector | Valid/null/empty inputs, bulk (251+), field population, sort order, `WITH USER_MODE` via `System.runAs` |
+| Scheduled | Direct execution via `execute(null)`, CRON registration via `CronTrigger` query |
+| Platform Event | `Test.enableChangeDataCapture()`, `Test.getEventBus().deliver()`, verify subscriber side effects |
+
+## Output Expectations
+
+Deliverables per test class:
+- `{ClassName}Test.cls` + `{ClassName}Test.cls-meta.xml` (match API version of class under test; default `66.0`)
+- `TestDataFactory.cls` + `TestDataFactory.cls-meta.xml` (if not already present)
+
+## Reference Files
+
+Load on demand for detailed patterns:
+
+| Reference | When to use |
+|-----------|-------------|
+| [references/test-data-factory.md](references/test-data-factory.md) | TestDataFactory patterns, field overrides, duplicate rule handling |
+| [references/assertion-patterns.md](references/assertion-patterns.md) | Assertion best practices, anti-patterns, common pitfalls |
+| [references/mocking-patterns.md](references/mocking-patterns.md) | HttpCalloutMock, DML mocking, StubProvider, SOSL, Email, Platform Events |
+| [references/async-testing.md](references/async-testing.md) | Batch, Queueable, Future, Scheduled job testing |

package/skills/generating-apex-test/assets/test-class-template.cls

@@ -0,0 +1,93 @@
+/**
+ * @description Test class for {ClassUnderTest}.
+ *              Tests bulk operations (251+ records), positive/negative paths,
+ *              and exception handling.
+ */
+@isTest
+private class {ClassUnderTest}Test {
+
+    @TestSetup
+    static void setupTestData() {
+        List<Account> accounts = TestDataFactory.createAccounts(251, true);
+    }
+
+    // ─── Positive Tests ───────────────────────────────────────────────────
+
+    @isTest
+    static void shouldPerformExpectedBehavior_WhenValidInput() {
+        // Given
+        List<Account> accounts = [SELECT Id, Name FROM Account];
+
+        // When
+        Test.startTest();
+        // {ClassUnderTest}.methodUnderTest(params);
+        Test.stopTest();
+
+        // Then
+        // Assert.areEqual(expected, actual, 'Descriptive failure message');
+    }
+
+    @isTest
+    static void shouldHandleBulkRecords_WhenProcessing251() {
+        // Given
+        List<Account> accounts = [SELECT Id FROM Account];
+        Assert.areEqual(251, accounts.size(), 'Should have 251 test records');
+
+        // When
+        Test.startTest();
+        // {ClassUnderTest}.bulkMethod(accounts);
+        Test.stopTest();
+
+        // Then
+        // List<Account> results = [SELECT Id, Status__c FROM Account];
+        // for (Account acc : results) {
+        //     Assert.areEqual('Processed', acc.Status__c, 'All records should be processed');
+        // }
+    }
+
+    // ─── Negative Tests ───────────────────────────────────────────────────
+
+    @isTest
+    static void shouldThrowException_WhenNullInput() {
+        Test.startTest();
+        try {
+            // {ClassUnderTest}.methodUnderTest(null);
+            Assert.fail('Expected exception for null input');
+        } catch (MyCustomException e) {
+            Assert.isTrue(e.getMessage().contains('cannot be null'),
+                'Exception message should mention null input');
+        }
+        Test.stopTest();
+    }
+
+    @isTest
+    static void shouldReturnEmpty_WhenEmptyInput() {
+        Test.startTest();
+        // List<SObject> results = {ClassUnderTest}.methodUnderTest(new List<Id>());
+        Test.stopTest();
+
+        // Assert.isTrue(results.isEmpty(), 'Should return empty list for empty input');
+    }
+
+    // ─── Edge Case Tests ──────────────────────────────────────────────────
+
+    @isTest
+    static void shouldHandleMixedRecords_WhenSomeQualify() {
+        // Given
+        List<Account> accounts = [SELECT Id, Status__c FROM Account];
+        Integer half = accounts.size() / 2;
+        // for (Integer i = 0; i < half; i++) {
+        //     accounts[i].Status__c = 'Qualifying';
+        // }
+        // update accounts;
+
+        // When
+        Test.startTest();
+        // {ClassUnderTest}.conditionalMethod(accounts);
+        Test.stopTest();
+
+        // Then
+        // List<Account> qualifying = [SELECT Id FROM Account WHERE Processed__c = true];
+        // Assert.areEqual(half, qualifying.size(), 'Only qualifying records should be processed');
+    }
+}

package/skills/generating-apex-test/assets/test-data-factory-template.cls

@@ -0,0 +1,111 @@
+/**
+ * @description Centralized factory for creating test data with sensible defaults.
+ *              All methods accept a doInsert flag for flexibility.
+ *              Bulk methods create multiple records; single-record methods delegate to bulk.
+ */
+@isTest
+public class TestDataFactory {
+
+    // ─── Accounts ─────────────────────────────────────────────────────────
+
+    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,
+                BillingCity = 'San Francisco',
+                BillingState = 'CA',
+                BillingCountry = 'USA',
+                Industry = 'Technology',
+                Type = 'Customer'
+            ));
+        }
+        if (doInsert) insert accounts;
+        return accounts;
+    }
+
+    public static Account createAccount(Boolean doInsert) {
+        return createAccounts(1, doInsert)[0];
+    }
+
+    // ─── Contacts ─────────────────────────────────────────────────────────
+
+    public static List<Contact> createContacts(List<Account> accounts, Integer countPerAccount, Boolean doInsert) {
+        List<Contact> contacts = new List<Contact>();
+        Integer idx = 0;
+        for (Account acc : accounts) {
+            for (Integer i = 0; i < countPerAccount; i++) {
+                contacts.add(new Contact(
+                    FirstName = 'Test',
+                    LastName = 'Contact ' + idx,
+                    Email = 'test.contact' + idx + '@example.com',
+                    AccountId = acc.Id
+                ));
+                idx++;
+            }
+        }
+        if (doInsert) insert contacts;
+        return contacts;
+    }
+
+    // ─── Opportunities ────────────────────────────────────────────────────
+
+    public static List<Opportunity> createOpportunities(List<Account> accounts, Integer countPerAccount, Boolean doInsert) {
+        List<Opportunity> opps = new List<Opportunity>();
+        Integer idx = 0;
+        for (Account acc : accounts) {
+            for (Integer i = 0; i < countPerAccount; i++) {
+                opps.add(new Opportunity(
+                    Name = 'Test Opportunity ' + idx,
+                    AccountId = acc.Id,
+                    StageName = 'Prospecting',
+                    CloseDate = Date.today().addDays(30),
+                    Amount = 10000 + (idx * 1000)
+                ));
+                idx++;
+            }
+        }
+        if (doInsert) insert opps;
+        return opps;
+    }
+
+    // ─── Users ────────────────────────────────────────────────────────────
+
+    public static User createUser(String profileName, Boolean doInsert) {
+        Profile p = [SELECT Id FROM Profile WHERE Name = :profileName LIMIT 1];
+        String uniqueKey = String.valueOf(DateTime.now().getTime());
+
+        User u = new User(
+            FirstName = 'Test',
+            LastName = 'User ' + uniqueKey,
+            Email = 'testuser' + uniqueKey + '@example.com',
+            Username = 'testuser' + uniqueKey + '@example.com.test',
+            Alias = 'tuser',
+            TimeZoneSidKey = 'America/Los_Angeles',
+            LocaleSidKey = 'en_US',
+            EmailEncodingKey = 'UTF-8',
+            LanguageLocaleKey = 'en_US',
+            ProfileId = p.Id
+        );
+        if (doInsert) insert u;
+        return u;
+    }
+
+    // ─── Field Override Pattern ────────────────────────────────────────────
+
+    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;
+    }
+
+    // ─── Custom Objects ───────────────────────────────────────────────────
+    // Add methods for your custom objects following the same pattern:
+    // public static List<MyObject__c> createMyObjects(Integer count, Boolean doInsert) { ... }
+}

package/skills/generating-apex-test/references/assertion-patterns.md

@@ -0,0 +1,108 @@
+# Assertion Patterns
+
+## Assertion Methods
+
+| Method | Use Case |
+|--------|----------|
+| `Assert.areEqual(expected, actual, msg)` | Exact equality |
+| `Assert.areNotEqual(expected, actual, msg)` | Value should differ |
+| `Assert.isTrue(condition, msg)` | Boolean condition |
+| `Assert.isFalse(condition, msg)` | Negated boolean condition |
+| `Assert.fail(msg)` | Force failure (e.g., expected exception not thrown) |
+| `Assert.isNotNull(value, msg)` | Non-null check |
+| `Assert.isNull(value, msg)` | Null check |
+
+**Always include the message parameter** — makes test failures actionable.
+
+## Good vs Bad Assertions
+
+### Bad: No message, tests coverage not behavior
+
+```apex
+Assert.isTrue(result); // no message
+Assert.isTrue(accounts.size() > 0); // vague — use areEqual with exact count
+```
+
+### Good: Descriptive message, tests specific behavior
+
+```apex
+Assert.areEqual(true, result, 'Service should return true for valid input');
+Assert.areEqual(200, accounts.size(), 'All 200 accounts should be processed');
+```
+
+## Common Assertion Patterns
+
+### Collection Size
+
+```apex
+Assert.areEqual(200, results.size(), 'Should process all 200 records');
+Assert.isTrue(results.isEmpty(), 'No results expected for invalid input');
+Assert.isFalse(results.isEmpty(), 'Results should not be empty');
+```
+
+### Field Values
+
+```apex
+Assert.areEqual('Processed', acc.Status__c, 'Account status should be updated to Processed');
+
+for (Account acc : updatedAccounts) {
+    Assert.areEqual('Active', acc.Status__c,
+        'Account ' + acc.Name + ' should have Active status');
+}
+```
+
+### Exception Testing
+
+```apex
+@isTest
+static void shouldThrowException_WhenInputInvalid() {
+    Test.startTest();
+    try {
+        MyService.process(null);
+        Assert.fail('Expected MyCustomException for null input');
+    } catch (MyCustomException e) {
+        Assert.isTrue(e.getMessage().contains('cannot be null'),
+            'Exception message should mention null input');
+    }
+    Test.stopTest();
+}
+```
+
+### DML Results
+
+```apex
+// Insert success
+Database.SaveResult[] results = Database.insert(accounts, false);
+for (Database.SaveResult sr : results) {
+    Assert.isTrue(sr.isSuccess(), 'Insert should succeed: ' + sr.getErrors());
+}
+
+Database.SaveResult sr = Database.insert(invalidAccount, false);
+Assert.isFalse(sr.isSuccess(), 'Insert should fail for invalid data');
+Assert.isTrue(sr.getErrors()[0].getMessage().contains('REQUIRED_FIELD_MISSING'),
+    'Error should indicate missing required field');
+```
+
+### Null Checks
+
+```apex
+Assert.isNull(result.ErrorMessage__c, 'No error expected for valid input');
+Assert.isNotNull(result.Id, 'Record should have been inserted');
+```
+
+### Date/DateTime
+
+```apex
+Assert.areEqual(Date.today(), record.CreatedDate__c, 'Should be created today');
+Assert.isTrue(record.DueDate__c >= Date.today(), 'Due date should be in the future');
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Fix |
+|---|---|
+| `Assert.isTrue(results.size() > 0)` | Use `Assert.areEqual(expectedCount, results.size(), ...)` |
+| `Assert.isTrue(results.size() >= expected)` | Compute exact expected count, use `Assert.areEqual` |
+| Testing implementation not behavior | Assert on observable outcomes (field values, record counts) |
+| Missing negative test assertions | Verify the actual outcome, not just that no exception occurred |
+| `Assert.isTrue(count != 0)` | Use `Assert.areEqual` with deterministic value from test data |