@salesforce/afv-skills 1.8.0 → 1.9.1

package/skills/running-apex-tests/references/testing-best-practices.md

@@ -0,0 +1,509 @@
+<!-- Parent: running-apex-tests/SKILL.md -->
+# Apex Testing Best Practices
+
+## Overview
+
+This guide covers best practices for writing effective, maintainable Apex tests that ensure code quality and prevent regressions.
+
+## The Testing Pyramid
+
+```
+                    ╱╲
+                   ╱  ╲
+                  ╱ E2E╲        Few end-to-end tests
+                 ╱──────╲
+                ╱        ╲
+               ╱Integration╲    Moderate integration tests
+              ╱────────────╲
+             ╱              ╲
+            ╱   Unit Tests   ╲  Many unit tests
+           ╱──────────────────╲
+```
+
+## Core Principles
+
+### 1. Test One Thing Per Method
+
+```apex
+// ❌ BAD: Testing multiple things
+@IsTest
+static void testEverything() {
+    Account acc = new Account(Name = 'Test');
+    insert acc;
+    acc.Name = 'Updated';
+    update acc;
+    delete acc;
+    // What exactly are we testing?
+}
+
+// ✅ GOOD: Single responsibility
+@IsTest
+static void testAccountInsert_ValidName_Success() {
+    Account acc = new Account(Name = 'Test');
+    insert acc;
+    Assert.isNotNull(acc.Id, 'Account should be inserted');
+}
+
+@IsTest
+static void testAccountUpdate_ChangeName_Success() {
+    Account acc = TestDataFactory.createAndInsertAccounts(1)[0];
+    acc.Name = 'Updated';
+    update acc;
+    Account updated = [SELECT Name FROM Account WHERE Id = :acc.Id];
+    Assert.areEqual('Updated', updated.Name, 'Name should be updated');
+}
+```
+
+### 2. Use Descriptive Test Names
+
+```apex
+// ❌ BAD: Unclear names
+@IsTest static void test1() { }
+@IsTest static void testMethod() { }
+
+// ✅ GOOD: Describes scenario, condition, and expectation
+@IsTest static void testCreateAccount_WithValidData_ReturnsId() { }
+@IsTest static void testCreateAccount_WithNullName_ThrowsException() { }
+@IsTest static void testBulkInsert_251Records_AllSucceed() { }
+```
+
+### 3. Follow AAA Pattern (Arrange-Act-Assert)
+
+```apex
+@IsTest
+static void testCalculateDiscount_VIPCustomer_Returns20Percent() {
+    // ARRANGE - Set up test data
+    Account vipAccount = new Account(
+        Name = 'VIP Customer',
+        Type = 'VIP'
+    );
+    insert vipAccount;
+
+    // ACT - Execute the code under test
+    Test.startTest();
+    Decimal discount = DiscountService.calculateDiscount(vipAccount.Id);
+    Test.stopTest();
+
+    // ASSERT - Verify results
+    Assert.areEqual(0.20, discount, 'VIP customers should get 20% discount');
+}
+```
+
+## Test Data Factory Pattern
+
+### Why Use Test Data Factory?
+
+1. **Consistency**: Same data creation logic everywhere
+2. **Maintainability**: Change in one place affects all tests
+3. **Readability**: Tests focus on logic, not data setup
+4. **Flexibility**: Easy to create variations
+
+### Factory Methods
+
+```apex
+@IsTest
+public class TestDataFactory {
+
+    // Basic creation (no insert)
+    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;
+    }
+
+    // Create and insert
+    public static List<Account> createAndInsertAccounts(Integer count) {
+        List<Account> accounts = createAccounts(count);
+        insert accounts;
+        return accounts;
+    }
+
+    // With specific attributes
+    public static Account createAccount(String name, String industry) {
+        return new Account(Name = name, Industry = industry);
+    }
+}
+```
+
+## @TestSetup for Efficiency
+
+```apex
+@IsTest
+private class AccountServiceTest {
+
+    @TestSetup
+    static void setupTestData() {
+        // This runs ONCE for all test methods in the class
+        // Data is rolled back after each test method
+        List<Account> accounts = TestDataFactory.createAccounts(10);
+        insert accounts;
+
+        List<Contact> contacts = new List<Contact>();
+        for (Account acc : accounts) {
+            contacts.addAll(TestDataFactory.createContacts(5, acc.Id));
+        }
+        insert contacts;
+    }
+
+    @IsTest
+    static void testMethod1() {
+        // Has access to 10 accounts and 50 contacts
+        List<Account> accounts = [SELECT Id FROM Account];
+        Assert.areEqual(10, accounts.size());
+    }
+
+    @IsTest
+    static void testMethod2() {
+        // ALSO has access to 10 accounts and 50 contacts
+        // @TestSetup data is available to all test methods
+        List<Contact> contacts = [SELECT Id FROM Contact];
+        Assert.areEqual(50, contacts.size());
+    }
+}
+```
+
+## Bulk Testing (251+ Records)
+
+### Why 251 Records?
+
+Triggers process records in batches of 200. Testing with 251 records ensures:
+- First batch: 200 records
+- Second batch: 51 records
+- Crosses the batch boundary, revealing bulkification issues
+
+```apex
+@IsTest
+static void testTrigger_BulkInsert_NoDMLInLoop() {
+    // ARRANGE
+    List<Account> accounts = TestDataFactory.createAccounts(251);
+
+    // ACT
+    Test.startTest();
+    insert accounts;  // Trigger fires twice: 200, then 51
+    Test.stopTest();
+
+    // ASSERT
+    Assert.areEqual(251, [SELECT COUNT() FROM Account],
+        'All 251 accounts should be created');
+
+    // Verify governor limits not approached
+    Assert.isTrue(Limits.getQueries() < 90,
+        'Should not approach SOQL limit');
+}
+```
+
+## Negative Testing
+
+### Test for Expected Failures
+
+```apex
+@IsTest
+static void testCreateAccount_NullName_ThrowsException() {
+    try {
+        Account acc = new Account(Name = null);
+        insert acc;
+        Assert.fail('Expected DmlException was not thrown');
+    } catch (DmlException e) {
+        Assert.isTrue(
+            e.getMessage().contains('REQUIRED_FIELD_MISSING'),
+            'Should throw required field error'
+        );
+    }
+}
+
+@IsTest
+static void testWithdraw_InsufficientFunds_ReturnsFalse() {
+    Account acc = TestDataFactory.createAndInsertAccounts(1)[0];
+    acc.AnnualRevenue = 100;
+    update acc;
+
+    Test.startTest();
+    Boolean result = AccountService.withdraw(acc.Id, 200);
+    Test.stopTest();
+
+    Assert.isFalse(result, 'Withdrawal should fail with insufficient funds');
+}
+```
+
+## Mock Framework Patterns
+
+### HttpCalloutMock
+
+```apex
+private class SuccessHttpMock implements HttpCalloutMock {
+    public HttpResponse respond(HttpRequest req) {
+        HttpResponse res = new HttpResponse();
+        res.setStatusCode(200);
+        res.setBody('{"success": true}');
+        return res;
+    }
+}
+
+@IsTest
+static void testExternalAPICall_Success() {
+    Test.setMock(HttpCalloutMock.class, new SuccessHttpMock());
+
+    Test.startTest();
+    String result = MyService.callExternalAPI();
+    Test.stopTest();
+
+    Assert.isTrue(result.contains('success'));
+}
+```
+
+### Stub API (Test.StubProvider)
+
+```apex
+@IsTest
+private class AccountServiceTest {
+
+    // Stub for dependency injection
+    private class SelectorStub implements System.StubProvider {
+        public Object handleMethodCall(
+            Object stubbedObject,
+            String stubbedMethodName,
+            Type returnType,
+            List<Type> paramTypes,
+            List<String> paramNames,
+            List<Object> args
+        ) {
+            if (stubbedMethodName == 'getAccountById') {
+                return new Account(Name = 'Mocked Account');
+            }
+            return null;
+        }
+    }
+
+    @IsTest
+    static void testServiceWithMockedSelector() {
+        // Create stub
+        AccountSelector mockSelector = (AccountSelector) Test.createStub(
+            AccountSelector.class,
+            new SelectorStub()
+        );
+
+        // Inject into service
+        AccountService service = new AccountService(mockSelector);
+
+        // Test with mocked dependency
+        Test.startTest();
+        Account result = service.getAccount('001xx000000001');
+        Test.stopTest();
+
+        Assert.areEqual('Mocked Account', result.Name);
+    }
+}
+```
+
+## Governor Limit Testing
+
+```apex
+@IsTest
+static void testBulkOperation_StaysWithinLimits() {
+    List<Account> accounts = TestDataFactory.createAccounts(200);
+
+    Test.startTest();
+    insert accounts;
+    Test.stopTest();
+
+    // Assert limits not exceeded
+    System.debug('SOQL queries used: ' + Limits.getQueries());
+    System.debug('DML statements used: ' + Limits.getDmlStatements());
+
+    Assert.isTrue(Limits.getQueries() < 100,
+        'Should stay under SOQL limit: ' + Limits.getQueries());
+    Assert.isTrue(Limits.getDmlStatements() < 150,
+        'Should stay under DML limit: ' + Limits.getDmlStatements());
+}
+```
+
+## Common Anti-Patterns to Avoid
+
+### ❌ SeeAllData=true
+
+```apex
+// ❌ BAD: Depends on org data
+@IsTest(SeeAllData=true)
+static void testBadPattern() {
+    Account acc = [SELECT Id FROM Account LIMIT 1];
+    // This will fail in empty orgs!
+}
+
+// ✅ GOOD: Creates own data
+@IsTest
+static void testGoodPattern() {
+    Account acc = TestDataFactory.createAndInsertAccounts(1)[0];
+    // Works in any org
+}
+```
+
+### ❌ No Assertions
+
+```apex
+// ❌ BAD: No assertions - test passes even if code is broken
+@IsTest
+static void testNoAssertions() {
+    Account acc = new Account(Name = 'Test');
+    insert acc;
+    // Test "passes" but proves nothing
+}
+
+// ✅ GOOD: Meaningful assertions
+@IsTest
+static void testWithAssertions() {
+    Account acc = new Account(Name = 'Test');
+    insert acc;
+    Assert.isNotNull(acc.Id, 'Account should have an Id after insert');
+    Account inserted = [SELECT Name FROM Account WHERE Id = :acc.Id];
+    Assert.areEqual('Test', inserted.Name, 'Name should be preserved');
+}
+```
+
+### ❌ Hardcoded IDs
+
+```apex
+// ❌ BAD: Hardcoded IDs fail across orgs
+Account acc = [SELECT Id FROM Account WHERE Id = '001xx0000000001'];
+
+// ✅ GOOD: Query or create dynamically
+Account acc = TestDataFactory.createAndInsertAccounts(1)[0];
+```
+
+## Test Method Template
+
+```apex
+/**
+ * @description Tests [method] with [condition] expecting [outcome]
+ */
+@IsTest
+static void test[Method]_[Condition]_[ExpectedOutcome]() {
+    // ═══════════════════════════════════════════════════════════════
+    // ARRANGE - Set up test data and conditions
+    // ═══════════════════════════════════════════════════════════════
+    // Create test data using TestDataFactory
+    // Set up any mocks needed
+
+    // ═══════════════════════════════════════════════════════════════
+    // ACT - Execute the code under test
+    // ═══════════════════════════════════════════════════════════════
+    Test.startTest();
+    // Call the method being tested
+    Test.stopTest();
+
+    // ═══════════════════════════════════════════════════════════════
+    // ASSERT - Verify expected outcomes
+    // ═══════════════════════════════════════════════════════════════
+    // Assert.areEqual(expected, actual, 'Descriptive message');
+    // Assert.isTrue(condition, 'Descriptive message');
+    // Assert.isNotNull(value, 'Descriptive message');
+}
+```
+
+---
+
+## Test Speed Philosophy
+
+### Why Test Speed Matters
+
+Fast tests enable continuous integration. Slow tests become barriers to frequent commits.
+
+### Target Metrics
+
+| Test Type | Target Speed | Purpose |
+|-----------|--------------|---------|
+| Unit test (no DML) | < 50ms | Test pure business logic |
+| Unit test (mocked DML) | < 100ms | Test with stubbed database |
+| Integration test | < 500ms | Verify real database behavior |
+| Full scenario test | < 2000ms | End-to-end validation |
+
+### Speed Strategy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  INTEGRATION TESTS (Few)                                    │
+│  - Real DML, real triggers                                  │
+│  - Test happy path completely                               │
+│  - Slow but high confidence                                 │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  UNIT TESTS WITH MOCKS (Many)                               │
+│  - Stub database operations                                 │
+│  - Test edge cases, variations                              │
+│  - Fast, run on every save                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Balance Reality vs Speed
+
+```apex
+// INTEGRATION TEST: Full database interaction (slower, realistic)
+@IsTest
+static void testAccountCreation_Integration() {
+    Test.startTest();
+    Account acc = new Account(Name = 'Test');
+    insert acc;
+    Test.stopTest();
+
+    Account queried = [SELECT Name, Status__c FROM Account WHERE Id = :acc.Id];
+    Assert.areEqual('Active', queried.Status__c, 'Trigger should set status');
+}
+
+// UNIT TEST: Mocked database (faster, tests logic only)
+@IsTest
+static void testAccountRules_IsHighValue() {
+    // No database interaction - tests pure logic
+    Account acc = new Account(AnnualRevenue = 1500000);
+    Assert.isTrue(AccountRules.isHighValue(acc), 'Should be high value');
+
+    Account lowValue = new Account(AnnualRevenue = 500000);
+    Assert.isFalse(AccountRules.isHighValue(lowValue), 'Should not be high value');
+}
+```
+
+### Techniques for Faster Tests
+
+| Technique | Benefit | Trade-off |
+|-----------|---------|-----------|
+| @TestSetup | Reuse data across methods | Small setup overhead |
+| Stub API | No real DML | Less realistic |
+| Selector mocking | Skip SOQL | Must trust Selector |
+| Domain class testing | Pure logic, no DB | Limited scope |
+| Avoid SeeAllData | Predictable data | Must create test data |
+
+### When to Prioritize Speed vs Reality
+
+| Scenario | Priority | Approach |
+|----------|----------|----------|
+| Business logic validation | Speed | Unit test with mocks |
+| Trigger behavior | Reality | Integration test |
+| Edge case coverage | Speed | Many unit tests |
+| Deployment validation | Reality | RunLocalTests |
+| Developer feedback loop | Speed | Fast unit tests |
+
+### Measuring Test Speed
+
+```bash
+# Run tests and view timing
+sf apex run test --test-level RunLocalTests --target-org alias --result-format human
+
+# Check individual test timing
+sf apex get test --test-run-id [id] --code-coverage --result-format json | jq '.tests[] | {name: .MethodName, time: .RunTime}'
+```
+
+### Fast Test Checklist
+
+```
+□ Is there a pure logic portion that can be unit tested?
+□ Can database operations be mocked for edge cases?
+□ Is @TestSetup reused across multiple test methods?
+□ Are tests avoiding SeeAllData=true?
+□ Are integration tests reserved for critical paths only?
+□ Can SOQL be mocked via Selector pattern?
+```

