Generating Apex Tests

Core Principles

1. One behavior per method — each test method validates a single scenario. Separate positive, negative, and bulk tests. NEVER combine related-but-distinct inputs (e.g., null and empty) in one method — create

   _NullInput_

   and

   _EmptyInput_

   as separate test methods
2. Bulkify tests — test with 251+ records to cross the 200-record trigger batch boundary. Batch Apex exception: in test context only one

   execute()

   invocation runs, so set

   batchSize >= testRecordCount

   . See references/async-testing.md
3. Isolate test data — every

   @TestSetup

   must delegate record creation to a

   TestDataFactory

   class. If none exists, create one first. Never build record lists inline in

   @TestSetup

   . Never rely on org data (

   SeeAllData=false

   ) or hardcoded IDs. For duplicate rule handling, see references/test-data-factory.md
4. Assert meaningfully — use exact expected values computed from test data setup. NEVER use range assertions or approximate counts when the value is deterministic. Always include failure messages. See references/assertion-patterns.md
5. Use

   Assert

   class only —

   Assert.areEqual

   ,

   Assert.isTrue

   ,

   Assert.fail

   , etc. Never use legacy

   System.assert

   ,

   System.assertEquals

   , or

   System.assertNotEquals

6. Mock external boundaries — use

   HttpCalloutMock

   for callouts,

   Test.setFixedSearchResults

   for SOSL, DML mock classes for database isolation. Design for testability via constructor injection. See references/mocking-patterns.md
7. Test negative paths — validate error handling and exception scenarios, not just happy paths
8. Wrap with start/stop — pair

   Test.startTest()

   with

   Test.stopTest()

   to reset governor limits and force async execution

Test.startTest() / Test.stopTest()

Test.startTest()

Test.stopTest()

• Resets governor limits so the test measures only the code under test
• Executes async operations synchronously (queueables, batch, future methods)
• Fires scheduled jobs immediately

Test Code Anti-Patterns

Map<Id, SObject>

Exception

DmlException

Workflow

Step 1 — Gather Context

• the target production class(es) under test
• existing test classes, test data factories, and setup helpers
• desired test scope (single class, specific methods, suite, or local tests)
• coverage threshold (75% minimum for deploy, 90%+ recommended)
• org alias when running tests against an org

Step 2 — Generate the Test Class

1. {ClassName}Test.cls

   — the test class (use assets/test-class-template.cls as starting point)

2. {ClassName}Test.cls-meta.xml

   — the metadata file:

<?xml version="1.0" encoding="UTF-8"?>
<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>66.0</apiVersion>
    <status>Active</status>
</ApexClass>

TestDataFactory

TestDataFactory.cls

TestDataFactory.cls-meta.xml

@TestSetup Example

@TestSetup
static void setupTestData() {
    List<Account> accounts = TestDataFactory.createAccounts(251, true);
}

Test Method Structure

@isTest
static void shouldUpdateStatus_WhenValidInput() {
    // Given
    List<Account> accounts = [SELECT Id FROM Account];

    // When
    Test.startTest();
    MyService.processAccounts(accounts);
    Test.stopTest();

    // Then
    List<Account> updated = [SELECT Id, Status__c FROM Account];
    Assert.areEqual(251, updated.size(), 'All accounts should be processed');
}

Negative Test — Exception Pattern

Assert.fail

@isTest
static void shouldThrowException_WhenInvalidInput() {
    // Given
    List<Account> emptyList = new List<Account>();

    // When/Then
    Test.startTest();
    try {
        MyService.processAccounts(emptyList);
        Assert.fail('Expected MyCustomException to be thrown');
    } catch (MyCustomException e) {
        Assert.isTrue(e.getMessage().contains('cannot be empty'),
            'Exception message should indicate empty input');
    }
    Test.stopTest();
}

Naming Convention

• should[ExpectedResult]_When[Scenario]

  :

  shouldSendNotification_WhenOpportunityClosedWon

• [SubjectOrAction]_[Scenario]_[ExpectedResult]

  :

  AccountUpdate_ChangeName_Success

Step 3 — Run Tests

# Single test class
sf apex run test --class-names MyServiceTest --result-format human --code-coverage --target-org <alias>

# Specific test methods
sf apex run test --tests MyServiceTest.shouldUpdateStatus_WhenValidInput --result-format human --target-org <alias>

# All local tests
sf apex run test --test-level RunLocalTests --result-format human --code-coverage --target-org <alias>

Step 4 — Analyze Results

• failing methods — exception types and stack traces
• uncovered lines and weak coverage areas
• whether failures indicate bad test data, brittle assertions, or broken production logic

Step 5 — Fix Loop

1. Read the failing test class and the class under test
2. Identify root cause from error messages and stack traces
3. Apply fix — adjust test data or assertions for test-side issues; delegate production code issues to the

   generating-apex

   skill
4. Rerun the focused test before broader regression
5. Repeat until all tests pass, iteration limit reached, or root cause requires design change

Step 6 — Validate Coverage

What to Test by Component

Database.Stateful

finish()

Database.executeBatch()

UnexpectedException

Test.startTest()

WITH USER_MODE

System.runAs

execute(null)

CronTrigger

Test.enableChangeDataCapture()

Test.getEventBus().deliver()

Output Expectations

• {ClassName}Test.cls

  +

  {ClassName}Test.cls-meta.xml

  (match API version of class under test; default

  66.0

  )

• TestDataFactory.cls

  +

  TestDataFactory.cls-meta.xml

  (if not already present)

Reference Files