@salesforce/afv-skills 1.5.0 → 1.5.1

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

@@ -0,0 +1,219 @@
+# Mocking Patterns
+
+## HTTP Callout Mocking
+
+Apex doesn't allow real HTTP callouts in tests. Use `HttpCalloutMock` interface.
+
+### Basic Mock Implementation
+
+```apex
+@isTest
+public class MockHttpResponse implements HttpCalloutMock {
+    
+    private Integer statusCode;
+    private String body;
+    
+    public MockHttpResponse(Integer statusCode, String body) {
+        this.statusCode = statusCode;
+        this.body = body;
+    }
+    
+    public HTTPResponse respond(HTTPRequest req) {
+        HttpResponse res = new HttpResponse();
+        res.setStatusCode(statusCode);
+        res.setBody(body);
+        res.setHeader('Content-Type', 'application/json');
+        return res;
+    }
+}
+```
+
+### Using the Mock
+
+```apex
+@isTest
+static void shouldProcessApiResponse_WhenCalloutSucceeds() {
+    // Given
+    String mockResponse = '{"status": "success", "data": [{"id": "123"}]}';
+    Test.setMock(HttpCalloutMock.class, new MockHttpResponse(200, mockResponse));
+    
+    // When
+    Test.startTest();
+    List<ExternalRecord> results = MyIntegrationService.fetchRecords();
+    Test.stopTest();
+    
+    // Then
+    System.assertEquals(1, results.size(), 'Should parse one record from response');
+    System.assertEquals('123', results[0].externalId, 'Should extract correct ID');
+}
+
+@isTest
+static void shouldHandleError_WhenCalloutFails() {
+    // Given
+    String errorResponse = '{"error": "Unauthorized"}';
+    Test.setMock(HttpCalloutMock.class, new MockHttpResponse(401, errorResponse));
+    
+    // When
+    Test.startTest();
+    CalloutResult result = MyIntegrationService.fetchRecords();
+    Test.stopTest();
+    
+    // Then
+    System.assertEquals(false, result.isSuccess, 'Should indicate failure');
+    System.assert(result.errorMessage.contains('Unauthorized'), 'Should capture error');
+}
+```
+
+### Multi-Request Mock
+
+For services making multiple callouts:
+
+```apex
+@isTest
+public class MultiRequestMock implements HttpCalloutMock {
+    
+    private Map<String, HttpResponse> endpointResponses;
+    
+    public MultiRequestMock(Map<String, HttpResponse> responses) {
+        this.endpointResponses = responses;
+    }
+    
+    public HTTPResponse respond(HTTPRequest req) {
+        String endpoint = req.getEndpoint();
+        
+        for (String key : endpointResponses.keySet()) {
+            if (endpoint.contains(key)) {
+                return endpointResponses.get(key);
+            }
+        }
+        
+        // Default 404 if no match
+        HttpResponse res = new HttpResponse();
+        res.setStatusCode(404);
+        res.setBody('{"error": "Not found"}');
+        return res;
+    }
+}
+
+// Usage:
+Map<String, HttpResponse> mocks = new Map<String, HttpResponse>();
+
+HttpResponse authResponse = new HttpResponse();
+authResponse.setStatusCode(200);
+authResponse.setBody('{"token": "abc123"}');
+mocks.put('/oauth/token', authResponse);
+
+HttpResponse dataResponse = new HttpResponse();
+dataResponse.setStatusCode(200);
+dataResponse.setBody('{"records": []}');
+mocks.put('/api/records', dataResponse);
+
+Test.setMock(HttpCalloutMock.class, new MultiRequestMock(mocks));
+```
+
+## StaticResourceCalloutMock
+
+For complex response bodies, store JSON in Static Resources:
+
+```apex
+@isTest
+static void shouldParseComplexResponse() {
+    StaticResourceCalloutMock mock = new StaticResourceCalloutMock();
+    mock.setStaticResource('TestApiResponse'); // Static Resource name
+    mock.setStatusCode(200);
+    mock.setHeader('Content-Type', 'application/json');
+    
+    Test.setMock(HttpCalloutMock.class, mock);
+    
+    Test.startTest();
+    Result r = MyService.callExternalApi();
+    Test.stopTest();
+    
+    System.assertNotEquals(null, r, 'Should parse response');
+}
+```
+
+## Stub API (Enterprise Pattern)
+
+For mocking Apex class dependencies using `System.StubProvider`:
+
+```apex
+@isTest
+public class MyServiceMock implements System.StubProvider {
+    
+    public Object handleMethodCall(
+        Object stubbedObject,
+        String stubbedMethodName,
+        Type returnType,
+        List<Type> paramTypes,
+        List<String> paramNames,
+        List<Object> args
+    ) {
+        if (stubbedMethodName == 'getAccountData') {
+            return new AccountData('Mock Account', 'Active');
+        }
+        return null;
+    }
+}
+
+// Usage in test:
+@isTest
+static void shouldUseAccountData() {
+    MyServiceMock mockProvider = new MyServiceMock();
+    IMyService mockService = (IMyService)Test.createStub(IMyService.class, mockProvider);
+    
+    // Inject mock into class under test
+    MyController controller = new MyController(mockService);
+    
+    Test.startTest();
+    String result = controller.displayAccountInfo();
+    Test.stopTest();
+    
+    System.assert(result.contains('Mock Account'), 'Should use mocked data');
+}
+```
+
+## Email Mocking
+
+Apex sends real emails by default. Use limits to verify:
+
+```apex
+@isTest
+static void shouldSendEmail_WhenTriggered() {
+    Integer emailsBefore = Limits.getEmailInvocations();
+    
+    Test.startTest();
+    MyService.sendNotification(testContact);
+    Test.stopTest();
+    
+    // Verify email was queued (not actually sent in tests)
+    System.assertEquals(
+        emailsBefore + 1, 
+        Limits.getEmailInvocations(), 
+        'One email should be sent'
+    );
+}
+```
+
+## Platform Event Testing
+
+```apex
+@isTest
+static void shouldPublishEvent_WhenRecordCreated() {
+    Test.startTest();
+    
+    // Enable event delivery in test context
+    Test.enableChangeDataCapture();
+    
+    Account acc = TestDataFactory.createAccount(true);
+    
+    // Deliver events
+    Test.getEventBus().deliver();
+    
+    Test.stopTest();
+    
+    // Query platform event trigger results
+    List<EventLog__c> logs = [SELECT Id FROM EventLog__c WHERE AccountId__c = :acc.Id];
+    System.assertEquals(1, logs.size(), 'Event handler should create log record');
+}
+```

