Pillar 3 – handler functions

Goal: Understand what handler functions are and learn how to build and apply them.

In our first test codeunit example, the Message statement results in the display of a message box. Unless we want to wait until a user presses the OK button, this message box stays there forever, halting the full execution of our test run. In order to be able to have a fully automated test run, we need a way to deal with any user interactions, such as a message box, a confirm dialog, a report request page, or a modal page.

For this, handler functions, also known as UI handlers, have been conceived. Handler functions are a special type of function that can only be created in test codeunits, and aim at handling UI interactions that exist in the code under test. Handler functions enable us to fully automate tests without the need of a real user to interact with them. As soon as specific UI interactions occur, and a handler has been provided for it, the platform takes care of calling the handler as a substitute for real user interactions.

Test function handler functions are defined by the FunctionType tag. The currently available values are shown in the following screenshot:

Each handler function addresses a different type of user interaction object and needs different parameters to let it interact adequately with the platform. Let VS Code and the AL extension be your guide in finding the right signature for a handler function. The following screenshot shows you the signature of a MessageHandler when you hover over the function name:

In case of a MessageHandler function, the signature is the text the message box would show to the user. Handing over this text to the MessageHandler enables you to determine if the right message was triggered.

So, to get the Message statement handled automatically in our first test codeunit, we should create a MessageHandler function:

[MessageHandler]
 procedure MyMessageHandler(Message: Text[1024])
 begin
 
 end;

But this is only half of the job, as this handler needs to be linked to the test that will execute the code calling Message one way or another. The HandlerFunctions tag is used to do this. Each handler function needs to be called in a Test function and must be added to the HandlerFunctions tag as text. If multiple handlers are needed, these will make up a comma separated string:

HandlerFunctions('Handler1[,Handler2,…]')

Let's apply this to MyFirstTestFunction in a new codeunit and run it:

codeunit 60002 MyThirdTestCodeunit
 {
     Subtype = Test;
 
     [Test]
     [HandlerFunctions('MyMessageHandler')]
     procedure MyFirstTestFunction()
     begin
         Message(MyFirstTestFunction);
     end;
 
     [MessageHandler]
     procedure MyMessageHandler(Message: Text[1024])
     begin
 
     end;
 }

Instantly, rather than showing a message box first, the resume message of the execution of the whole test codeunit is shown: