@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/handling-sf-data/references/anonymous-apex-guide.md

@@ -0,0 +1,98 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Anonymous Apex Guide
+
+Using anonymous Apex for complex data operations.
+
+## When to Use Anonymous Apex
+
+- Complex data setup requiring Apex logic
+- Testing triggers with specific data patterns
+- One-time data migrations
+- Debugging and troubleshooting
+
+## sf CLI Execution
+
+### From File
+```bash
+sf apex run --file setup-data.apex --target-org myorg
+```
+
+### Interactive
+```bash
+sf apex run --target-org myorg
+# Then type Apex code and press Ctrl+D
+```
+
+## Common Patterns
+
+### Bulk Data Creation
+```apex
+List<Account> accounts = new List<Account>();
+for (Integer i = 0; i < 500; i++) {
+    accounts.add(new Account(
+        Name = 'Test Account ' + i,
+        Industry = 'Technology'
+    ));
+}
+insert accounts;
+System.debug('Created ' + accounts.size() + ' accounts');
+```
+
+### Data Transformation
+```apex
+List<Account> accounts = [
+    SELECT Id, Name, Industry
+    FROM Account
+    WHERE Name LIKE 'Old%'
+];
+
+for (Account acc : accounts) {
+    acc.Name = acc.Name.replace('Old', 'New');
+}
+
+update accounts;
+```
+
+### Testing Trigger Logic
+```apex
+// Setup test data
+Account acc = new Account(Name = 'Trigger Test');
+insert acc;
+
+// Force trigger to fire
+acc.Industry = 'Technology';
+update acc;
+
+// Verify results
+acc = [SELECT Id, Field__c FROM Account WHERE Id = :acc.Id];
+System.debug('Result: ' + acc.Field__c);
+```
+
+## Error Handling
+
+```apex
+try {
+    insert accounts;
+} catch (DmlException e) {
+    System.debug('Error: ' + e.getMessage());
+    for (Integer i = 0; i < e.getNumDml(); i++) {
+        System.debug('Row ' + e.getDmlIndex(i) + ': ' + e.getDmlMessage(i));
+    }
+}
+```
+
+## Limits in Anonymous Apex
+
+| Limit | Value |
+|-------|-------|
+| SOQL Queries | 100 |
+| DML Rows | 10,000 |
+| CPU Time | 10,000 ms |
+| Heap Size | 6 MB |
+
+## Best Practices
+
+1. **Test in sandbox first** - Validate before production
+2. **Add debug statements** - Track progress
+3. **Handle errors gracefully** - Use try/catch
+4. **Keep scripts idempotent** - Safe to re-run

package/skills/handling-sf-data/references/bulk-operations-guide.md

@@ -0,0 +1,94 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Bulk Operations Guide
+
+When and how to use Salesforce Bulk API operations.
+
+## Decision Matrix
+
+| Record Count | Recommended API | Command |
+|--------------|-----------------|---------|
+| 1-10 | Single Record | `sf data create record` |
+| 11-2000 | Standard API | `sf data query` + Apex |
+| 2000-10M | Bulk API 2.0 | `sf data import bulk` |
+| 10M+ | Data Loader | External tool |
+
+## Bulk API 2.0 Commands
+
+### Import (Insert)
+```bash
+sf data import bulk \
+  --file accounts.csv \
+  --sobject Account \
+  --target-org myorg \
+  --wait 30
+```
+
+### Update
+```bash
+sf data update bulk \
+  --file updates.csv \
+  --sobject Account \
+  --target-org myorg \
+  --wait 30
+```
+
+### Upsert (Insert or Update)
+```bash
+sf data upsert bulk \
+  --file upsert.csv \
+  --sobject Account \
+  --external-id External_Id__c \
+  --target-org myorg \
+  --wait 30
+```
+
+### Delete
+```bash
+sf data delete bulk \
+  --file delete.csv \
+  --sobject Account \
+  --target-org myorg \
+  --wait 30
+```
+
+### Export
+```bash
+sf data export bulk \
+  --query "SELECT Id, Name FROM Account" \
+  --output-file accounts.csv \
+  --target-org myorg \
+  --wait 30
+```
+
+## CSV Format Requirements
+
+- First row: Field API names
+- UTF-8 encoding
+- Comma delimiter (default)
+- Max 100MB per file
+
+## Bulk API Limits
+
+| Limit | Value |
+|-------|-------|
+| Batches per 24 hours | 10,000 |
+| Records per 24 hours | 10,000,000 |
+| Max file size | 100 MB |
+| Max concurrent jobs | 100 |
+
+## Error Handling
+
+```bash
+# Check job status
+sf data resume --job-id [job-id] --target-org myorg
+
+# Get results
+sf data bulk results --job-id [job-id] --target-org myorg
+```
+
+## Best Practices
+
+1. **Chunk large files** - Split files >100MB
+2. **Use --wait** - Monitor completion
+3. **Handle partial failures** - Check result files
+4. **Test in sandbox** - Validate before production