package/skills/generating-apex-test/references/test-data-factory.md

@@ -0,0 +1,176 @@
+# TestDataFactory Patterns
+
+## Overview
+
+TestDataFactory is a centralized utility class for creating test records with sensible defaults. It ensures consistent test data across all test classes and reduces duplication.
+
+## Base Template
+
+```apex
+@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,
+                BillingStreet = '123 Test St',
+                BillingCity = 'San Francisco',
+                BillingState = 'CA',
+                BillingPostalCode = '94105',
+                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 index = 0;
+        for (Account acc : accounts) {
+            for (Integer i = 0; i < countPerAccount; i++) {
+                contacts.add(new Contact(
+                    FirstName = 'Test',
+                    LastName = 'Contact ' + index,
+                    Email = 'test.contact' + index + '@example.com',
+                    Phone = '555-000-' + String.valueOf(index).leftPad(4, '0'),
+                    AccountId = acc.Id
+                ));
+                index++;
+            }
+        }
+        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 index = 0;
+        for (Account acc : accounts) {
+            for (Integer i = 0; i < countPerAccount; i++) {
+                opps.add(new Opportunity(
+                    Name = 'Test Opportunity ' + index,
+                    AccountId = acc.Id,
+                    StageName = 'Prospecting',
+                    CloseDate = Date.today().addDays(30),
+                    Amount = 10000 + (index * 1000)
+                ));
+                index++;
+            }
+        }
+        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;
+    }
+    
+    // ============ CUSTOM OBJECTS ============
+    
+    // Add methods for your custom objects following the same pattern:
+    // public static List<MyObject__c> createMyObjects(Integer count, Boolean doInsert) { ... }
+}
+```
+
+## Field Override Pattern
+
+Allow callers to override default values:
+
+```apex
+public static Account createAccount(Map<String, Object> fieldOverrides, Boolean doInsert) {
+    Account acc = new Account(
+        Name = 'Test Account',
+        Industry = 'Technology'
+    );
+    
+    // Apply overrides
+    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' => 'Custom Name',
+    'Industry' => 'Healthcare'
+}, true);
+```
+
+## Handling Required Fields and Validation Rules
+
+```apex
+public static Account createAccountWithRequiredFields(Boolean doInsert) {
+    Account acc = new Account(
+        Name = 'Test Account',
+        // Required custom fields
+        External_Id__c = 'EXT-' + String.valueOf(DateTime.now().getTime()),
+        // Fields required by validation rules
+        Phone = '555-123-4567',
+        Website = 'https://example.com'
+    );
+    if (doInsert) insert acc;
+    return acc;
+}
+```
+
+## Record Type Support
+
+```apex
+public static Account createAccountByRecordType(String recordTypeName, Boolean doInsert) {
+    Id recordTypeId = Schema.SObjectType.Account
+        .getRecordTypeInfosByDeveloperName()
+        .get(recordTypeName)
+        .getRecordTypeId();
+    
+    Account acc = new Account(
+        Name = 'Test Account',
+        RecordTypeId = recordTypeId
+    );
+    if (doInsert) insert acc;
+    return acc;
+}
+```
+
+## Best Practices
+
+1. **Always include doInsert parameter** - Allows flexibility for tests that need to modify records before insert
+2. **Use unique identifiers** - Include index or timestamp in Name/Email fields to avoid duplicates
+3. **Set all required fields** - Include all fields required by validation rules
+4. **Return the created records** - Enables chaining and further manipulation
+5. **Create bulk methods first** - Single record methods should call bulk methods with count=1

