Loading

Difference between System.Assert and System.AssertEquals

Publish Date: May 15, 2026
Description

This article explains the difference between System.Assert and System.AssertEquals in Salesforce Apex test classes.

  • System.Assert accepts two parameters: a condition to test (mandatory) and an optional message to display if the condition is false. It passes when the condition evaluates to true.
  • System.AssertEquals and System.AssertNotEquals each accept three parameters: the first two (mandatory) are the variables to compare for equality or inequality, and the third (optional) is a message to display if the assertion fails.

Both methods are used in Apex test classes for positive test cases (verifying expected successful outcomes) and negative test cases (verifying that expected errors or validation failures occur correctly), with both single-record and bulk scenarios.

Resolution

Use System.assert and System.assertEquals together in a negative test case to validate DML exception behavior. The following pattern describes how to test that a record with an invalid field value (for example, a mileage value above the 500-mile daily limit) correctly fails with a validation exception.
Run the test in a System.runAs(u3) context to simulate the specific user context. Inside System.runAs, attempt to insert a Mileage__c record with a Miles__c value of 501 (which exceeds the 500-mile limit). Wrap the insert in a try/catch block that catches DmlException.
In the catch block, use three assertions:

  1. System.assert() — Verify that the exception message contains the expected text: 'Insert failed. First exception on row 0; first error: FIELD_CUSTOM_VALIDATION_EXCEPTION, Mileage request exceeds daily limit(500): [Miles__c]'. Pass the actual exception message as the optional second parameter to display it on failure.
  2. System.assertEquals(Mileage__c.Miles__c, e.getDmlFields(0)[0]) — Confirm that the DML field that triggered the exception is Miles__c.
  3. System.assertEquals('FIELD_CUSTOM_VALIDATION_EXCEPTION', e.getDmlStatusCode(0)) — Confirm that the DML status code is FIELD_CUSTOM_VALIDATION_EXCEPTION.

static testMethod void runNegativeTestCases(){
	User u3 = [select id from User where alias='tuser'];     
	System.RunAs(u3)
	{
		System.debug('Inserting a record with 501 miles... (negative test case)');

		Mileage__c testMiles3 = new Mileage__c( Miles__c = 501, Date__c = System.today() );
		try{

			insert testMiles3;

		}catch (DmlException e){

			//Assert Error Message 

			System.assert( e.getMessage().contains('Insert failed. First exception on ' +'row 0; first error:FIELD_CUSTOM_VALIDATION_EXCEPTION,'+'Mileage request exceeds daily limit(500): [Miles__c]'),e.getMessage() );

			//Assert field 

			System.assertEquals(Mileage__c.Miles__c, e.getDmlFields(0)[0]);

			//Assert Status Code 

			System.assertEquals('FIELD_CUSTOM_VALIDATION_EXCEPTION' , e.getDmlStatusCode(0) );

		} //catch 

} //RunAs(u3)
Knowledge Article Number

000382121

 
Loading
Salesforce Help | Article