package/skills/handling-sf-data/references/bulk-testing-example.md

@@ -0,0 +1,194 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Bulk Testing Example
+
+Testing Apex triggers and flows with bulk data operations.
+
+## Scenario
+
+Test an Account trigger that:
+- Fires on insert with 200+ records
+- Updates a custom field based on Industry
+- Creates a related Task for high-value accounts
+
+## Why 201 Records?
+
+Salesforce processes triggers in batches of 200. Testing with 201+ records ensures:
+- Trigger handles batch boundaries
+- No governor limit violations in loops
+- SOQL/DML operations are bulkified
+
+## Method 1: Anonymous Apex Factory
+
+### Create Test Data
+```apex
+// Create 251 Accounts to test trigger bulkification
+List<Account> accounts = new List<Account>();
+
+List<String> industries = new List<String>{
+    'Technology', 'Healthcare', 'Finance', 'Manufacturing', 'Retail'
+};
+
+for (Integer i = 0; i < 251; i++) {
+    accounts.add(new Account(
+        Name = 'BulkTest Account ' + i,
+        Industry = industries[Math.mod(i, industries.size())],
+        AnnualRevenue = Math.round(Math.random() * 10000000)
+    ));
+}
+
+// Single DML - triggers fire in batches of 200
+insert accounts;
+
+System.debug('Created ' + accounts.size() + ' accounts');
+System.debug('SOQL Queries Used: ' + Limits.getQueries() + '/' + Limits.getLimitQueries());
+System.debug('DML Statements: ' + Limits.getDmlStatements() + '/' + Limits.getLimitDmlStatements());
+```
+
+Save as `bulk-test-accounts.apex` and run:
+```bash
+sf apex run --file bulk-test-accounts.apex --target-org dev
+```
+
+## Method 2: CSV Bulk Import
+
+### Create CSV File
+```csv
+Name,Industry,AnnualRevenue
+BulkTest Account 1,Technology,1000000
+BulkTest Account 2,Healthcare,2000000
+BulkTest Account 3,Finance,5000000
+... (251 rows)
+```
+
+### Import via sf CLI
+```bash
+sf data import bulk \
+  --file accounts-bulk.csv \
+  --sobject Account \
+  --target-org dev \
+  --wait 30
+```
+
+## Method 3: JSON Tree Import
+
+For hierarchical test data with relationships:
+
+```json
+{
+  "records": [
+    {
+      "attributes": {"type": "Account", "referenceId": "AccountRef1"},
+      "Name": "BulkTest Parent 1",
+      "Industry": "Technology",
+      "Contacts": {
+        "records": [
+          {
+            "attributes": {"type": "Contact"},
+            "FirstName": "Test",
+            "LastName": "Contact 1"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+```bash
+sf data import tree \
+  --files bulk-hierarchy.json \
+  --target-org dev
+```
+
+## Verify Trigger Executed Correctly
+
+### Check Trigger Results
+```bash
+sf data query \
+  --query "SELECT Id, Name, Industry, Custom_Field__c FROM Account WHERE Name LIKE 'BulkTest%' LIMIT 10" \
+  --target-org dev \
+  --json
+```
+
+### Check Related Tasks Created
+```bash
+sf data query \
+  --query "SELECT Id, Subject, WhatId, What.Name FROM Task WHERE What.Name LIKE 'BulkTest%'" \
+  --target-org dev
+```
+
+### Count Records
+```bash
+sf data query \
+  --query "SELECT COUNT(Id) total FROM Account WHERE Name LIKE 'BulkTest%'" \
+  --target-org dev
+```
+
+## Test Bulk Update
+
+```apex
+// Update all test records - triggers fire again
+List<Account> accounts = [
+    SELECT Id, Name, Industry
+    FROM Account
+    WHERE Name LIKE 'BulkTest%'
+];
+
+for (Account acc : accounts) {
+    acc.Description = 'Bulk updated on ' + DateTime.now();
+}
+
+update accounts;
+
+System.debug('Updated ' + accounts.size() + ' accounts');
+```
+
+## Test Bulk Delete
+
+```apex
+// Delete in reverse order (children first)
+List<Task> tasks = [SELECT Id FROM Task WHERE What.Name LIKE 'BulkTest%'];
+delete tasks;
+
+List<Contact> contacts = [SELECT Id FROM Contact WHERE Account.Name LIKE 'BulkTest%'];
+delete contacts;
+
+List<Account> accounts = [SELECT Id FROM Account WHERE Name LIKE 'BulkTest%'];
+delete accounts;
+
+System.debug('Cleanup complete');
+```
+
+## Governor Limits Monitoring
+
+```apex
+// Add to your test script to monitor limits
+System.debug('=== GOVERNOR LIMITS ===');
+System.debug('SOQL: ' + Limits.getQueries() + '/' + Limits.getLimitQueries());
+System.debug('DML Statements: ' + Limits.getDmlStatements() + '/' + Limits.getLimitDmlStatements());
+System.debug('DML Rows: ' + Limits.getDmlRows() + '/' + Limits.getLimitDmlRows());
+System.debug('CPU Time: ' + Limits.getCpuTime() + 'ms/' + Limits.getLimitCpuTime() + 'ms');
+System.debug('Heap: ' + Limits.getHeapSize() + '/' + Limits.getLimitHeapSize());
+```
+
+## Validation Score
+
+```
+Score: 128/130 ⭐⭐⭐⭐⭐ Excellent
+├─ Query Efficiency: 25/25 (bulk queries)
+├─ Bulk Safety: 25/25 (251 records, limits monitored)
+├─ Data Integrity: 20/20 (valid field values)
+├─ Security & FLS: 20/20 (no sensitive data)
+├─ Test Patterns: 15/15 (201+ records, variations)
+├─ Cleanup & Isolation: 13/15 (cleanup script provided)
+└─ Documentation: 10/10 (fully documented)
+```
+
+## Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `SOQL 101` | Query in loop | Use Map or Set for bulk queries |
+| `DML 151` | DML in loop | Collect records, single DML |
+| `CPU timeout` | Complex logic | Optimize loops, async processing |
+| `Too many records` | >10,000 DML rows | Use Bulk API or Batch Apex |

package/skills/handling-sf-data/references/cleanup-rollback-example.md

@@ -0,0 +1,322 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Cleanup and Rollback Examples
+
+Strategies for test data isolation and proper cleanup.
+
+## Method 1: Savepoint/Rollback
+
+Best for synchronous operations in a single transaction.
+
+### Basic Pattern
+```apex
+// Create savepoint BEFORE any DML
+Savepoint sp = Database.setSavepoint();
+
+try {
+    // Create test data
+    Account acc = new Account(Name = 'Test Account');
+    insert acc;
+
+    Contact con = new Contact(
+        FirstName = 'Test',
+        LastName = 'Contact',
+        AccountId = acc.Id
+    );
+    insert con;
+
+    // Perform operations
+    MyClass.processAccount(acc);
+
+    // Assert results
+    acc = [SELECT Custom_Field__c FROM Account WHERE Id = :acc.Id];
+    System.assert(acc.Custom_Field__c != null, 'Field should be populated');
+
+} finally {
+    // ALWAYS rollback - even on success
+    Database.rollback(sp);
+}
+
+// Data is now completely removed
+```
+
+### In Unit Tests
+```apex
+@isTest
+static void testWithRollback() {
+    Savepoint sp = Database.setSavepoint();
+
+    try {
+        // Create 1000 test records
+        List<Account> accounts = new List<Account>();
+        for (Integer i = 0; i < 1000; i++) {
+            accounts.add(new Account(Name = 'Rollback Test ' + i));
+        }
+        insert accounts;
+
+        // Run business logic
+        Test.startTest();
+        BatchProcessor.process(accounts);
+        Test.stopTest();
+
+        // Assertions
+        Integer count = [SELECT COUNT() FROM Account WHERE Name LIKE 'Rollback Test%'];
+        System.assertEquals(1000, count);
+
+    } finally {
+        Database.rollback(sp);
+    }
+
+    // Verify cleanup
+    Integer remaining = [SELECT COUNT() FROM Account WHERE Name LIKE 'Rollback Test%'];
+    System.assertEquals(0, remaining, 'All records should be rolled back');
+}
+```
+
+### Limitations
+- **Does NOT rollback async operations** (future, queueable, batch)
+- Maximum 5 savepoints per transaction
+- Cannot rollback across transaction boundaries
+
+## Method 2: Cleanup by Name Pattern
+
+Best when savepoint isn't possible (async tests, multi-transaction).
+
+### Single Object Cleanup
+```apex
+// Delete all test accounts
+List<Account> toDelete = [
+    SELECT Id FROM Account
+    WHERE Name LIKE 'Test%'
+    LIMIT 10000
+];
+delete toDelete;
+```
+
+### Multi-Object Cleanup (Correct Order)
+```apex
+// CRITICAL: Delete children before parents!
+String testPattern = 'Test%';
+
+// 1. Delete grandchildren first
+delete [SELECT Id FROM Task WHERE What.Name LIKE :testPattern];
+delete [SELECT Id FROM Event WHERE What.Name LIKE :testPattern];
+
+// 2. Delete children
+delete [SELECT Id FROM Opportunity WHERE Account.Name LIKE :testPattern];
+delete [SELECT Id FROM Contact WHERE Account.Name LIKE :testPattern];
+delete [SELECT Id FROM Case WHERE Account.Name LIKE :testPattern];
+
+// 3. Delete parents last
+delete [SELECT Id FROM Account WHERE Name LIKE :testPattern];
+
+System.debug('Cleanup complete');
+```
+
+### sf CLI Cleanup
+```bash
+# Query records to delete
+sf data query \
+  --query "SELECT Id FROM Account WHERE Name LIKE 'Test%'" \
+  --target-org dev \
+  --result-format csv \
+  > delete-accounts.csv
+
+# Bulk delete
+sf data delete bulk \
+  --file delete-accounts.csv \
+  --sobject Account \
+  --target-org dev \
+  --wait 30
+```
+
+## Method 3: Cleanup by Time Window
+
+Best for cleaning up after a specific test run.
+
+### By CreatedDate
+```apex
+// Clean up records created in the last hour
+DateTime startTime = DateTime.now().addHours(-1);
+String testPattern = 'Test%';
+
+delete [
+    SELECT Id FROM Account
+    WHERE CreatedDate >= :startTime
+    AND Name LIKE :testPattern
+];
+```
+
+### With Timestamp Tracking
+```apex
+// At start of test - capture timestamp
+DateTime testStartTime = DateTime.now();
+
+// ... run tests ...
+
+// Cleanup - only records created during this test
+delete [
+    SELECT Id FROM Account
+    WHERE CreatedDate >= :testStartTime
+    AND Name LIKE 'Test%'
+];
+```
+
+## Method 4: ID-Based Cleanup
+
+Most precise - track exactly what you created.
+
+### Track IDs During Creation
+```apex
+// Collection to track all created record IDs
+Set<Id> createdAccountIds = new Set<Id>();
+Set<Id> createdContactIds = new Set<Id>();
+Set<Id> createdOppIds = new Set<Id>();
+
+// Create and track
+List<Account> accounts = TestDataFactory_Account.create(100);
+createdAccountIds.addAll(new Map<Id, Account>(accounts).keySet());
+
+List<Contact> contacts = TestDataFactory_Contact.createForAccounts(createdAccountIds, 3);
+createdContactIds.addAll(new Map<Id, Contact>(contacts).keySet());
+
+// ... run tests ...
+
+// Cleanup exactly what we created
+delete [SELECT Id FROM Contact WHERE Id IN :createdContactIds];
+delete [SELECT Id FROM Account WHERE Id IN :createdAccountIds];
+```
+
+### Wrapper Class for Tracking
+```apex
+public class TestDataTracker {
+    private Map<String, Set<Id>> trackedIds = new Map<String, Set<Id>>();
+
+    public void track(SObject record) {
+        String objType = record.getSObjectType().getDescribe().getName();
+        if (!trackedIds.containsKey(objType)) {
+            trackedIds.put(objType, new Set<Id>());
+        }
+        trackedIds.get(objType).add(record.Id);
+    }
+
+    public void trackAll(List<SObject> records) {
+        for (SObject rec : records) {
+            track(rec);
+        }
+    }
+
+    public void cleanup() {
+        // Delete in reverse dependency order
+        List<String> deleteOrder = new List<String>{
+            'Task', 'Event', 'Opportunity', 'Contact', 'Case', 'Account'
+        };
+
+        for (String objType : deleteOrder) {
+            if (trackedIds.containsKey(objType)) {
+                Set<Id> ids = trackedIds.get(objType);
+                String query = 'SELECT Id FROM ' + objType + ' WHERE Id IN :ids';
+                delete Database.query(query);
+            }
+        }
+    }
+}
+
+// Usage
+TestDataTracker tracker = new TestDataTracker();
+
+List<Account> accounts = TestDataFactory_Account.create(100);
+tracker.trackAll(accounts);
+
+List<Contact> contacts = TestDataFactory_Contact.create(50);
+tracker.trackAll(contacts);
+
+// ... run tests ...
+
+// Clean up everything tracked
+tracker.cleanup();
+```
+
+## Method 5: @testSetup Isolation
+
+Automatic rollback with @isTest annotation.
+
+```apex
+@isTest
+public class MyTestClass {
+
+    @testSetup
+    static void setup() {
+        // This data is automatically rolled back after ALL tests complete
+        List<Account> accounts = TestDataFactory_Account.create(100);
+    }
+
+    @isTest
+    static void testMethod1() {
+        // Access setup data
+        List<Account> accounts = [SELECT Id FROM Account];
+        // Modify data - changes rolled back after this test
+        delete accounts[0];
+    }
+
+    @isTest
+    static void testMethod2() {
+        // Fresh copy of @testSetup data - all 100 accounts available
+        List<Account> accounts = [SELECT Id FROM Account];
+        System.assertEquals(100, accounts.size());
+    }
+}
+```
+
+## Cleanup via sf CLI
+
+### Generate Cleanup CSV
+```bash
+# Export IDs of test records
+sf data query \
+  --query "SELECT Id FROM Account WHERE Name LIKE 'Test%'" \
+  --target-org dev \
+  --result-format csv \
+  > cleanup-accounts.csv
+
+sf data query \
+  --query "SELECT Id FROM Contact WHERE Account.Name LIKE 'Test%'" \
+  --target-org dev \
+  --result-format csv \
+  > cleanup-contacts.csv
+```
+
+### Execute Bulk Delete
+```bash
+# Delete children first
+sf data delete bulk \
+  --file cleanup-contacts.csv \
+  --sobject Contact \
+  --target-org dev \
+  --wait 30
+
+# Then delete parents
+sf data delete bulk \
+  --file cleanup-accounts.csv \
+  --sobject Account \
+  --target-org dev \
+  --wait 30
+```
+
+## Best Practices Summary
+
+| Method | Best For | Limitations |
+|--------|----------|-------------|
+| Savepoint/Rollback | Synchronous tests | No async, max 5 savepoints |
+| Name Pattern | Ad-hoc cleanup | May delete unintended records |
+| Time Window | Post-test cleanup | Needs accurate timestamp |
+| ID Tracking | Precise cleanup | Requires tracking discipline |
+| @testSetup | Unit tests | Only in @isTest classes |
+| sf CLI Bulk | Large volumes | External tool required |
+
+## Golden Rules
+
+1. **Always delete children before parents** - Respect relationships
+2. **Use specific patterns** - 'Test%', 'BulkTest%' to avoid accidents
+3. **Verify before delete** - Query first to see what will be deleted
+4. **Test cleanup in sandbox** - Never run unverified cleanup in prod
+5. **Track created IDs** - Most reliable cleanup method