package/skills/generating-experience-react-site/SKILL.md

@@ -51,6 +51,17 @@ Use the default templates in the docs below. Values in `{braces}` are resolved p
 | DigitalExperienceBundle | [configure-metadata-digital-experience-bundle.md](docs/configure-metadata-digital-experience-bundle.md) |
 | DigitalExperience (sfdc_cms__site) | [configure-metadata-digital-experience.md](docs/configure-metadata-digital-experience.md) |
 
+### Execution Note for Step 3: Load and use the docs
+- Agents MUST read the full contents of each docs/*.md file referenced in Step 3 before attempting to populate metadata fields.
+- Use your platform's file-read tool (for example, `read_file`) to load these files in full, then perform placeholder substitution for values in `{braces}` using the resolved properties from Step 1.
+- Files to load:
+  - `docs/configure-metadata-network.md`
+  - `docs/configure-metadata-custom-site.md`
+  - `docs/configure-metadata-digital-experience-config.md`
+  - `docs/configure-metadata-digital-experience-bundle.md`
+  - `docs/configure-metadata-digital-experience.md`
+- Read entire file contents, replace placeholders (e.g. `{siteName}`) with the resolved values, then use the expanded templates to populate the metadata XML/JSON content.
+  
 ### Step 4: Resolve Additional Configurations
 Address any extra configurations the user requests. Use the schemas returned by `get_metadata_api_context` in Step 2 to understand each field's purpose, and update only the minimum necessary fields.
 

package/skills/generating-flexipage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-flexipage
-description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like \"create a Lightning page\", \"add a component to a page\", \"customize the record page\", \"generate a FlexiPage\", or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention \"page\" in the context of Salesforce."
+description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like 'create a Lightning page', 'add a component to a page', 'customize the record page', 'generate a FlexiPage', or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention 'page' in the context of Salesforce."
 ---
 
 ## When to Use This Skill
@@ -20,6 +20,8 @@ Use this skill when you need to:
 
 ## Overview
 
+**CRITICAL: When creating NEW FlexiPages, you MUST ALWAYS start with the CLI template command.** Never create FlexiPage XML from scratch - the CLI provides valid structure, proper regions, and correct component configuration that prevents deployment errors.
+
 Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping for component discovery and configuration.
 
 ---
@@ -28,6 +30,8 @@ Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping
 
 ### Step 1: Bootstrap with CLI
 
+**MANDATORY FOR NEW PAGES: This step is NOT optional.** Always use the CLI template command when creating a new FlexiPage. The CLI generates valid XML structure, proper regions, and correct metadata that prevents common deployment errors. Only skip this step if you're editing an existing FlexiPage file.
+
 ```bash
 sf template generate flexipage \
   --name <PageName> \
@@ -39,19 +43,22 @@ sf template generate flexipage \
   --output-dir force-app/main/default/flexipages
 ```
 
-**Template-specific requirements:**
-- **RecordPage**: Requires `--sobject` (e.g., Account, Custom_Object__c)
-- **RecordPage**: Requires `--primary-field` and `--secondary-fields` for dynamic highlights, `--detail-fields` for full record details. Use the most important identifying field as primary, e.g. Name. Use the secondary fields (max 12, recommended 4-6) to show a summary of the record. Use detail fields to show the full details of the record.
-- **AppPage**: No additional requirements
-- **HomePage**: No additional requirements
-
 **Note:** If the `sf template generate flexipage` command fails, recommend users upgrade to the latest version of the Salesforce CLI:
 ```bash
 npm install -g @salesforce/cli@latest
 ```
 
+#### **Field Selection Guidelines**
+- **Validate fields exist**: Use MCP tools or describe commands to discover available fields for the object before specifying them in the command
+- **Prefer compound fields**: Use `Name` (not `FirstName`/`LastName`), `BillingAddress` (not `BillingStreet`/`BillingCity`/`BillingState`), `MailingAddress`, etc. when available
 
-**What you get:**
+#### **Template-specific requirements**
+- **RecordPage**: Requires `--sobject` (e.g., Account, Custom_Object__c)
+- **RecordPage**: Requires `--primary-field` and `--secondary-fields` for dynamic highlights, `--detail-fields` for full record details. Use the most important identifying field as primary, e.g. Name. Use the secondary fields (max 12, recommended 4-6) to show a summary of the record. Use detail fields to show the full details of the record.
+- **AppPage**: No additional requirements
+- **HomePage**: No additional requirements
+
+#### **What you get**
 - Valid FlexiPage XML with correct structure
 - Pre-configured regions and basic components
 - Proper field references and facet structure
@@ -59,17 +66,31 @@ npm install -g @salesforce/cli@latest
 
 ### Step 2: Deploy Base Page
 
+Run a **dry-run** deployment of the entire project to validate the page and dependencies:
 ```bash
-sf project deploy start --source-dir force-app/main/default/flexipages
+sf project deploy start --dry-run -d "force-app/main/default" --test-level NoTestRun --wait 10 --json
 ```
 
-**Deploy early, deploy often.** Start with the bootstrapped page, validate it works, then enhance.
+**Critical:** Fix any deployment errors before proceeding. The page must validate successfully.
+
+### Step 3: **STOP - No Further Modifications**
+
+**MANDATORY: Stop after Step 2. Do not add components or edit the FlexiPage XML.**
 
-### Step 3: Update and Redeploy
+This applies even if the user requested:
+- Additional components
+- Page customization
+- Component configuration
 
-Modify the generated XML, adding components discovered via MCP. Deploy incrementally.
+What you CAN do:
+- Suggest what components would be useful
+- Explain what enhancements are possible
+- Document what would need to be added manually
 
-**Note:** Warn users to use caution with updates beyond this step when using this command.
+What you CANNOT do:
+- Modify the XML file
+- Add any components
+- Make any enhancements
 
 ---
 
@@ -215,6 +236,10 @@ Every fieldInstance requires:
 
 ## Common Deployment Errors
 
+### "We couldn't retrieve or load the information on the field"
+**Cause:** Invalid field API name - field doesn't exist on the object or has incorrect spelling
+**Fix:** Use MCP tools or describe commands to discover valid fields, then update the field reference (see Field Selection Guidelines)
+
 ### "Invalid field reference"
 **Cause:** Used `ObjectName.Field` instead of `Record.Field`  
 **Fix:** Change to `Record.{FieldApiName}`
@@ -245,49 +270,6 @@ Every fieldInstance requires:
 
 ---
 
-## Incremental Development Pattern
-
-**Philosophy:** Deploy small, working increments. Don't build entire complex page at once.
-
-**Process:**
-1. **CLI bootstrap** → Deploy base page
-2. **Add one component** → Deploy
-3. **Add another component** → Deploy
-4. **Repeat** until complete
-
-**Benefits:**
-- Isolated errors (know exactly what broke)
-- Faster debugging
-- Build confidence with each success
-- Get user feedback early
-
-**Anti-pattern:** Building entire complex page → one giant error cascade.
-
----
-
-## Adding Components to Existing FlexiPages
-
-### Workflow
-
-When user provides an existing FlexiPage file path:
-
-1. **Read the file** using native file I/O
-2. **Parse XML** to extract:
-   - **ALL existing component identifiers** (search for all `<identifier>` tags)
-   - **ALL existing region/facet names** (search for all `<name>` tags in `<flexiPageRegions>`)
-   - Available regions (parse from file, don't assume names)
-   - Existing facets
-3. **Verify uniqueness** - ensure your new identifiers and names don't conflict with ANY existing ones
-4. **Check if target facet exists** - if adding to a named facet like `detailTabContent` that already exists:
-   - **Add new `<itemInstances>` to existing region** (don't create duplicate region)
-   - **Insert before the closing `</flexiPageRegions>` tag of that region**
-5. **Generate component XML** (apply all rules from "Critical XML Rules" section)
-6. **Insert** into appropriate region or add itemInstances to existing facet
-7. **Write** modified XML back to file
-8. **Deploy**: `sf project deploy start --source-dir force-app/...`
-
----
-
 ### Generating Unique Identifiers
 
 **CRITICAL: Before generating ANY new identifier or facet name, follow the rules in section 5 of "Critical XML Rules" above.**
@@ -474,7 +456,7 @@ Identifier Pattern: flexipage_richText or flexipage_richText_{sequence}
 ## Validation Checklist
 
 Before deploying:
-- [ ] Used CLI to bootstrap (don't start from scratch)
+- [ ] **[NEW PAGES ONLY]** Used CLI to bootstrap - NEVER create FlexiPage XML from scratch
 - [ ] **ALL identifiers are unique** - no duplicate `<identifier>` values anywhere in file
 - [ ] **ALL region/facet names are unique** - no duplicate `<name>` values in `<flexiPageRegions>`
 - [ ] **Multiple components in same facet are combined** - ONE region with multiple `<itemInstances>`, NOT separate regions with same name