@salesforce/afv-skills 1.5.1 → 1.5.3

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

@@ -4,26 +4,30 @@
 
 | Method | Use Case |
 |--------|----------|
-| `System.assertEquals(expected, actual, msg)` | Exact equality |
-| `System.assertNotEquals(expected, actual, msg)` | Value should differ |
-| `System.assert(condition, msg)` | Boolean condition |
+| `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 third parameter (message)** - Makes test failures meaningful.
+**Always include the message parameter** — makes test failures actionable.
 
 ## Good vs Bad Assertions
 
-### ❌ Bad: No message, tests coverage not behavior
+### Bad: No message, tests coverage not behavior
 
 ```apex
-System.assertEquals(true, result);
-System.assert(accounts.size() > 0);
+Assert.isTrue(result); // no message
+Assert.isTrue(accounts.size() > 0); // vague — use areEqual with exact count
 ```
 
-### ✅ Good: Descriptive message, tests specific behavior
+### Good: Descriptive message, tests specific behavior
 
 ```apex
-System.assertEquals(true, result, 'Service should return true for valid input');
-System.assertEquals(200, accounts.size(), 'All 200 accounts should be processed');
+Assert.isTrue(result, 'Service should return true for valid input');
+Assert.areEqual(200, accounts.size(), 'All 200 accounts should be processed');
 ```
 
 ## Common Assertion Patterns
@@ -31,25 +35,18 @@ System.assertEquals(200, accounts.size(), 'All 200 accounts should be processed'
 ### Collection Size
 
 ```apex
-// Exact count
-System.assertEquals(200, results.size(), 'Should process all 200 records');
-
-// Not empty
-System.assert(!results.isEmpty(), 'Results should not be empty');
-
-// Empty
-System.assert(results.isEmpty(), 'No results expected for invalid input');
+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
-// Single record
-System.assertEquals('Processed', acc.Status__c, 'Account status should be updated to Processed');
+Assert.areEqual('Processed', acc.Status__c, 'Account status should be updated to Processed');
 
