@salesforce/afv-skills 1.5.0 → 1.5.2

package/skills/generating-apex-test/references/async-testing.md

@@ -0,0 +1,193 @@
+# Async Testing Patterns
+
+## Key Principle
+
+`Test.stopTest()` forces all async operations to execute synchronously, allowing assertions on their results.
+
+## Batch Apex Testing
+
+### Basic Batch Test
+
+**Critical:** In test context only one `execute()` invocation runs, so always set `batchSize >= testRecordCount` (e.g., `Database.executeBatch(batch, 200)` with 200 records). Never create more records than the batch size.
+
+```apex
+@isTest
+static void shouldProcessAllRecords_WhenBatchExecutes() {
+    List<Account> accounts = TestDataFactory.createAccounts(200, true);
+
+    Test.startTest();
+    MyBatchClass batch = new MyBatchClass();
+    Id batchId = Database.executeBatch(batch, 200);
+    Test.stopTest();
+
+    List<Account> updated = [SELECT Id, Status__c FROM Account];
+    for (Account acc : updated) {
+        Assert.areEqual('Processed', acc.Status__c,
+            'Batch should update all account statuses');
+    }
+}
+```
+
+### Batch with Failures
+
+```apex
+@isTest
+static void shouldLogErrors_WhenRecordsFail() {
+    List<Account> accounts = TestDataFactory.createAccounts(198, true);
+
+    List<Account> invalidAccounts = new List<Account>();
+    for (Integer i = 0; i < 2; i++) {
+        invalidAccounts.add(new Account(
+            Name = 'Invalid Account ' + i,
+            Invalid_Field__c = 'triggers_validation_error'
+        ));
+    }
+    insert invalidAccounts;
+
+    Test.startTest();
+    MyBatchClass batch = new MyBatchClass();
+    Database.executeBatch(batch, 200);
+    Test.stopTest();
+
+    List<Error_Log__c> errors = [SELECT Id, Message__c FROM Error_Log__c];
+    Assert.areEqual(2, errors.size(), 'Should log 2 failed records');
+}
+```
+
+### Batch Chaining
+
+Test `finish()` chaining in a **separate test method** — calling `Database.executeBatch()` inside `finish()` during a test can throw `UnexpectedException`. Verify the first batch independently, then test that `finish()` enqueues the next batch.
+
+## Queueable Testing
+
+### Basic Queueable Test
+
+```apex
+@isTest
+static void shouldCompleteProcessing_WhenQueueableEnqueued() {
+    Account acc = TestDataFactory.createAccount(true);
+
+    Test.startTest();
+    MyQueueableClass queueable = new MyQueueableClass(acc.Id);
+    System.enqueueJob(queueable);
+    Test.stopTest();
+
+    Account updated = [SELECT Id, Status__c FROM Account WHERE Id = :acc.Id];
+    Assert.areEqual('Processed', updated.Status__c,
+        'Queueable should update account status');
+}
+```
+
+### Queueable Chaining
+
+Only the **first** chained queueable executes in tests. Design tests to verify:
+1. First job completes correctly
+2. Chain is properly enqueued (query `AsyncApexJob`)
+3. Each job works independently in its own test method
+
+```apex
+@isTest
+static void shouldChainNextJob_WhenMoreRecordsExist() {
+    List<Account> accounts = TestDataFactory.createAccounts(500, true);
+
+    Test.startTest();
+    MyChainedQueueable queueable = new MyChainedQueueable(0, 100);
+    System.enqueueJob(queueable);
+    Test.stopTest();
+
+    List<Account> processed = [SELECT Id FROM Account WHERE Processed__c = true];
+    Assert.areEqual(100, processed.size(), 'First batch should process 100 records');
+
+    List<AsyncApexJob> jobs = [
+        SELECT Id, Status, JobType
+        FROM AsyncApexJob
+        WHERE ApexClass.Name = 'MyChainedQueueable'
+    ];
+    Assert.isTrue(jobs.size() >= 1, 'Chained job should be enqueued');
+}
+```
+
+### Queueable with Callouts
+
+Set the callout mock **before** `Test.startTest()`:
+
+```apex
+@isTest
+static void shouldMakeCallout_WhenQueueableWithCallout() {
+    Test.setMock(HttpCalloutMock.class, new MockHttpResponse(200, '{"status":"ok"}'));
+    Account acc = TestDataFactory.createAccount(true);
+
+    Test.startTest();
+    MyQueueableWithCallout queueable = new MyQueueableWithCallout(acc.Id);
+    System.enqueueJob(queueable);
+    Test.stopTest();
+
+    Account updated = [SELECT Id, External_Status__c FROM Account WHERE Id = :acc.Id];
+    Assert.areEqual('Synced', updated.External_Status__c,
+        'Should update status after successful callout');
+}
+```
+
+## Future Method Testing
+
+```apex
+@isTest
+static void shouldExecuteFutureMethod() {
+    Account acc = TestDataFactory.createAccount(true);
+
+    Test.startTest();
+    MyClass.processFuture(acc.Id);
+    Test.stopTest();
+
+    Account updated = [SELECT Id, Processed__c FROM Account WHERE Id = :acc.Id];
+    Assert.areEqual(true, updated.Processed__c, 'Future should process record');
+}
+```
+
+## Scheduled Apex Testing
+
+### Direct Execution
+
+```apex
+@isTest
+static void shouldExecuteScheduledJob() {
+    List<Account> accounts = TestDataFactory.createAccounts(50, true);
+
+    Test.startTest();
+    MyScheduledClass scheduled = new MyScheduledClass();
+    scheduled.execute(null);
+    Test.stopTest();
+
+    List<Account> processed = [SELECT Id FROM Account WHERE Processed__c = true];
+    Assert.areEqual(50, processed.size(), 'Scheduled job should process records');
+}
+```
+
+### CRON Registration
+
+```apex
+@isTest
+static void shouldScheduleJob() {
+    Test.startTest();
+    String cronExp = '0 0 6 * * ?';
+    String jobId = System.schedule('Daily Processing', cronExp, new MyScheduledClass());
+    Test.stopTest();
+
+    CronTrigger ct = [
+        SELECT Id, CronExpression, State
+        FROM CronTrigger
+        WHERE Id = :jobId
+    ];
+    Assert.areEqual('0 0 6 * * ?', ct.CronExpression, 'CRON should match');
+    Assert.areEqual('WAITING', ct.State, 'Job should be waiting');
+}
+```
+
+## Common Pitfalls
+
+| Pitfall | Impact |
+|---|---|
+| Missing `Test.stopTest()` | Async never executes, assertions fail silently |
+| Expecting all chained queueables to run | Only the first runs; test each independently |
+| Mock set after `Test.startTest()` | Callout mock must be set **before** `Test.startTest()` |
+| Batch size < record count in tests | Only `batchSize` records processed; set `batchSize >= recordCount` |

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

