Platform Events Developer Guide
jNewer Version Available
Deliver Test Event Messages
Deliver Test Event Messages After Test.stopTest()
To publish platform event messages in an Apex test, enclose the publish statements within Test.startTest() and Test.stopTest() statements. Call the EventBus.publish() method within the Test.startTest() and Test.stopTest() statements. In test context, the EventBus.publish() method enqueues the publish operation. The Test.stopTest() statement causes the event publishing to be carried out and event messages to be delivered to the test event bus. Include your validations after the Test.stopTest() statement. For example, you can validate that a subscribed Apex trigger or a subscribed flow Pause element has performed the expected actions, like creating a Salesforce record.
Example
This sample test class contains two test methods. The testValidEvent() method checks that the event was successfully published and fires the associated trigger. The testInvalidEvent() method verifies that publishing an event with a missing required field fails, and no trigger is fired. The testValidEvent() method creates one Low_Ink__e event. After Test.stopTest(), it executes a SOQL query to verify that a case record is created, which means that the trigger was fired. The second test method follows a similar process but for an invalid test.
This example requires that the Low_Ink__e event and the associated trigger are defined in the org.
Deliver Test Event Messages on Demand with Test.getEventBus().deliver()
You can control when test event messages are delivered to subscribers by calling Test.getEventBus().deliver(). Use Test.getEventBus().deliver() to deliver test event messages multiple times, and verify that subscribers have processed the test events each step of the way. Delivering event messages multiple times is useful for testing sequential processing of events. For example, you can verify sequential actions of a subscriber in a loop within the same test.
Enclose Test.getEventBus().deliver() within the Test.startTest() and Test.stopTest() statement block.
Also, you can call Test.getEventBus().deliver() in an Apex test method outside the Test.startTest() and Test.stopTest() statement block. Doing so enables you to test event messages with asynchronous Apex.
Deliver Test Event Messages Published from Asynchronous Apex
When testing a batch Apex job that publishes BatchApexErrorEvent on failure, use the Test.startTest() and Test.stopTest() statement block with Test.getEventBus().deliver(). The Test.stopTest() call ensures that the asynchronous Apex job executes after this statement. Next, Test.getEventBus().deliver() delivers the event message that the failed batch job published.
This snippet shows how to execute a batch Apex job and deliver event messages. It executes the batch job after Test.stopTest(). This batch job publishes a BatchApexErrorEvent message when a failure occurs through the implementation of Database.RaisesPlatformEvents. After Test.stopTest() runs, a separate Test.getEventBus().deliver() statement is added so that it can deliver the BatchApexErrorEvent.
Asynchronous Apex also includes queueable Apex and future methods. If a platform event message is published from within those async Apex jobs, they’re delivered after Test.stopTest(). It’s not necessary to add Test.getEventBus().deliver();. The next example shows how to deliver a platform event message that a queueable Apex job publishes. After Test.stopTest(), the queueable job is executed and the event message is delivered.
Example: Deliver Event Messages Individually
This test class publishes an Order_Event__e event message and delivers it using Test.getEventBus().deliver(). It verifies that the trigger processed the event message and created a task. A duplicate event message (an event with the same Event_ID__c custom field value) is published and delivered. The test verifies that the trigger didn’t create a task for the duplicate event.
Before you can run this test class, define a platform event with the name of Order_Event__e and these fields: Event_ID__c of type Text, Order_Number__c of type Text, Has_Shipped__c of type Checkbox. Also, in the OrderTrigger trigger, replace the user Name field value in the SOQL query with a user’s full name in your Salesforce org, such as John Smith.
This example trigger processes Order_Event__e event messages that the test class publishes.
Fail the Publishing of Event Messages to Test Apex Publish Callbacks
Apex publish callbacks contain the final result of asynchronous EventBus.publish calls. To test your Apex publish callback class, you can simulate the failure of a publish call with Test.getEventBus().fail().
In an Apex test, event messages are published synchronously in the test event bus. To can simulate the execution of the callback methods in a test, you can deliver or fail the publishing of the event messages. This section covers the failure of event publishing.
The Test.getEventBus().fail() method causes the publishing of events to fail immediately after the call and event messages are removed from the test event bus. This method causes the onFailure() method in the callback class to be invoked. When the event messages fail to publish, none of the triggers defined on the platform event receive any failed events.
This example class is a test class for the FailureAndSuccessCallback class that is given in Get the Result of Asynchronous Platform Event Publishing with Apex Publish Callbacks. This test class shows how to test the failed delivery of test event messages in the test event bus. Before you run this test class, define a platform event in Setup with the label Order Event and a Text field of Order Number.
To deliver event messages successfully, check out these sections.