-// All records in collection
 for (Account acc : updatedAccounts) {
-    System.assertEquals('Active', acc.Status__c, 
+    Assert.areEqual('Active', acc.Status__c,
         'Account ' + acc.Name + ' should have Active status');
 }
 ```
@@ -59,21 +56,15 @@ for (Account acc : updatedAccounts) {
 ```apex
 @isTest
 static void shouldThrowException_WhenInputInvalid() {
-    Boolean exceptionThrown = false;
-    String exceptionMessage = '';
-    
     Test.startTest();
     try {
         MyService.process(null);
+        Assert.fail('Expected MyCustomException for null input');
     } catch (MyCustomException e) {
-        exceptionThrown = true;
-        exceptionMessage = e.getMessage();
+        Assert.isTrue(e.getMessage().contains('cannot be null'),
+            'Exception message should mention null input');
     }
     Test.stopTest();
-    
-    System.assert(exceptionThrown, 'MyCustomException should be thrown for null input');
-    System.assert(exceptionMessage.contains('cannot be null'), 
-        'Exception message should mention null input');
 }
 ```
 
@@ -83,83 +74,35 @@ static void shouldThrowException_WhenInputInvalid() {
 // Insert success
 Database.SaveResult[] results = Database.insert(accounts, false);
 for (Database.SaveResult sr : results) {
-    System.assert(sr.isSuccess(), 'Insert should succeed: ' + sr.getErrors());
+    Assert.isTrue(sr.isSuccess(), 'Insert should succeed: ' + sr.getErrors());
 }
 
-// Expected failures
 Database.SaveResult sr = Database.insert(invalidAccount, false);
-System.assert(!sr.isSuccess(), 'Insert should fail for invalid data');
-System.assert(sr.getErrors()[0].getMessage().contains('REQUIRED_FIELD_MISSING'),
+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');
 ```
 
-### Comparing Objects
-
-```apex
-// Compare specific fields, not entire objects
-System.assertEquals(expected.Name, actual.Name, 'Names should match');
-System.assertEquals(expected.Status__c, actual.Status__c, 'Status should match');
-
-// Or use JSON for deep comparison (use sparingly)
-System.assertEquals(
-    JSON.serialize(expected), 
-    JSON.serialize(actual), 
-    'Objects should be identical'
-);
-```
-
-### Date/DateTime Assertions
-
-```apex
-// Exact date
-System.assertEquals(Date.today(), record.CreatedDate__c, 'Should be created today');
-
-// Date within range
-System.assert(record.DueDate__c >= Date.today(), 'Due date should be in the future');
-System.assert(record.DueDate__c <= Date.today().addDays(30), 
-    'Due date should be within 30 days');
-```
-
 ### Null Checks
 
 ```apex
-// Should be null
-System.assertEquals(null, result.ErrorMessage__c, 'No error expected for valid input');
-
-// Should not be null
-System.assertNotEquals(null, result.Id, 'Record should have been inserted');
+Assert.isNull(result.ErrorMessage__c, 'No error expected for valid input');
+Assert.isNotNull(result.Id, 'Record should have been inserted');
 ```
 
-## Anti-Patterns to Avoid
-
-### ❌ Testing implementation, not behavior
+### Date/DateTime
 
 ```apex
-// Bad: Testing that a specific method was called
-System.assert(MyClass.methodWasCalled, 'Method should be called');
-
-// Good: Testing the observable outcome
-System.assertEquals('Expected Value', record.Field__c, 'Field should be updated');
+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');
 ```
 
-### ❌ Overly generic assertions
+## Anti-Patterns
 
-```apex
-// Bad: Passes for any non-empty result
-System.assert(results.size() > 0);
-
-// Good: Verifies exact expected count
-System.assertEquals(200, results.size(), 'All 200 records should be returned');
-```
-
-### ❌ Missing negative test assertions
-
-```apex
-// Bad: Only tests that no exception occurred
-MyService.process(data); // Test passes if no exception
-
-// Good: Verifies the actual outcome
-Result r = MyService.process(data);
-System.assertEquals('Success', r.status, 'Processing should succeed');
-System.assertEquals(0, r.errorCount, 'No errors should occur');
-```
+| 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 |

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

@@ -8,36 +8,33 @@
 
 ### 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() {
-    // Given: Create test data
     List<Account> accounts = TestDataFactory.createAccounts(200, true);
-    
-    // When: Execute batch
+
     Test.startTest();
     MyBatchClass batch = new MyBatchClass();
     Id batchId = Database.executeBatch(batch, 200);
-    Test.stopTest(); // Forces batch to complete
-    
-    // Then: Verify results
+    Test.stopTest();
+
     List<Account> updated = [SELECT Id, Status__c FROM Account];
     for (Account acc : updated) {
-        System.assertEquals('Processed', acc.Status__c, 
+        Assert.areEqual('Processed', acc.Status__c,
             'Batch should update all account statuses');
     }
 }
 ```
 
-### Testing Batch with Failures
+### Batch with Failures
 
 ```apex
 @isTest
 static void shouldLogErrors_WhenRecordsFail() {
-    // Given: Create mix of valid and invalid records
     List<Account> accounts = TestDataFactory.createAccounts(198, true);
-    
-    // Create 2 accounts that will fail processing
+
     List<Account> invalidAccounts = new List<Account>();
     for (Integer i = 0; i < 2; i++) {
         invalidAccounts.add(new Account(
@@ -46,37 +43,20 @@ static void shouldLogErrors_WhenRecordsFail() {
         ));
     }
     insert invalidAccounts;
-    
-    // When
+
     Test.startTest();
     MyBatchClass batch = new MyBatchClass();
-    Database.executeBatch(batch, 50);
+    Database.executeBatch(batch, 200);
     Test.stopTest();
-    
-    // Then
+
     List<Error_Log__c> errors = [SELECT Id, Message__c FROM Error_Log__c];
-    System.assertEquals(2, errors.size(), 'Should log 2 failed records');
+    Assert.areEqual(2, errors.size(), 'Should log 2 failed records');
 }
 ```
 
-### Testing Batch Scope
+### Batch Chaining
 
-```apex
-@isTest
-static void shouldRespectBatchSize() {
-    // Given
-    List<Account> accounts = TestDataFactory.createAccounts(250, true);
-    
-    Test.startTest();
-    MyBatchClass batch = new MyBatchClass();
-    Database.executeBatch(batch, 50); // 5 batches of 50
-    Test.stopTest();
-    
-    // Note: In tests, all batches execute but you can verify total processing
-    List<Account> processed = [SELECT Id FROM Account WHERE Processed__c = true];
-    System.assertEquals(250, processed.size(), 'All records should be processed');
-}
-```
+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
 
@@ -85,70 +65,65 @@ static void shouldRespectBatchSize() {
 ```apex
 @isTest
 static void shouldCompleteProcessing_WhenQueueableEnqueued() {
-    // Given
     Account acc = TestDataFactory.createAccount(true);
-    
-    // When
+
     Test.startTest();
     MyQueueableClass queueable = new MyQueueableClass(acc.Id);
     System.enqueueJob(queueable);
-    Test.stopTest(); // Forces queueable to complete
-    
-    // Then
+    Test.stopTest();
+
     Account updated = [SELECT Id, Status__c FROM Account WHERE Id = :acc.Id];
-    System.assertEquals('Processed', updated.Status__c, 
+    Assert.areEqual('Processed', updated.Status__c,
         'Queueable should update account status');
 }
 ```
 
-### Testing Queueable Chaining
+### Queueable Chaining
 
-Chained queueables only execute the first job in tests:
+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() {
-    // Given: More records than one queueable can process
     List<Account> accounts = TestDataFactory.createAccounts(500, true);
-    
+
     Test.startTest();
-    // First queueable processes batch 1 and chains next
     MyChainedQueueable queueable = new MyChainedQueueable(0, 100);
     System.enqueueJob(queueable);
     Test.stopTest();
-    
-    // Verify first batch processed
+
     List<Account> processed = [SELECT Id FROM Account WHERE Processed__c = true];
-    System.assertEquals(100, processed.size(), 'First batch should process 100 records');
-    
-    // Verify chain was enqueued (check AsyncApexJob)
+    Assert.areEqual(100, processed.size(), 'First batch should process 100 records');
+
     List<AsyncApexJob> jobs = [
-        SELECT Id, Status, JobType 
-        FROM AsyncApexJob 
+        SELECT Id, Status, JobType
+        FROM AsyncApexJob
         WHERE ApexClass.Name = 'MyChainedQueueable'
     ];
-    System.assert(jobs.size() >= 1, 'Chained job should be enqueued');
+    Assert.isTrue(jobs.size() >= 1, 'Chained job should be enqueued');
 }
 ```
 
-### Testing Queueable with Callouts
+### Queueable with Callouts
+
+Set the callout mock **before** `Test.startTest()`:
 
 ```apex
 @isTest
 static void shouldMakeCallout_WhenQueueableWithCallout() {
-    // Given
     Test.setMock(HttpCalloutMock.class, new MockHttpResponse(200, '{"status":"ok"}'));
     Account acc = TestDataFactory.createAccount(true);
-    
-    // When
+
     Test.startTest();
     MyQueueableWithCallout queueable = new MyQueueableWithCallout(acc.Id);
     System.enqueueJob(queueable);
     Test.stopTest();
-    
-    // Then
+
     Account updated = [SELECT Id, External_Status__c FROM Account WHERE Id = :acc.Id];
-    System.assertEquals('Synced', updated.External_Status__c, 
+    Assert.areEqual('Synced', updated.External_Status__c,
         'Should update status after successful callout');
 }
 ```
@@ -158,119 +133,61 @@ static void shouldMakeCallout_WhenQueueableWithCallout() {
 ```apex
 @isTest
 static void shouldExecuteFutureMethod() {
-    // Given
     Account acc = TestDataFactory.createAccount(true);
-    
-    // When
+
     Test.startTest();
-    MyClass.processFuture(acc.Id); // @future method
-    Test.stopTest(); // Forces future to complete
-    
-    // Then
+    MyClass.processFuture(acc.Id);
+    Test.stopTest();
+
     Account updated = [SELECT Id, Processed__c FROM Account WHERE Id = :acc.Id];
-    System.assertEquals(true, updated.Processed__c, 'Future should process record');
+    Assert.isTrue(updated.Processed__c, 'Future should process record');
 }
 ```
 
 ## Scheduled Apex Testing
 
-### Testing Scheduled Execution
+### Direct Execution
 
 ```apex
 @isTest
 static void shouldExecuteScheduledJob() {
-    // Given
     List<Account> accounts = TestDataFactory.createAccounts(50, true);
-    
-    // When
+
     Test.startTest();
-    String cronExp = '0 0 0 1 1 ? 2099'; // Arbitrary future time
-    String jobId = System.schedule('Test Job', cronExp, new MyScheduledClass());
-    
-    // Execute the scheduled job immediately
     MyScheduledClass scheduled = new MyScheduledClass();
-    scheduled.execute(null); // Pass null SchedulableContext in tests
+    scheduled.execute(null);
     Test.stopTest();
-    
-    // Then
+
     List<Account> processed = [SELECT Id FROM Account WHERE Processed__c = true];
-    System.assertEquals(50, processed.size(), 'Scheduled job should process records');
+    Assert.areEqual(50, processed.size(), 'Scheduled job should process records');
 }
 ```
 
-### Testing Schedule Registration
+### CRON Registration
 
 ```apex
 @isTest
 static void shouldScheduleJob() {
     Test.startTest();
-    String cronExp = '0 0 6 * * ?'; // Daily at 6 AM
+    String cronExp = '0 0 6 * * ?';
     String jobId = System.schedule('Daily Processing', cronExp, new MyScheduledClass());
     Test.stopTest();
-    
-    // Verify job is scheduled
+
     CronTrigger ct = [
-        SELECT Id, CronExpression, State 
-        FROM CronTrigger 
+        SELECT Id, CronExpression, State
+        FROM CronTrigger
         WHERE Id = :jobId
     ];
-    System.assertEquals('0 0 6 * * ?', ct.CronExpression, 'CRON should match');
-    System.assertEquals('WAITING', ct.State, 'Job should be waiting');
-}
-```
-
-## Testing Async Limits
-
-```apex
-@isTest
-static void shouldNotExceedQueueableLimits() {
-    // Given: Setup that might enqueue multiple jobs
-    List<Account> accounts = TestDataFactory.createAccounts(100, true);
-    
-    Test.startTest();
-    Integer queueablesBefore = Limits.getQueueableJobs();
-    
-    MyService.processWithQueueables(accounts);
-    
-    Integer queueablesUsed = Limits.getQueueableJobs() - queueablesBefore;
-    Test.stopTest();
-    
-    // Verify limit not exceeded (50 in synchronous context, 1 in queueable)
-    System.assert(queueablesUsed <= 50, 
-        'Should not exceed queueable limit. Used: ' + queueablesUsed);
+    Assert.areEqual('0 0 6 * * ?', ct.CronExpression, 'CRON should match');
+    Assert.areEqual('WAITING', ct.State, 'Job should be waiting');
 }
 ```
 
 ## Common Pitfalls
 
-### ❌ Forgetting Test.stopTest()
-
-```apex
-// Bad: Async never executes
-Test.startTest();
-System.enqueueJob(new MyQueueable());
-// Missing Test.stopTest()!
-
-List<Account> results = [SELECT Id FROM Account WHERE Processed__c = true];
-System.assertEquals(100, results.size()); // FAILS - queueable didn't run
-```
-
-### ❌ Testing chained jobs without understanding limits
-
-```apex
-// Only the FIRST chained queueable runs in tests
-// Design tests to verify:
-// 1. First job completes correctly
-// 2. Chain is properly enqueued (check AsyncApexJob)
-// 3. Each job works independently
-```
-
-### ❌ Not mocking callouts in async
-
-```apex
-// Async with callouts MUST have mock set BEFORE Test.startTest()
-Test.setMock(HttpCalloutMock.class, new MockResponse()); // Before startTest!
-Test.startTest();
-System.enqueueJob(new QueueableWithCallout());
-Test.stopTest();
-```
+| 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` |