@@ -0,0 +1,220 @@
+# Mocking Patterns
+
+## HTTP Callout Mocking
+
+Apex doesn't allow real HTTP callouts in tests. Use `HttpCalloutMock` interface.
+
+### Basic Mock
+
+```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() {
+    String mockResponse = '{"status": "success", "data": [{"id": "123"}]}';
+    Test.setMock(HttpCalloutMock.class, new MockHttpResponse(200, mockResponse));
+
+    Test.startTest();
+    List<ExternalRecord> results = MyIntegrationService.fetchRecords();
+    Test.stopTest();
+
+    Assert.areEqual(1, results.size(), 'Should parse one record from response');
+    Assert.areEqual('123', results[0].externalId, 'Should extract correct ID');
+}
+
+@isTest
+static void shouldHandleError_WhenCalloutFails() {
+    String errorResponse = '{"error": "Unauthorized"}';
+    Test.setMock(HttpCalloutMock.class, new MockHttpResponse(401, errorResponse));
+
+    Test.startTest();
+    CalloutResult result = MyIntegrationService.fetchRecords();
+    Test.stopTest();
+
+    Assert.areEqual(false, result.isSuccess, 'Should indicate failure');
+    Assert.isTrue(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);
+            }
+        }
+        HttpResponse res = new HttpResponse();
+        res.setStatusCode(404);
+        res.setBody('{"error": "Not found"}');
+        return res;
+    }
+}
+```
+
+### StaticResourceCalloutMock
+
+Use when response JSON is large or complex:
+
+```apex
+@isTest
+static void shouldParseComplexResponse() {
+    StaticResourceCalloutMock mock = new StaticResourceCalloutMock();
+    mock.setStaticResource('TestApiResponse');
+    mock.setStatusCode(200);
+    mock.setHeader('Content-Type', 'application/json');
+    Test.setMock(HttpCalloutMock.class, mock);
+
+    Test.startTest();
+    Result r = MyService.callExternalApi();
+    Test.stopTest();
+
+    Assert.isNotNull(r, 'Should parse response');
+}
+```
+
+## SOSL Mocking
+
+SOSL returns empty results in tests by default. Call `Test.setFixedSearchResults(List<Id>)` before the search:
+
+```apex
+@isTest
+static void shouldReturnSearchResults() {
+    Account acc = TestDataFactory.createAccount(true);
+    Test.setFixedSearchResults(new List<Id>{ acc.Id });
+
+    Test.startTest();
+    List<Account> results = MyService.searchAccounts('Test');
+    Test.stopTest();
+
+    Assert.areEqual(1, results.size(), 'Should return mocked search result');
+}
+```
+
+## DML Mocking (Constructor Injection)
+
+Design for testability — use a public constructor for production and a `@TestVisible private` constructor that accepts mock interfaces:
+
+```apex
+public class MyService {
+    private IDML dmlHandler;
+
+    public MyService() {
+        this.dmlHandler = new DMLHandler();
+    }
+
+    @TestVisible
+    private MyService(IDML dmlHandler) {
+        this.dmlHandler = dmlHandler;
+    }
+
+    public void createRecords(List<Account> accounts) {
+        dmlHandler.doInsert(accounts);
+    }
+}
+```
+
+## Stub API (System.StubProvider)
+
+For mocking Apex class dependencies:
+
+```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;
+    }
+}
+
+@isTest
+static void shouldUseAccountData() {
+    MyServiceMock mockProvider = new MyServiceMock();
+    IMyService mockService = (IMyService) Test.createStub(IMyService.class, mockProvider);
+
+    MyController controller = new MyController(mockService);
+
+    Test.startTest();
+    String result = controller.displayAccountInfo();
+    Test.stopTest();
+
+    Assert.isTrue(result.contains('Mock Account'), 'Should use mocked data');
+}
+```
+
+## Email Testing
+
+Apex doesn't actually send emails in tests. Use limits to verify:
+
+```apex
+@isTest
+static void shouldSendEmail_WhenTriggered() {
+    Integer emailsBefore = Limits.getEmailInvocations();
+
+    Test.startTest();
+    MyService.sendNotification(testContact);
+    Test.stopTest();
+
+    Assert.areEqual(emailsBefore + 1, Limits.getEmailInvocations(),
+        'One email should be sent');
+}
+```
+
+## Platform Event Testing
+
+```apex
+@isTest
+static void shouldPublishEvent_WhenRecordCreated() {
+    Test.startTest();
+    Test.enableChangeDataCapture();
+
+    Account acc = TestDataFactory.createAccount(true);
+    Test.getEventBus().deliver();
+    Test.stopTest();
+    
+    // Query platform event trigger results
+    List<EventLog__c> logs = [SELECT Id FROM EventLog__c WHERE AccountId__c = :acc.Id];
+    Assert.areEqual(1, logs.size(), 'Event handler should create log record');
+}
+```

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

@@ -0,0 +1,75 @@
+# TestDataFactory Patterns
+
+For the base class template, see [assets/test-data-factory-template.cls](../assets/test-data-factory-template.cls).
+
+## Design Rules
+
+1. **Always accept a `doInsert` flag** — lets callers modify records before insert
+2. **Append loop index to all fields that participate in matching rules** — prevents `DUPLICATES_DETECTED` errors from active Duplicate Rules
+3. **Single-record methods delegate to bulk** — e.g., `createAccount(doInsert)` calls `createAccounts(1, doInsert)[0]`
+4. **Return created records** — enables chaining and further manipulation
+5. **Set all required fields** — include fields enforced by validation rules, not just schema-required fields
+
+## Field Override Pattern
+
+Allow callers to override default values 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' => 'Custom Name',
+    'Industry' => 'Healthcare'
+}, true);
+```
+
+## 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;
+}
+```
+
+## Handling Duplicate Rules
+
+When unique field values alone are not sufficient, use `Database.insert()` with a `DuplicateRuleHeader`:
+
+```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 = 'Test Account ' + i,
+            Phone = '555-000-' + String.valueOf(i).leftPad(4, '0')
+        ));
+    }
+    if (doInsert) {
+        Database.DMLOptions dml = new Database.DMLOptions();
+        dml.DuplicateRuleHeader.allowSave = true;
+        Database.insert(accounts, dml);
+    }
+    return accounts;
+}
+```

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

@@ -1,12 +1,12 @@
 ---
 name: generating-experience-react-site