package/skills/segmenting-datacloud/CREDITS.md

@@ -0,0 +1,3 @@
+# Credits & Acknowledgments
+
+This skill is part of the `*-datacloud` family of skills covering the Salesforce Data Cloud workflow phases. Shared definitions, templates, and readiness scripts for this family live in the `orchestrating-datacloud` skill directory.

package/skills/segmenting-datacloud/README.md

@@ -0,0 +1,36 @@
+# segmenting-datacloud
+
+Audience and insight workflows for Salesforce Data Cloud.
+
+## Use this skill for
+
+- creating and publishing segments
+- managing calculated insights
+- checking segment counts
+- troubleshooting segment SQL
+- understanding why a segment is empty or unexpectedly large
+
+## Example requests
+
+```text
+"Create a high-value customer segment in Data Cloud"
+"Why is my segment returning zero members?"
+"Run this calculated insight and help me verify it"
+"Show me how to get member counts for this segment"
+```
+
+## Common commands
+
+```bash
+sf data360 segment list -o myorg 2>/dev/null
+sf data360 segment create -o myorg -f segment.json --api-version 64.0 2>/dev/null
+sf data360 segment publish -o myorg --name High_Value_Customers 2>/dev/null
+sf data360 calculated-insight list -o myorg 2>/dev/null
+```
+
+## References
+
+- [SKILL.md](SKILL.md)
+- [../orchestrating-datacloud/assets/definitions/calculated-insight.template.json](../orchestrating-datacloud/assets/definitions/calculated-insight.template.json)
+- [../orchestrating-datacloud/assets/definitions/segment.template.json](../orchestrating-datacloud/assets/definitions/segment.template.json)
+- [CREDITS.md](CREDITS.md)

package/skills/segmenting-datacloud/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: segmenting-datacloud
+description: "Salesforce Data Cloud Segment phase. Use this skill when the user creates or publishes segments, manages calculated insights, or troubleshoots audience SQL in Data Cloud. TRIGGER when: user creates or publishes segments, manages calculated insights, inspects segment counts or membership, or troubleshoots audience SQL in Data Cloud. DO NOT TRIGGER when: the task is DMO/mapping/identity-resolution work (use harmonizing-datacloud), activation work (use activating-datacloud), query/search-index work (use retrieving-datacloud), or Standard Data Model (STDM)/session tracing (use observing-agentforce)."
+license: MIT
+compatibility: "Requires an external community sf data360 CLI plugin and a Data Cloud-enabled org"
+metadata:
+  version: "1.0"
+---
+
+# segmenting-datacloud: Data Cloud Segment Phase
+
+Use this skill when the user needs **audience and insight work**: segments, calculated insights, publish workflows, member counts, or troubleshooting Data Cloud segment SQL.
+
+## When This Skill Owns the Task
+
+Use `segmenting-datacloud` when the work involves:
+- `sf data360 segment *`
+- `sf data360 calculated-insight *`
+- segment publish workflows
+- member counts and segment troubleshooting
+- calculated insight execution and verification
+
+Delegate elsewhere when the user is:
+- still building Data Model Objects (DMOs), mappings, or identity resolution → [harmonizing-datacloud](../harmonizing-datacloud/SKILL.md)
+- activating a segment downstream → [activating-datacloud](../activating-datacloud/SKILL.md)
+- writing read-only SQL or search-index queries → [retrieving-datacloud](../retrieving-datacloud/SKILL.md)
+
+---
+
+## Required Context to Gather First
+
+Ask for or infer:
+- target org alias
+- unified DMO (Data Model Object) or base entity name
+- whether the user wants create, publish, inspect, or troubleshoot
+- whether the asset is a segment or calculated insight
+- expected success metric: member count, aggregate value, or publish status
+
+---
+
+## Core Operating Rules
+
+- Treat Data Cloud segment SQL as distinct from CRM SOQL.
+- Run the shared readiness classifier from the `orchestrating-datacloud` skill before mutating audience assets: `node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase segment --json`.
+- Prefer reusable JSON definitions for repeatable segment and CI creation.
+- Use `--api-version 64.0` when segment creation behavior is unstable on newer defaults.
+- Verify with counts or SQL after publish/run steps instead of assuming success.
+- Use SQL joins rather than `segment members` when readable member details are needed.
+
+---
+
+## Recommended Workflow
+
+### 1. Classify readiness for segment work
+```bash
+node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase segment --json
+```
+
+### 2. Inspect current state
+```bash
+sf data360 segment list -o <org> 2>/dev/null
+sf data360 calculated-insight list -o <org> 2>/dev/null
+```
+
+### 3. Create with reusable JSON definitions
+```bash
+sf data360 segment create -o <org> -f segment.json --api-version 64.0 2>/dev/null
+sf data360 calculated-insight create -o <org> -f ci.json 2>/dev/null
+```
+
+### 4. Publish or run explicitly
+```bash
+sf data360 segment publish -o <org> --name My_Segment 2>/dev/null
+sf data360 calculated-insight run -o <org> --name Lifetime_Value 2>/dev/null
+```
+
+### 5. Verify with counts or SQL
+```bash
+sf data360 segment count -o <org> --name My_Segment 2>/dev/null
+sf data360 query sql -o <org> --sql 'SELECT COUNT(*) FROM "UnifiedssotIndividualMain__dlm"' 2>/dev/null
+```
+
+---
+
+## High-Signal Gotchas
+
+- Segment creation can require `--api-version 64.0`.
+- `segment members` returns opaque IDs; use SQL joins when human-readable member details are needed.
+- Segment SQL is not SOQL.
+- Calculated insight assets and segment SQL have different limitations.
+- Publish/run steps may kick off asynchronous work even when the command returns quickly.
+- An empty segment or calculated-insight list usually means the module is reachable but unconfigured, not unavailable.
+
+---
+
+## Output Format
+
+```text
+Segment task: <segment / calculated-insight>
+Action: <create / publish / inspect / troubleshoot>
+Target org: <alias>
+Artifacts: <definition files / commands>
+Verification: <member count / query result / publish state>
+Next step: <act / retrieve / follow-up>
+```
+
+---
+
+## References
+
+- [README.md](README.md)
+- [../orchestrating-datacloud/assets/definitions/calculated-insight.template.json](../orchestrating-datacloud/assets/definitions/calculated-insight.template.json)
+- [../orchestrating-datacloud/assets/definitions/segment.template.json](../orchestrating-datacloud/assets/definitions/segment.template.json)
+- [../orchestrating-datacloud/references/feature-readiness.md](../orchestrating-datacloud/references/feature-readiness.md)
+- [../orchestrating-datacloud/UPSTREAM.md](../orchestrating-datacloud/UPSTREAM.md)