-description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React web application. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a web app, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React web application site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my web application.\""
+description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React UI bundle. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a UI bundle, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React UI bundle site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my UI bundle.\""
 ---
 
-# Digital Experience Site for React Web Applications
-Create and configure Digital Experience Sites that host React web applications on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the `sfdc_cms__site` content type — so a React app can be served from Salesforce.
+# Digital Experience Site for React UI Bundles
+Create and configure Digital Experience Sites that host React UI bundles on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the `sfdc_cms__site` content type — so a React app can be served from Salesforce.
 
-React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (`appContainer: true`) that delegates rendering to the React application referenced by `appSpace`.
+React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (`appContainer: true`) that delegates rendering to the React UI bundle referenced by `appSpace`.
 
 ## Required Properties
 Resolve all five properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.
@@ -14,9 +14,9 @@ Resolve all five properties before generating any metadata. Each has a fallback
 | Property | Format | How to Resolve |
 |----------|--------|----------------|
 | **siteName** | `UpperCamelCase` (e.g., `MyCommunity`) | Ask user or derive from context |
-| **siteUrlPathPrefix** | `kebab-case` (e.g., `my-community`) | User-provided, or convert siteName to kebab-case |
+| **siteUrlPathPrefix** | `All lowercase` (e.g., `mycommunity`) | User-provided, or convert siteName to all lowercase with alphanumeric characters only |
 | **appNamespace** | String | `namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c` |
-| **appDevName** | String | `webApplication` metadata in the project → `sf data query -q "SELECT DeveloperName FROM WebApplication" --target-org ${usernameOrAlias}` → default to siteName |
+| **appDevName** | String | `UIBundle` metadata in the project → `sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias}` → default to siteName |
 | **enableGuestAccess** | Boolean | Ask user whether unauthenticated guest users can access site APIs → default `false` |
 
 The `appNamespace` and `appDevName` properties connect the site to the correct React application. Getting these wrong means the site deploys but shows a blank page, so take care to resolve them from real project data.
@@ -26,7 +26,7 @@ The `appNamespace` and `appDevName` properties connect the site to the correct R
 Determine values for all five properties before constructing anything. Use the resolution strategies in the table above, falling through each option until a value is found.
 
 ### Step 2: Create the Project Structure
-Call the `get_metadata_api_context` MCP tool to retrieve schemas for `Network`, `CustomSite`, `DigitalExperienceConfig`, and `DigitalExperienceBundle` metadata types. These schemas define the valid XML structure for each file.
+Use available Salesforce metadata schema and field context for `Network`, `CustomSite`, `DigitalExperienceConfig`, and `DigitalExperienceBundle` to ensure each file uses valid structure.
 
 Create any files and directories that don't already exist, using these paths:
 
@@ -51,8 +51,19 @@ 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.
+Address any extra configurations the user requests. Use the metadata sections and field context identified in Step 2 to understand each field’s purpose and constraints, then update only the minimum necessary fields.
 
 ## Verification Checklist
 Before deploying, confirm:
@@ -60,7 +71,7 @@ Before deploying, confirm:
 - [ ] All five required properties are resolved
 - [ ] All metadata directories and files exist per the project structure
 - [ ] All metadata fields are populated per the templates and user requests
-- [ ] `appSpace` in `content.json` matches an existing `WebApplication` metadata record
+- [ ] `appSpace` in `content.json` matches an existing `UIBundle` metadata record
 - [ ] Deployment validates successfully:
 ```bash
 sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}

package/skills/generating-experience-react-site/docs/configure-metadata-digital-experience.md

@@ -3,7 +3,7 @@
 ## Purpose
 These configuration files create **net-new, default** DigitalExperience content records (`sfdc_cms__site` type) for a Digital Experience React Site. They are not intended to edit or modify existing DigitalExperience content. Use these templates only when provisioning a brand-new React site.
 
-The `appContainer: true` and `appSpace` fields in `content.json` are what make this a React site rather than a standard LWR site. The `appSpace` value follows the format `{namespace}__{developerName}` and must match a deployed `WebApplication` metadata record.
+The `appContainer: true` and `appSpace` fields in `content.json` are what make this a React site rather than a standard LWR site. The `appSpace` value follows the format `{namespace}__{developerName}` and must match a deployed `UIBundle` metadata record.
 
 ## File Location
 The DigitalExperience directory contains only `_meta.json` and `content.json`. Do not create any directories other than `sfdc_cms__site` inside the bundle.